Batch REST API

REST API in a distributed server batch environment

While the REST API operations are issued by a client against a single server, the target or scope of these operations can target multiple servers. The scope includes the set of servers that are configured to use the same database-backed job repository. Specific operations with special behaviors such as redirection are described in the following sections that describe the STOP, JOBLOGS, and purge requests in a distributed server batch environment.

REST API with a user ID that is only a submitter

The results that are returned by the GET ("read") URLs will be filtered when the user ID that invokes the REST API over HTTPS has only been granted access to the batchSubmitter role. The submitter sees only instance and execution data that is associated with job instances that were submitted by the submitter. In contrast, user IDs granted access to the batchAdmin and batchMonitor roles are able to view all instance and execution data (returned by any given URL with any given set of parameters).

A user ID that has access only to the batchSubmitter role sees results that are first filtered by the standard parameters as described in the documentation of the given URL. Further filtered is then done by returning only instance and execution data associated with job instances submitted by the submitter himself.

For more information, see Securing the Liberty batch environment.

Job instances

GET /ibm/api/batch/jobinstances/

This URI returns a list of job instances. Query parameters include:

• page=[page number]: Indicates which page (subset of records) to return. The default is 0.
• pageSize=[number of records per page]: Indicates the number of records per page. The default is 50.

Sample requests:

https://localhost:9443/ibm/api/batch/jobinstances

https://localhost:9443/ibm/api/batch/jobinstances?page=13&pagesize=20

Sample response:

[
    {
        "jobName":"test_sleepyBatchlet",
        "instanceId":7,
        "appName":"SimpleBatchJob#SimpleBatchJob.war",
        "submitter":"bob",
        "batchStatus":"COMPLETED",
        "jobXMLName":"test_sleepyBatchlet",
        "instanceState":"COMPLETED",
        "_links":[
            {
                "rel":"self",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/7"
            },
            {
                "rel":"job logs",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/7/joblogs"
            }
        ]
    },
    {
        "jobName":"test_sleepyBatchlet",
        "instanceId":6,
        "appName":"SimpleBatchJob#SimpleBatchJob.war",
        "submitter":"bob",
        "batchStatus":"COMPLETED",
        "jobXMLName":"test_sleepyBatchlet",
        "instanceState":"COMPLETED",
        "_links":[
            {
                "rel":"self",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/6"
            },
            {
                "rel":"job logs",
                "href":"https://localhost:9443/ibm/api/batch/jobinstances/6/joblogs"
            }
        ]
    }
]

GET /ibm/api/batch/v2/jobinstances/

This URI returns a list of job instances filtered by the following query parameters:

• jobInstanceId=[instanceId]:[instanceId]: Returns job instances equal to and between the instanceId range.
• jobInstanceId=>[instanceId]: Returns job instances equal to and greater than the provided instanceId.
• jobInstanceId=<[instanceId]: Returns job instances equal to and less than the provided instanceId.
• jobinstanceId=[instanceId],[instanceId],[instanceId]: Returns job instances specified.
• createTime=[yyyy-MM-dd]:[yyy-MM-dd]: Returns job instances between the date range inclusively.
• createTime=[yyyy-MM-dd]: Returns job instances on the given date.
• createTime=>3d: Returns job instances that were created on or after the day that was three days ago. For example, the createTime is greater than or equal to the beginning of the day three days ago.
• createTime=<3d: Returns job instances that were created on or before the day that was three days ago. For example, the createTime is less than or equal to the end of the day three days ago.
• instanceState=[state],[state]: Returns job instances with the provided state. Valid Instance States are SUBMITTED, JMS_QUEUED, JMS_CONSUMED, DISPATCHED, FAILED, STOPPED, COMPLETED, and ABANDONED.
• exitStatus=[string]: Returns job instances that match the exit status string. The string criteria can use the wildcard (*) operator anywhere in the string.
• page=[page number]: Indicates which page (subset of records) to return. The default is 0.
• pageSize=[number of records per page]: Indicates the number of records per page. The default is 50.

Note: The role of the server default time zone in queries involving createTime

