Batch Jobs

Batch jobs are conversions which have co-dependencies; for example, a conversion that can only be performed after another one has been run.

This section describes:

• why you might need to use them
• how to create a new batch
• how to run a batch to produce conversions
• the similarities with normal conversion jobs

Conversion Dependencies

Sometimes a conversion may be dependent on another. Typically this is where you want to apply more than once edit or modification to the same content, or a particular conversion requires input in a format which is itself the output of another conversion. For example, not all conversions can operate on the format of the canonical content.

Create a New Batch

To create a new batch, invoke the method createContentConvertBatch

Example

<soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:createConvertBatchRequest
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
    
<clientApplicationId>petshow</clientApplicationId>  
<clientApplicationCredentials>Wf</clientApplicationCredentials>
   
</ns2:createConvertBatchRequest>
</soap:Body>
</soap:Envelope>

Example Response

<soap:Envelope   
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
   
<ns2:createConvertBatchRequest
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<batchId>1025</batchId>
     
<status>200</status>
   
</ns2:createConvertBatchRequest>
  </soap:Body>
</soap:Envelope>

Create Content Batch Fields

You must supply your Client Application ID & Credentials, see Client Application ID & Credentials for details

Create Content Batch Response

The reponse returns one of the following status codes:

Adding Jobs to the Batch

A successful batch creation returns a unique ID for this batch. You can add jobs to the batch by specifying this batch ID in the batchParameters element of a conversion request.

For example:

<batchParameters>
            <batchId>19202</batchId>
            <prerequisiteJobId>19204</prerequisiteJobId>
            <prerequisiteJobId>19205</prerequisiteJobId>
</batchParameters>

Note that, in order to set up the prerequisites correctly, you must submit the prerequisite conversions first-because you need to know their job IDs.

Be careful not to specify prerequisite jobs that depend upon each other. It is possible to create a batch that will lock indefinitely if you do this.

To see this in the context of a conversion request, see Batch Parameters.

Start Conversion Batch

After you have created a batch, and added all the jobs (some of which will be perquisites), you can start the batch in order to execute the conversions it contains.

Issue a startContentConvertBatchRequest with the following parameters.

Start Conversion Batch Fields

To start a batch, you need to provide client application details and the batch ID.

Client Application ID & Credentials

Starting batches in yospaceCDS is restricted in the same way as uploading content. See Client Application ID & Credentials for details.

Batch ID

Use the batch ID the was provided in the response to the original create request.

Start Conversion Batch Response

The status code returned by the start batch request can have one of these values:

Once the batch has been started, the jobs within it will be removed from the queue only when the whole batch has completed. Jobs are only processed when their prerequisite jobs have been completed.

Results from Batch Conversions

Notifications from jobs that are part of a batch are handled in exactly the same way as normal conversion jobs-see Conversion Completion Notification for details.

Note that starting the batch does not cause the first job to be immediately executed-it just makes the batch's jobs available on the queue. They will be taken from the queue in the same way as normal conversions. For this reason, just like submitting a single conversion job, there may be a delay before the conversion is performed, depending on the load on yospaceCDS at the time.

Batch Failure Modes - (R1.11 and above)

Release 1.11 introduced the possibility to indicate to yospaceCDS what it should do in the event that jobs within your batch fail. There are two failure modes that are supported.

• BRANCH where all jobs dependent on the failed job are automatically failed and notified (if you have specified failure notification URLs in your submit requests). 
• ALL fails all outstanding jobs within the batch, regardless of whether they were dependent on the failed job or not. This excludes jobs that are currently in operation. Like the BRANCH mode, all failed jobs are notified provided that you have specified a failure notification URL.

To indicate which failure mode to use, on the method createContentConvertBatch set the parameter batchFailureMode to one of either BRANCH or ALL. If you do not specify a mode, the default is BRANCH.

Example

<soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:createConvertBatchRequest
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
    
<clientApplicationId>petshow</clientApplicationId>  
<clientApplicationCredentials>Wf</clientApplicationCredentials>
<batchFailureMode>ALL</batchFailureMode>
</ns2:createConvertBatchRequest>
</soap:Body>
</soap:Envelope>