Hitachi

JP1 Version 12 JP1/Automatic Job Management System 3 Command Reference


7.1.11 Change job status API

This API changes the status of the specified job.

For details about changing the job status, see 4.5.12 Changing the status of a job in the manual JP1/Automatic Job Management System 3 Overview.

You can use this API only when the JP1/AJS3 - Web Console version is 11-10 or later. Before using this API, make sure that the return value of the version information acquisition API (productVersionNumber) is 111000 or greater.

Execution privileges

The logged in JP1 user must have one of the following JP1 permissions for the unit whose status is to be changed:

  • JP1_AJS_Admin privileges

  • JP1_AJS_Manager privileges

  • JP1_AJS_Operator privileges

Request format
Request line
POST /application/component/apiVersion/objects/statuses/unitName:execID/actions/changeStatus/invoke httpVersion
Message Body
{
  "parameters":{
    "manager":"manager-host-name-or-IP-address",
    "serviceName":"scheduler-service-name",
    "newStatus":"status-after-change",
    "newReturnCode":"return-code-after-change"
  }
}
API version

v1

Information that uniquely identifies a resource

The table below describes the information that uniquely identifies a resource.

If a parameter is not specified or is specified incorrectly, an error with the status code 404 occurs because the resource cannot be uniquely identified.

Information that uniquely identifies a resource

Data type

Description

Required?

unitName

string

Specify the full name of the unit to be requested, by using a character string in the range from 1 to 930 bytes.

Y

execID

string

Specify the execution ID by using a character string in the format of @[mmmm]{A to Z}nnnn (for example, @10A200).

Y

Legend:

Y: Required

Parameter

The following table lists and describes the parameters that can be specified for parameters in the request message body.

Table 7‒11: List of parameters for the change job status API

Parameter

Data type

Description of the value

Required?

manager

string

Specify the manager host name or IP address by using a character string in the range from 1 to 255 bytes.

Y

serviceName

string

Specify the scheduler service name by using a character string in the range from 1 to 30 bytes.

Y

newStatus#

string

Specify the status after the change, by using a character string constant specified for the ChangeStatus constant. For details about the ChangeStatus constant, see 7.4.12(1) ChangeStatus.

If you do not want to change the status, do not specify this parameter, or specify null for this parameter.

The operation of this parameter differs depending on the type of the unit whose status is to be changed.

The following shows the operations:

  • If the unit type is a jobnet connector, you can specify NORMAL (Ended normally), WARNING (Ended with warning), or ABNORMAL (Ended abnormally). If you specify any other value or omit this parameter, an error occurs.

  • If the unit type is an event job, action job, or OR job, you cannot specify RETURNCODE (Judge by return code). If you specify this value, an error occurs.

  • You cannot specify this parameter if the type of the target unit is a judgement job or event job defined in the start conditions. If you specify this parameter, an error occurs.

--

newReturnCode#

string

Specify the return code after change, as a number in the range from -2,147,483,648 to 2,147,483,647. If you do not want to change the return code, do not specify this parameter or specify null for this parameter.

You cannot specify this parameter if the type of the target unit is a jobnet connector or event job defined in the start conditions. If you specify this parameter, an error occurs.

--

Legend:

Y: Required

--: Optional

#

Be sure to specify either the new status (newStatus) or the new return code (newReturnCode). If you do not specify either of these (or if null is specified), an error occurs.

Status code

The following table lists and describes the status codes returned as a response:

Status code

Message

Description

200

OK

The status of the job was changed successfully.

400

Bad Request

The argument is invalid.

401

Unauthorized

Authentication is required.

403

Forbidden

The operator does not have execution permission.

404

Not found

The operator does not have access permission for the resource, or the resource does not exist.

409

Conflict

The processing cannot be continued because the request is inconsistent with the current resource status.

412

Precondition failed

The Web Console server is not available.

500

Server-side error

A processing error occurred in the Web Console server.

Return values

None (The size of the response message body is 0 bytes.)

Example 1

The following shows an example of using the API that changes the status of the specified job.

Example request:
POST /ajs/api/v1/objects/statuses/%2FJobGroup%2FJobnet%2FJob:%40A100/actions/changeStatus/invoke HTTP/1.1
Host: HOSTW:22252
Accept-Language: ja
Content-type: application/json
X-AJS-Authorization: dXNlcjpwYXNzd29yZA==
 
{
  "parameters":{
    "manager":"HOSTM",
    "serviceName":"AJSROOT1",
    "newStatus":"NORMAL"
  }
}
Example response:
HTTP/1.1 200 OK
Content-Type: text/plain
Cache-Control: no-store, no-cache, max-age=0
Date: Mon, 08 Aug 2016 09:39:28 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Server: Cosminexus HTTP Server
Example 2

The following shows an example of using the API that changes the return code of the specified job.

Example request:
POST /ajs/api/v1/objects/statuses/%2FJobGroup%2FJobnet%2FJob:%40A100/actions/changeStatus/invoke HTTP/1.1
Host: HOSTW:22252
Accept-Language: ja
Content-type: application/json
X-AJS-Authorization: dXNlcjpwYXNzd29yZA==
 
{
  "parameters":{
    "manager":"HOSTM",
    "serviceName":"AJSROOT1",
    "newReturnCode":"4"
  }
}
Example response:
HTTP/1.1 200 OK
Content-Type: text/plain
Cache-Control: no-store, no-cache, max-age=0
Date: Mon, 08 Aug 2016 09:39:28 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Server: Cosminexus HTTP Server
Example 3

The following shows an example of using the API that changes the status and return code of the specified job.

Example request:
POST /ajs/api/v1/objects/statuses/%2FJobGroup%2FJobnet%2FJob:%40A100/actions/changeStatus/invoke HTTP/1.1
Host: HOSTW:22252
Accept-Language: ja
Content-type: application/json
X-AJS-Authorization: dXNlcjpwYXNzd29yZA==
 
{
  "parameters":{
    "manager":"HOSTM",
    "serviceName":"AJSROOT1",
    "newStatus":"ABNORMAL",
    "newReturnCode":"4"
  }
}
Example response:
HTTP/1.1 200 OK
Content-Type: text/plain
Cache-Control: no-store, no-cache, max-age=0
Date: Mon, 08 Aug 2016 09:39:28 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Server: Cosminexus HTTP Server
Example 4

The following shows an example of using the API that determines the status of the specified job by the return code, and then changes the job status to the specified return code.

Example request:
POST /ajs/api/v1/objects/statuses/%2FJobGroup%2FJobnet%2FJob:%40A100/actions/changeStatus/invoke HTTP/1.1
Host: HOSTW:22252
Accept-Language: ja
Content-type: application/json
X-AJS-Authorization: dXNlcjpwYXNzd29yZA==
 
{
  "parameters":{
    "manager":"HOSTM",
    "serviceName":"AJSROOT1",
    "newStatus":"RETURNCODE",
    "newReturnCode":"99"
  }
}
Example response:
HTTP/1.1 200 OK
Content-Type: text/plain
Cache-Control: no-store, no-cache, max-age=0
Date: Mon, 08 Aug 2016 09:39:28 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Server: Cosminexus HTTP Server