When you submit a job, the createTime for the job instance is stored in the job repository and normalized to UTC. When you specify dates by using yyyy-MM-dd, as in createTime=[yyyy-MM-dd] or createTime=[yyyy-MM-dd]:[yyy-MM-dd]:, then you must convert the yyyy-MM-dd date string into a specific range of UTC times to match against the createTime values in the job instance table records. To do this function, the application uses the default time zone of the server that is handling the REST request. It is this server's time zone that is used to convert the date string into a UTC time range that it is matched against.

The following table illustrates data that is returned by the query parameters jobInstanceId=10:13.

JOBINSTANCEID	CREATETIME(* in server1's time zone)	INSTANCESTATE	EXITSTATUS
10	11-05-2015.01:10:00	COMPLETED	SUCCESS
11	11-08-2014.02:20:00	COMPLETED	SUCCESS
12	11-10-2015.03:30:00	FAILED	FAILURE
13	11-11-2015:04:40:00	COMPLETED	SUCCESS

*Since the job repository stores the createTime in a UTC format, it is important to understand that the table data shows the createTime formatted by using the server's default time zone of a particular server, for example, "server1". If we had constructed a similar table from the perspective of a second server with a different default time zone (than "server1"), the table would show a different set of CREATETIME column values which a corresponding timezone-based difference. It is the default time zone of the server that is handling the REST request that is used to map yyyy-MM-dd date string parameters to UTC createTime values in the database in the following examples.

The following commands return the same result regardless of which server they are issued against:

• jobInstanceId=11:13 would return JOBINSTANCEID's 11, 12 and 13.
• jobInstanceId=>12 would return JOBINSTANCEID's 12 and 13.
• jobInstanceId=<12 would return JOBINSTANCEID's 11 and 12.
• jobInstanceId=11,12 would return JOBINSTANCEID's 11 and 12.
• instanceState=FAILED would return JOBINSTANCEID 12..
• exitStatus=SUCCESS would return JOBINSTANCEID's 10, 11 and 13.

The following commands may return different results against servers with different default time zones. In these examples, they are issued against "server1" (the same server that was used to populate the previous table) at date and time: 11-11-2015:07:00:00 in the server's default time zone.

• createTime=>2d would return JOBINSTANCEID's 12 and 13 (on or after 2 days ago, which was 11-09-2015)
• createTime=<2d would return JOBINSTANCEID's 10 and 11 (on or before 2 days ago, which was 11-09-2015)
• createTime=2015-11-08:2015-11-11 would return records with JOBINSTANCEID's 11,12, and 13.
• createTime=2015-11-10 would return record with JOBINSTANCEID 12.

Sample requests:

https://localhost:9443/ibm/api/batch/v2/jobinstances?jobInstanceId=20:50
https://localhost:9443/ibm/api/batch/jobinstances?createTime=>2d
https://localhost:9443/ibm/api/batch/v2/jobinstances?jobInstanceId=4,12,17&instanceState=COMPLETED
https://localhost:9443/ibm/api/batch/v2/jobinstances?jobInstanceId=4500:4600&createTime=2015-11-27&instanceState=COMPLETED&exitStatus=*JOB*&page=0&pageSize=1000

GET /ibm/api/batch/v3/jobinstances/

In addition to all of the functions of the GET /ibm/api/batch/v2/job instances/ URI, this URI returns a list of job instances filtered by the following query parameters:

• lastUpdatedTime=[yyyy-MM-dd]: Returns job instances that were last updated on the given date. This time value is updated on transitions of instance state. For example, from SUBMITTED to DISPATCHED.
• jobParameter.[paramName]=[paramValue]: Returns job instances with executions that have the supplied name:value pair as a job parameter. For example: jobParameter.jesJobName=myJobName. The string criteria can use the wildcard (*) operator anywhere in the string.
• sort=[string],[string]: Specifies the parameter or parameters to sort of the results by. Using the - character to prefix the parameter specifies that sorting will be done in descending order. For example,sort=submitter sorts the results by submitter in ascending order. Specifying sort=submitter,-lastUpdatedTime sorts the results first by submitter in ascending order, and then by lastUpdatedTime, in descending order.

GET /ibm/api/batch/v4/jobinstances/

In addition to all of the functions of the GET /ibm/api/batch/v3/job instances/ URI, this URI returns a list of job instances filtered by the following query parameters:

• submitter=[user]: Returns all job instances that were submitted by the specified user. The string criteria can use the wildcard (*) operator anywhere in the string.
• appName=[name]: Returns all job instances with the specified application name. This can be either the simple application name, or the full app-module-component name. For example, a search for either MyApp or MyApp#MyApp.war will return a job instance with an application name of MyApp and module name of MyApp.war. The string criteria can use the wildcard (*) operator anywhere in the string.
• jobName=[name]: Returns all job instances with the specified job name. The string criteria can use the wildcard (*) operator anywhere in the string.
• ignoreCase=true: By default, all text matching is case-sensitive. Specifying this option changes all text search terms to not be case sensitive.
• lastUpdatedTime=[yyyy-MM-dd]:[yyyy-MM-dd]: Returns job instances that were last updated between the date range inclusively.
• lastUpdatedTime=>3d: Returns job instances that were last updated on or after the day that was three days ago. For example, the lastUpdatedTime is greater than or equal to the beginning of the day three days ago.
• lastUpdatedTime=<3d: Returns job instances that were last updated on or before the day that was three days ago. For example, the lastUpdatedTime is less than or equal to the end of the day three days ago.

Note: The appName, exitStatus, jobName, and submitter parameters can be applied more than once. The result includes all job instances that match and of the supplied values. For example, specifying jobinstances?submitter=Alice&submitter=Bob returns all job instances submitted by Alice OR Bob.

GET /ibm/api/batch/jobinstances/job instance id

This URI returns detailed information about the specified job instance such as all executions that are associated with a specified job instance. Results are returned in order from most recent to the oldest. The most recent result is displayed first in the list.

Sample response:

{
    "jobName":"test_sleepyBatchlet",
    "instanceId":7,
    "appName":"SimpleBatchJob#SimpleBatchJob.war",
    "submitter":"bob",
    "batchStatus":"COMPLETED",
    "jobXMLName":"test_sleepyBatchlet",
    "instanceState":"COMPLETED",
    "_links":[
        {
            "rel":"self",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/7"
        },
        {
            "rel":"job logs",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/7/joblogs"
        },
        {
            "rel":"job execution",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/7/jobexecutions/7"
        }
    ]
}

POST /ibm/api/batch/jobinstances/

Use this URI to submit (start) a new job.

The following example illustrates the request body for submitting a job that is packaged in a WAR module, in JSON formatting:

{ 
  "applicationName" : "SimpleBatchJob",
  "moduleName" : "SimpleBatchJob.war",
  "jobXMLName" : "test_batchlet_jsl",
  "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"}
}

