7.1.27 API to change the job transfer restriction status of an execution agent

This API changes the job transfer restriction status of an execution agent that is registered on the manager host. You can also specify multiple execution agents to change their job transfer restriction statuses.

Execution privileges

The logged-in JP1 user must have one of the following JP1 permissions:

JP1_JPQ_Admin privileges
JP1_JPQ_Operator privileges

Request format

Request line

POST /application/component/apiVersion/objects/execAgents/actions/changeStatus/invoke httpVersion

Message Body

{
  "parameters":{
    "manager":"manager-host-name-or-IP-address",
    "mode":"agent",
    "status":"job-transfer-restriction-status-of-execution-agent",
    "execAgents":["execution-agent-name",...]
  }
}

API version

Information that uniquely identifies a resource

None

Parameter

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

Table 7‒27: List of parameters for the API to change the job transfer restriction status of an execution agent
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
`mode`	string	Specify a character string that indicates the target mode. Specify `agent` for this parameter.	Y
`status`	string	Specify the job transfer restriction status of an execution agent by using a character string constant that is supported by the `ExecAgentStatus` constant. For details about the `ExecAgentStatus` constant, see 7.4.14(1) ExecAgentStatus.	Y
`execAgents`	string[]	Specify the names of the execution agents as a string array. You can specify a maximum of 100 execution agents. Each execution agent name must be a character string in the range from 1 to 255 bytes.	Y

Status code

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

Status code	Message	Description
200	OK	The job transfer restriction statuses of the execution agents were 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.
412	Precondition failed	The Web Console server is not available.
500	Server-side error	A processing error occurred in the Web Console server.

Response format

Response message body

{
  "results":[Execution-agent-operation-result-object]
}

Return values

If the status code is 200, the following information is returned:

Member	Data type	Description
`results`	object[]	Returns an array of the execution agent operation result objects. The number of array elements is the same as the number of elements in the array specified for the `execAgents` parameter. Also, if the command terminates abnormally on the manager host, a non-zero value is stored as the result code of the target processing and `KNAK3696-E` is stored as a message in the returned array. For details about the execution agent operation result object, see 7.3.6 Execution agent operation result object.

Member

Data type

Description

results

object[]

Returns an array of the execution agent operation result objects. The number of array elements is the same as the number of elements in the array specified for the execAgents parameter.

Also, if the command terminates abnormally on the manager host, a non-zero value is stored as the result code of the target processing and KNAK3696-E is stored as a message in the returned array.

For details about the execution agent operation result object, see 7.3.6 Execution agent operation result object.

Cautionary note

Even if an error has occurred in JP1/AJS3 - Web Console, the operation on the execution agent might be successful on the manager host.

Example

The following shows an example of using the API to change the job transfer restriction status of an execution agent.

Example request:

POST /ajs/api/v1/objects/execAgents/actions/changeStatus/invoke HTTP/1.1
Host: HOSTW:22252
Accept-Language: ja
Content-Type: application/json
X-AJS-Authorization: dXNlcjpwYXNzd29yZA==
 
{
  "parameters":{
    "manager":"HOSTM",
    "mode":"agent",
    "status":"HOLD",
    "execAgents":["AGT01"]
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store, no-cache, max-age=0
Date: Tue, 25 Aug 2020 02:44:20 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Server: Cosminexus HTTP Server
 
{
    "results":
    [
        {
            "rtnCode":"0",
            "output":null,
            "execAgent":"AGT01"
        }
    ]
}

To Page Top