Executing a job (Job class operations)

This sample session walks you through the basics of executing a job. Note that this session uses operations from the Job class. There are similar operations available for installing/uninstalling applications using the Component Template class. For more information, see Installing-or-uninstalling-an-application-Component-Template-class.

• To execute a job
• Example job request and response
• Using asynchronous job notification
• Available operations and arguments (Job class)
• Argument formats

To execute a job

1. Find out what operations are available. To do this, you can use the following URI syntax:
   /type/PropertySetClasses/SystemObject/Job
   Browser example:

   https://myAppServer:9843/type/PropertySetClasses/SystemObject/Job
   ?username=myName&password=myPassword&role=myRole

   This returns a list of available operations. For convenience, a sample list of available operations is included in Available operations and arguments (Job class).

2. Within your client, construct an HTTP POST request.

This POST request contains a URI that specifies the job and the operation.

• Job: You can specify the job by using the /id prefix or by using the /group prefix.

• Operation: You specify the operation by ending the URI with the string "Operations/ <operation_name>"
  For example:

  /id/SystemObject/Job/SnapshotJob/d163b519-4c1d-4830-9972-87386a7e0c8f/
  Operations/execute
  urlConnection.setRequestProperty("Accept", "text/xml");
  /group/Jobs/MyJobs/job1/Operations/executeAgainstServers

  If the operation takes arguments, provide them as data in the POST request. For information about how to do this using the various argument formats, see Argument formats.

Example job request and response

Suppose you want to invoke the following URI:
/group/Jobs/myJobGroup/myJob/Operations/executeAgainstServers
This example shows you how to invoke it against two servers.

1. The executeAgainstServers  operation takes one argument (list of the URIs of the servers you want to execute against). In addition, you need to pass the name of this one argument (servers) and this argument's type. There are a number of ways to create this request--here is one sample way:

   private String createServerArgument(List<String> uris) throws JSONException, IOException
   {
   StringWriter writer = new StringWriter();
   JSONWriter jsonWriter = new JSONWriter(writer);
   jsonWriter.object();
   jsonWriter.key("OperationArguments");
   jsonWriter.array();
   jsonWriter.object();
   jsonWriter.key("name");
   jsonWriter.value("servers");
   jsonWriter.key("type");
   jsonWriter.value("/type/PropertySetClasses/SystemObject/Server");
   jsonWriter.key("uris");
   jsonWriter.array();
   for(String uri : uris)
   {
   jsonWriter.value(uri);
   }
   jsonWriter.endArray();
   jsonWriter.endObject();
   jsonWriter.endArray();
   jsonWriter.endObject();
   writer.close();
   String data = writer.toString();
   return data;
   }

   This creates the following data, which you include in the POST request that executes the job:
   Request:

   {
   "OperationArguments":[
   {
   "name":"servers",
   "type":"\/type\/PropertySetClasses\/SystemObject\/Server",
   "uris":["URI1","URI2"]}
   ]
   }
   

2. After the job executes, it returns an OperationResultResponse, which looks something like this:
   Response:

   {
      "OperationResultResponse":{
          "OperationResult":{
              "type":"String",
              "value":"/id/SystemObject/Job/{job_type}/{job_guid}/Status/{Status_Token}"
          }
      }
   }

3. If you perform a GET on the URI contained in this response, you get a StatusResponse, which looks something like this:

   {
   "StatusResponse":{
   "Status":{
   "name":"Status3",
   "status":"COMPLETE",
   "uri":"\/id\/SystemObject\/Job\/Update Server Properties Job\/
   95eb1d98-25a4-4212-94a1-17b65768d8f7\/Statuses\/Status3",
   "targetURI":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-
   8b50-2c545ab4e907",
   "hadErrors":"false",
   "hadWarnings":"true",
   "isAbort":"false"
   }
   }
   }