The following example illustrates the request body for submitting a job that is packaged in an EJB module, in JSON formatting:

{ 
  "applicationName" : "SimpleBatchJob",
  "moduleName" : "SimpleBatchJobEJB.jar",
  "componentName" : "MyEJB",
  "jobXMLName" : "test_batchlet_jsl",
  "jobParameters" : { "prop1" : "prop1value", "prop2" : "prop2value"}
}

The applicationName identifies the batch application. It is required unless moduleName is specified, in which case the applicationName is derived from the moduleName by trimming off the .war or .jar suffix of the moduleName. For example, if you provide no applicationName and moduleName=SimpleBatchJob.war, then applicationName defaults to SimpleBatchJob.

The moduleName identifies the module within the batch application that contains the job artifacts, such as the JSL. The job is submitted under the module's component context. The moduleName is required unless applicationName is specified, in which case the moduleName is derived from the applicationName by appending .war to the applicationName. For example, if you provide applicationName=SimpleBatchJob and no moduleName, then moduleName defaults to SimpleBatchJob.war.

The componentName identifies the EJB component within the batch application EJB module. If specified, the job is submitted under the EJB's component context.

Note: The componentName is required only when the module is an EJB module. When the module is a WAR module, the componentName is not required.

You must enter a value for jobXMLName. The value for jobParameters is optional.

