7.1.26 Execution agent reconfiguration API
This API changes the settings of an execution agent that is set on the manager host.
You can use this API function only if the version of JP1/AJS3 - Web Console is 12-50 or later and the version of the connection-destination JP1/AJS3 - Manager is 12-50 or later. Before you use this API function, confirm that: the return value (productVersionNumber) of the version information acquisition API function is 125000 or larger; and the return value (protocolVersionNumber) of the JP1/AJS3 - Manager protocol version acquisition API function is 1250 or larger.
- Execution privileges
-
The logged-in JP1 user must have the following JP1 permission:
-
JP1_JPQ_Admin privileges
-
- Request format
-
- Request line
POST /application/component/apiVersion/objects/execAgents/actions/update/invoke httpVersion
- Message Body
{ "parameters":{ "manager":"manager-host-name-or-IP-address", "mode":"target-mode", "execAgent":"execution-agent-name", "execHost":"execution-host-name", "timePeriods":[{ "timePeriod":"time-period", "conExe":maximum-number-of-concurrently-executable-jobs },...], "description":"comment" } }
- API version
-
v1
- 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‒26: List of parameters for the Execution agent reconfiguration 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
mode
string
Specify a character string that indicates the target mode. Specify agent for this parameter.
Y
execAgent
string
Specify the name of the execution agent whose settings are to be changed, by using a character string in the range from 1 to 255 bytes.
Y
execHost#
string
Specify the name of the job execution host by using a character string in the range from 1 to 255 bytes.
If you do not want to change the name of the job execution host, do not specify this parameter.
--
timePeriods#
object[]
Specify the maximum number of concurrently executable jobs as an object array.
If you specify this parameter, you must specify at least one maximum number of concurrently executable jobs.
If you do not want to change the maximum number of concurrently executable jobs, do not specify this parameter.
--
timePeriod
string
Specify (in hh:mm-hh:mm format) the time period during which the specified maximum number of concurrently executable jobs applies.
You can specify the following values:
-
hh: Specify the hour.
You can specify the hour in the range from 00 to 23 (unit: hour).
-
mm: Specify the minute.
For mm, you can specify only 00 or 30 (unit: minute).
Y
conExe
long
Specify the maximum number of jobs that can be concurrently executed in the specified time period. You can specify a numeric value in the range from 0 to 4294967295.
Y
description#
string
Specify a description by using a character string of no more than 80 bytes. If you do not want to change the description, do not specify this parameter.
--
- #
-
You must specify one or more of the following: the name of the job execution host, the maximum number of concurrently executable jobs, and the description.
-
- Status code
-
The following table lists and describes the status codes returned as a response:
Status code
Text description
Description
200
OK
The settings of the execution agent 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. In the returned array, the result of changing the execution agent settings is stored in element 0.
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 settings of an execution agent.
- Example request:
POST /ajs/api/v1/objects/execAgents/actions/update/invoke HTTP/1.1 Host: HOSTW:22252 Accept-Language: ja Content-Type: application/json X-AJS-Authorization: dXNlcjpwYXNzd29yZA== { "parameters":{ "manager":"HOSTM", "mode":"agent", "execAgent":"AGT01", "execHost":"AGT01", "timePeriods":[{ "timePeriod":"00:00-00:00", "conExe":30 }], "description":"TEST" } }
- Example response (message body):
{ "results": [ { "rtnCode":"0", "output":null, "execAgent":"AGT01" } ] }