4. The uri entry is the same URI you used to get this StatusResponse. targetURI provides more detailed information about the job run. If you perform a GET on targetURI, you get a PropertySetInstanceResponse, which looks something like this:

   "PropertySetInstanceResponse":{
          "PropertySetInstance":{
              "name":"Run at Wed Aug 04 15:07:50 EDT 2010",
              "type":"\/type\/PropertySetClasses\/SystemObject\/Job Run",
              "description":"",
              "dbKey":"DBKey:SJobRunModelKeyImpl:3-2000129",
              "objectId":"a3c0f3e9-bc90-4e15-8b50-2c545ab4e907",
              "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907",
              "modelType":"UPDATE_SERVER_PROPERTY_JOB_RUN",
              "modelTypeId":"386",
              "PropertyValues":{
                  "totalCount":"24",
                  "Elements":[
                      {
                          "name":"HAD_ERRORS",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/HAD_ERRORS"
                      },
                      {
                          "name":"IS_ABORTED",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/IS_ABORTED"
                      },
                      {
                          "name":"IS_RUNNING",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/IS_RUNNING"
                      },
                      {
                          "name":"USER_MODIFIED",
                          "type":"String",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/USER_MODIFIED"
                      },
                      {
                          "name":"USER_CREATED",
                          "type":"String",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/USER_CREATED"
                      },
                      {
                          "name":"IS_RESET",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/IS_RESET"
                      },
                      {
                          "name":"IS_CANCELLED",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/IS_CANCELLED"
                      },
                      {
                          "name":"ROLE_CREATED",
                          "type":"String",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/ROLE_CREATED"
                      },
                      {
                          "name":"DATE_MODIFIED",
                          "type":"Date",
                          "value":"2010\/08\/04 15:07:53-0400",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/DATE_MODIFIED"
                      },
                      {
                          "name":"NAME",
                          "type":"String",
                          "value":"Run at Wed Aug 04 15:07:50 EDT 2010",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/NAME"
                      },
                      {
                          "name":"DESCRIPTION",
                          "type":"String",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/DESCRIPTION"
                      },
                      {
                          "name":"IS_COMPLETED",
                          "type":"Boolean",
                          "value":"true",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/IS_COMPLETED"
                      },
                      {
                          "name":"AUTO_GENERATED",
                          "type":"Boolean",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/AUTO_GENERATED"
                      },
                      {
                          "name":"START_TIME",
                          "type":"Date",
                          "value":"2010\/08\/04 15:07:50-0400",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/START_TIME"
                      },
                      {
                          "name":"BROKEN_OBJECT",
                          "type":"Boolean",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/BROKEN_OBJECT"
                      },
                      {
                          "name":"JOB_NAME",
                          "type":"String",
                          "value":"job_9e0dce5d-761e-4509-bef1-8bc636c73c64",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/JOB_NAME"
                      },
                      {
                          "name":"PRIORITY*",
                          "type":"JobPriorityEnumeration",
                          "value":"NORMAL"
                      },
                      {
                          "name":"REQUIRES_REBOOTS",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/REQUIRES_REBOOTS"
                      },
                      {
                          "name":"ROLE_MODIFIED",
                          "type":"String",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/ROLE_MODIFIED"
                      },
                      {
                          "name":"IS_INCOMPLETE",
                          "type":"Boolean",
                          "value":"false",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/IS_INCOMPLETE"
                      },
                      {
                          "name":"HAD_WARNINGS",
                          "type":"Boolean",
                          "value":"true",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/HAD_WARNINGS"
                      },
                      {
                          "name":"END_TIME",
                          "type":"Date",
                          "value":"2010\/08\/04 15:07:50-0400",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/END_TIME"
                      },
                      {
                          "name":"BL_ACL*",
                          "type":"BlAcl",
                          "value":""
                      },
                      {
                          "name":"DATE_CREATED",
                          "type":"Date",
                          "value":"",
                          "uri":"\/id\/SystemObject\/Job Run\/a3c0f3e9-bc90-4e15-8b50-2c545ab4e907\/
   PropertyValues\/DATE_CREATED"
                      }
                   ]
              }
          }
      }
   }
   

The following example shows how to copy a job using the copy job command:

Using asynchronous job notification

When you execute a job, you can use one of the following methods to obtain the job completion status:

• Your REST client can use a polling thread to get the job's completion status. (This is the method described in detail above in Example job request and response.)
• As an alternative, you can design your POST request to specify that you want the system to automatically send a status notification to a URL when the job ends.

Summary of polling method

To clarify the differences between the polling method and the notification method, here is a quick summary of the polling method:

Sample REST request

This request might return an OperationResultResponse that looks something like:

Polling step

The client now would have to take the most recent job run value from the OperationResult and poll like this:

This poll returns the job's completion status (StatusResponse), and would look something like this:

Asynchronous notification alternative

As an alternative to having to poll to get the completion status, you can include a notifyURL argument in the initial POST. This argument specifies a URL where the system can send the StatusResponse.
For example, you might include the following data in the POST request that executes the job:
Request:

For further arguments that you can include in this request, see Notification arguments.

After the StatusResponse arrives at the notification URL, you need to identify the correct job and job run with which this status is associated. To do this, use the value of the OperationResult that got returned from your first request. In this example, the OperationResult is:

Use the value up to Statuses (without the Schedule number) to query for all runs of the job with the specified ID:

From the list of job runs that is returned, choose the most recent, that is, the status name that contains the highest number.

In this example, the most recent job run has the following status:

so the URI is:

In this example, you determined that Schedule number 4 (from the OperationResult) represents a job run with Status number 4 for obtaining notification information.

Notification arguments

In addition to the notifyURL argument described above, there are a number of additional notification arguments:

Available operations and arguments (Job class)

Argument formats

You can use the following argument formats:

• Primitive
• Class instance
• URI

The following examples show how to use these formats. Note the following when formatting arguments:

• You need to specify the name and type of each argument.
• Depending on the argument type (and also whether it is a single or a list), the tag name is different. For example: value, values, ClassInstance, ClassInstances, uri, uris.
• The name and type must match the operation signature provided in the GET operation.