As an alternative to using the JSL job definition that is packaged within your batch application under META-INF/batch-jobs, you can pass your JSL inline as part of your REST job submission request. The JSL that is submitted inline always overrides any JSL that is packaged with the batch application. You can use two methods to submit your JSL inline as part of your HTTP request.

1. Include your JSL as a JSON property in your job submission request. Add the property jobXML to the JSON object and add the entire content of the JSL file as a JSON string as the value of the property.
   Note: You must properly escape the XML string so it can be parsed by a JSON parser. Most JSON libraries do this function for you.
   The following example illustrates the request body for submitting a job that uses a single part HTTP request with the JSL being passed in-line by the JSON.

   {
     "applicationName":"SimpleBatchJob",
     "jobXMLName":"test_multiPartition_3Steps",
     "jobXML":"<?xml version=\"1.0\" encoding=\"UTF-8\" 
   standalone=\"yes\"?>
     \r\n<job id=\"test_multiPartition_3Steps\"
     xmlns=\"http://xmlns.jcp.org/xml/ns/javaee\"r\n\tversion=\"1.0>
     \r\n\t<step id=\"step1"\" next=\"step2\">
     \r\n\t\t<batchlet ref=\"simpleBatchlet\"/>
     \r\n\t\t<partition>\r\n\t\t\t<plan  partitions=\"3\"/>
     \r\n\t\t</partition>\r\n\t</step>
     \r\n\t<step  id=\"step2\" next=\"step3\">
     \r\n\t\t<batchlet ref=\"simpleBatchlet\" />
     \r\n\t\t<partition>\r\n\t\t\t<plan  partitions=\"3\" />
     \r\n\t\t</partition>\r\n\t</step>\r\n\t<step  id=\"step3\">
     \r\n\t\t<batchlet ref=\"simpleBatchlet\" />\r\n\t\t<partition>
     \r\n\t\t\t<plan partitions=\"3\"/>
     \r\n\t\t</partition>\r\n\t</step>\r\n</job>"
   }

   Note: The jobXML field must be parsed by a JSON parser and marshalled into a valid JSON object. The jobXMLName field is optional, as the job ID information in the inline JSL is used for the job name.
2. Use an HTTP multi-part form. When you use an HTTP multipart form, the JSON job submission data and XML job definition need to be submitted as two separate parts of the HTTP body. The JSON part of the multi-part form must be named jobdata and the XML part of the form must be named jsl. The XML does not need to be marshalled to a JSON string when you use a multi-part form.
   The following example illustrates the HTTP request for submitting a job that uses a multi-part HTTP request with the JSL being passed inline by way of the jsl message part.

   Content-Type: multipart/form-data;boundary=---------------------------49424d5f4a4241544348
   
   -----------------------------49424d5f4a4241544348
   Content-Disposition: form-data; name="jobdata"
   Content-Type: application/json; charset=UTF-8
   {  
     "applicationName" : "SimpleBatchJob", 
     "moduleName" : "SimpleBatchJob.war",  
     "jobXMLName" : "test_multiPartition"
   }
   
   -----------------------------49424d5f4a4241544348
   Content-Disposition: form-data; name="jsl" 
   Content-Type: application/xml; charset=UTF-8
   
   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <job id="test_multiPartition" xmlns="http://xmlns.jcp.org/xml/ns/javaee"
   version="1.0">
   <step id="step1">
   <batchlet ref="simpleBatchlet" />
   <partition>    
     <plan partitions="3" />    
     </partition>
   </step>
   </job>
   
   -----------------------------49424d5f4a4241544348--
       

   Note: The jobXMLName field is optional, as the job ID information in the inline JSL is used for the job name.

The following sample response illustrates a successful job submission:

{
    "jobName": "test_sleepyBatchlet",
    "instanceId": 10,
    "appName": "SimpleBatchJob#SimpleBatchJob.war",
    "submitter": "bob",
    "batchStatus": "STARTING",
    "jobXMLName": "test_sleepyBatchlet",
    "instanceState": "SUBMITTED",
    "_links": [
        {
            "rel": "self",
            "href": "https://localhost:9443/ibm/api/batch/jobinstances/10"
        },
        {
            "rel": "job logs",
            "href": "https://localhost:9443/ibm/api/batch/jobinstances/10/joblogs"
        }
    ]
}

PUT /ibm/api/batch/jobinstances/job instance id?action=stop

Use this URI to stop the most recent job execution that is associated with this job instance if it is running. If it is not, the API returns an error.

PUT /ibm/api/batch/jobinstances/job instance id?action=restart

Use this URI to restart the most recent job execution that is associated with this job instance only if it is in STOPPED or FAILED state. If no job execution is associated with this instance, or the most recent job execution is in COMPLETED state, the API returns an error.

PUT /ibm/api/batch/jobinstances/job instance id?action=restart&reusePreviousParams=true

Use this URI to restart the most recent job execution and reuse the job parameters from the previous execution that is associated with this job instance. The previous execution must be in STOPPED or FAILED state. If no job execution is associated with this instance, or the most recent job execution is in COMPLETED state, then the API returns an error. Note that reusePreviousParams is an optional setting. The default setting is reusePreviousParams=false.

Note: When reusePreviousParams=true, any job parameters that are submitted as part of the current restart request take precedence over any previous job parameters. Current parameters override previous parameters with the same job parameter key name.

DELETE /ibm/api/batch/jobinstances/job instance id

This URI purges all database entries and job logs that are associated with this job instance. This API returns an error if the job instance has active job executions. If there is an error when you delete the job logs, then no attempt is made to delete the job instance data from the job store database. Query parameters include:

• purgeJobStoreOnly=true|false: When purgeJobStoreOnly=true, no attempt is made to purge the job logs associated with this job instance. The default setting is purgeJobStoreOnly=false. This API returns an error if the job instance has active job executions.
  Note: No purge response message is returned when you use the single purge API.

DELETE /ibm/api/batch/v2/jobinstances/

This URI purges all database entries and job logs associated with the job instances returned by the following purge filter parameters:

Note: It is recommended that you use the GET interface to list out the jobs and verify that they are the correct jobs to purge before you perform the DELETE interface to purge them.

• page=[page number]: Indicates which page (subset of records) to return. The default is 0
• pageSize=[number of records per page]: Indicates the number of records per page. The default is 50.
• purgeJobStoreOnly=true|false: When purgeJobStoreOnly=true, no attempt is made to purge the job logs associated with this job instance. The default setting is purgeJobStoreOnly=false. This API returns an error if the job instance has active job executions.
• jobInstanceId=[instanceId]:[instanceId]: Purges job instances equal to and between the instanceId range.
• jobInstanceId=>[instanceId]: Purges job instances equal to and greater than the provided instanceId.
• jobInstanceId=<[instanceId]: Purges job instances equal to and less than the provided instanceId.
• jobinstanceId=[instanceId],[instanceId],[instanceId]: Purges job instances specified.
• createTime=[yyyy-MM-dd]:[yyy-MM-dd]: Returns job instances between the date range inclusively.
• createTime=[yyyy-MM-dd]: Returns job instances on the given date.
• createTime=>3d: Returns job instances that were created on or after the day that was three days ago. For example, the createTime is greater than or equal to the beginning of the day three days ago.
• createTime=<3d: Returns job instances that were created on or before the day that was three days ago. For example, the createTime is less than or equal to the end of the day three days ago.
• instanceState=[state],[state]: Purges job instances with the provided state. Valid Instance States are SUBMITTED, JMS_QUEUED, JMS_CONSUMED, DISPATCHED, FAILED, STOPPED, COMPLETED, and ABANDONED.
• exitStatus=[string]: Returns job instances that match the exit status string. The string criteria may use the wildcard(*) operator on either end.

Note: By default, unless the page and pageSize parameters are specified, a maximum of 50 records are purged.

Note: The role of the server default time zone in queries involving createTime

When you submit a job, the createTime for the job instance is stored in the job repository and normalized to UTC. When you specify dates via yyyy-MM-dd, as in createTime=[yyyy-MM-dd] or createTime=[yyyy-MM-dd]:[yyy-MM-dd]:, then you must convert the yyyy-MM-dd date string into a specific range of UTC times to match against the createTime values in the job instance table records. To do this, the application uses the default time zone of the server that is handling the REST request. It is this server's time zone that is used to convert the date string into a UTC time range that it is matched against.

The following table illustrates data that is returned by the query parameters jobInstanceId=10:13.

JOBINSTANCEID	CREATETIME(* in server1's time zone)	INSTANCESTATE	EXITSTATUS
10	11-05-2015.01:10:00	COMPLETED	SUCCESS
11	11-08-2014.02:20:00	COMPLETED	SUCCESS
12	11-10-2015.03:30:00	FAILED	FAILURE
13	11-11-2015:04:40:00	COMPLETED	SUCCESS

*Since the job repository stores the createTime in a UTC format, it is important to understand that the table data shows the createTime formatted by using the server's default time zone of a particular server, for example, "server1". If we had constructed a similar table from the perspective of a second server with a different default time zone (than "server1"), the table would show a different set of CREATETIME column values which a corresponding timezone-based difference. It is the default time zone of the server that is handling the REST request that is used to map yyyy-MM-dd date string parameters to UTC createTime values in the database in the following examples.

The following commands return the same result regardless of which server they are issued against:

• jobInstanceId=11:13 would return JOBINSTANCEID's 11, 12 and 13.
• jobInstanceId=>12 would return JOBINSTANCEID's 12 and 13.
• jobInstanceId=<12 would return JOBINSTANCEID's 11 and 12.
• jobInstanceId=11,12 would return JOBINSTANCEID's 11 and 12.
• instanceState=FAILED would return JOBINSTANCEID 12..
• exitStatus=SUCCESS would return JOBINSTANCEID's 10, 11 and 13.

The following commands may return different results against servers with different default time zones. In these examples, they are issued against "server1" (the same server that was used to populate the previous table) at date and time: 11-11-2015:07:00:00 in the server's default time zone.

• createTime=>2d would return JOBINSTANCEID's 12 and 13 (on or after 2 days ago, which was 11-09-2015)
• createTime=<2d would return JOBINSTANCEID's 10 and 11 (on or before 2 days ago, which was 11-09-2015)
• createTime=2015-11-08:2015-11-11 would return records with JOBINSTANCEID's 11,12, and 13.
• createTime=2015-11-10 would return record with JOBINSTANCEID 12.

Sample response:

[{"instanceId":394,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":395,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":396,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":397,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""},
{"instanceId":398,"purgeStatus":"COMPLETED","message":"Successful purge.","redirectUrl":""}]

The following purgeStatus values can be returned:

COMPLETED

Indicates that the job purge completed successfully.

FAILED

Indicates that the job purge failed.

STILL_ACTIVE

Indicates that the job purge failed because it was still active.

JOBLOGS_ONLY

Indicates that the database purge failed, but that the job logs were successfully purged.

NOT_LOCAL

Indicates that the job purge failed because the job is not local.

Job executions

GET /ibm/api/batch/jobexecutions/job execution id

This URI returns detailed information about a specified job execution and includes links to associated step executions and job logs.

Sample request:

https://localhost:9443/ibm/api/batch/jobexecutions/9

Sample response:

{
    "jobName":"test_sleepyBatchlet",
    "executionId":9,
    "instanceId":9,
    "batchStatus":"COMPLETED",
    "exitStatus":"COMPLETED",
    "createTime":"2015/05/07 16:09:41.025 -0400",
    "endTime":"2015/05/07 16:09:52.127 -0400",
    "lastUpdatedTime":"2015/05/07 16:09:52.127 -0400",
    "startTime":"2015/05/07 16:09:41.327 -0400",
    "jobParameters":{
    },
    "restUrl":"https://localhost:9443/ibm/api/batch",
    "serverId":"localhost/C:/ibm/RAD_workspaces/Liberty7/build.image/wlp/usr/server1",
    "logpath":"C:\\ibm\\Liberty\\wlp\\usr\\servers\\server1\\logs\\joblogs\\test_sleepyBatchlet\\2015-05-07\\instance.9\\execution.9\\",
    "stepExecutions":[
        {
            "stepExecutionId":9,
            "stepName":"step1",
            "batchStatus":"COMPLETED",
            "exitStatus":"SleepyBatchlet:i=10;stopRequested=false",
            "stepExecution":"https://localhost:9443/ibm/api/batch/jobexecutions/9/stepexecutions/step1"
        }
    ],
    "_links":[
        {
            "rel":"self",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9"
        },
        {
            "rel":"job instance",
            "href":"https://localhost:9443/ibm/api/batch/jobinstances/9"
        },
        {
            "rel":"step executions",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9/stepexecutions"
        },
        {
            "rel":"job logs",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9/joblogs"
        },
        {
            "rel":"stop url",
            "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9?action=stop"
        }
    ]
}

GET /ibm/api/batch/jobexecutions/job execution id/jobinstance

This URI returns detailed information about the job instance related to the specified job execution.

GET /ibm/api/batch/jobinstances/job instance id/jobexecutions

This URI returns detailed information about the job execution(s) for a specified job instance. This includes links to associated step executions and job logs.

GET /ibm/api/batch/jobinstances/job instance id/jobexecutions/job execution sequence number

This URI returns detailed information about the specified job execution in relation to the specified job instance ID. This includes links to associated step executions and job logs.

Note: The job execution sequence number means the 0th, 1st, 2nd, etc. job execution related to the specified job instance.

PUT /ibm/api/batch/jobexecutions/job execution id?action=stop

Use this URI to stop the specified running job execution. Required parameters include action = stop, restart.

PUT /ibm/api/batch/jobexecutions/job execution id?action=restart

Use this URI to restart the specified job execution. Required parameters include action = stop, restart.

Step executions

GET /ibm/api/batch/jobexecutions/job execution id/stepexecutions

This URI returns a JSON array of all the step execution details for the specified job execution. If your job contains a partitioned step, the partition information is returned listed within each step.

Sample request:

https://localhost:8020/ibm/api/batch/jobexecutions/40/stepexecutions

The following sample illustrates a response for a partitioned step.

[ 
   { 
      "stepExecutionId":47,
      "executionId":39,
      "instanceId":35,
      "stepName":"step1",
      "batchStatus":"COMPLETED",
      "startTime":"2015/03/30 11:10:08.652 -0400",
      "endTime":"2015/03/30 11:10:09.817 -0400",
      "exitStatus":"COMPLETED",
      "metrics":{ 
         "READ_COUNT":"0",
         "WRITE_COUNT":"0",
         "COMMIT_COUNT":"0",
         "ROLLBACK_COUNT":"0",
         "READ_SKIP_COUNT":"0",
         "PROCESS_SKIP_COUNT":"0",
         "FILTER_COUNT":"0",
         "WRITE_SKIP_COUNT":"0"
      },
      "partitions":[ 
         { 
            "partitionNumber":0,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:09.579 -0400",
            "endTime":"2015/03/30 11:10:09.706 -0400",
            "exitStatus":"step1",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":1,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:09.257 -0400",
            "endTime":"2015/03/30 11:10:09.302 -0400",
            "exitStatus":"step1",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":2,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:09.469 -0400",
            "endTime":"2015/03/30 11:10:09.548 -0400",
            "exitStatus":"step1",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         }
      ]
   },
   { 
      "stepExecutionId":51,
      "executionId":39,
      "instanceId":35,
      "stepName":"step2",
      "batchStatus":"COMPLETED",
      "startTime":"2015/03/30 11:10:09.915 -0400",
      "endTime":"2015/03/30 11:10:10.648 -0400",
      "exitStatus":"COMPLETED",
      "metrics":{ 
         "READ_COUNT":"0",
         "WRITE_COUNT":"0",
         "COMMIT_COUNT":"0",
         "ROLLBACK_COUNT":"0",
         "READ_SKIP_COUNT":"0",
         "PROCESS_SKIP_COUNT":"0",
         "FILTER_COUNT":"0",
         "WRITE_SKIP_COUNT":"0"
      },
      "partitions":[ 
         { 
            "partitionNumber":0,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:10.324 -0400",
            "endTime":"2015/03/30 11:10:10.417 -0400",
            "exitStatus":"step2",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":1,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:10.260 -0400",
            "endTime":"2015/03/30 11:10:10.347 -0400",
            "exitStatus":"step2",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         { 
            "partitionNumber":2,
            "batchStatus":"COMPLETED",
            "startTime":"2015/03/30 11:10:10.507 -0400",
            "endTime":"2015/03/30 11:10:10.557 -0400",
            "exitStatus":"step2",
            "metrics":{ 
               "READ_COUNT":"0",
               "WRITE_COUNT":"0",
               "COMMIT_COUNT":"0",
               "ROLLBACK_COUNT":"0",
               "READ_SKIP_COUNT":"0",
               "PROCESS_SKIP_COUNT":"0",
               "FILTER_COUNT":"0",
               "WRITE_SKIP_COUNT":"0"
            }
         },
         {
            "_links":[
            {
               "rel":"job execution",
               "href":"https://localhost:9443/ibm/api/batch/jobexecutions/9"
            },
            {
               "rel":"job instance",
               "href":"https://localhost:9443/ibm/api/batch/jobinstances/9"
            }
        ]
    }
] 

GET /ibm/api/batch/jobexecutions/job execution id/stepexecutions/step name

This URI returns a JSON array that contains the step execution details for the specified job execution and step name.

GET /ibm/api/batch/jobinstances/job instance id/jobexecutions/job execution sequence number/stepexecutions/step name

This URI returns a JSON array that contains the step execution details for the specified job instance, job execution, and step name.

GET /ibm/api/batch/stepexecutions/step execution id

This URI returns a JSON array that contains the step execution details for the specified step execution.

Job logs

GET /ibm/api/batch/jobinstances/job instance id/joblogs

This URI returns a JSON array with REST links to all job log parts for the specified job instance.

GET /ibm/api/batch/jobexecutions/job execution id/joblogs

This URI returns a JSON array with REST links to all job log parts for the specified job execution.

Important: The following example shows the format of the REST links.

If your job execution has the following job log parts,

joblogs/instance.inst-id/execution.exec-id/part.1.log
joblogs/instance.inst-id/execution.exec-id/part.2.log
joblogs/instance.inst-id/execution.exec-id/step.step-name/partition.0/part.1.log
joblogs/instance.inst-id/execution.exec-id/step.step-name/partition.1/part.1.log

then the corresponding REST links are:

/ibm/api/batch/jobexecutionsexec-id/joblogs?part=part.1.log
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=part.2.log
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=step.step-name/partition.0/part.1.log
/ibm/api/batch/jobexecutionsexec-id/joblogs?part=step.step-name/partition.1/part.1.log

Optional parameters include:

type = text

Text returns all job logs as plain text. All job log parts are aggregated together. Part delimiting header and footer records are inserted into the stream to delimit the different parts as they are aggregated together.

type = zip

Zip returns all job logs for the specified job instance or job execution as a compressed file. The directory structure of the job logs is preserved in the compressed file.

GET /ibm/api/batch/jobinstances/job instance id/joblogs?type=text|zip

GET /ibm/api/batch/jobexecutions/job execution id/joblogs?type=text|zip

The behavior of these two URIs with the type parameter specified varies by value.

type = text

Text returns all job logs as plain text. All job log parts are aggregated together. Part delimiting header and footer records are inserted into the stream to delimit the different parts as they are aggregated together.

type = zip

Zip returns all job logs for the specified job instance or job execution as a compressed file. The directory structure of the job logs is preserved in the compressed file.

GET /ibm/api/batch/jobexecutions/job execution id/joblogs?part=path to part&type=text|zip

With the part parameter specified, this URI returns job log parts as either plain text (type=text) or in a compressed file (type=zip). The default setting is type=text.

HTTP Return Codes

STOP requests in a distributed server batch environment

Stop requests sent to the batch REST API must be sent directly to the executor where the job is running. If a stop request is sent to a dispatcher or executor where the job is not running, the request is redirected to the correct executor by an HTTP 302 redirection response message. The location field in the HTTP 302 redirection response indicates the correct URL to use for the stop request.

JOBLOGS requests in a distributed server batch environment

Purge requests in a distributed server batch environment