7.1.24 Execution agent addition API

This API adds an execution agent to 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 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
    },...],
    "status":"job-transfer-restriction-status-of-execution-agent",
    "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‒24: List of parameters for the Execution agent addition 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 execution agent name 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 of no more than 255 bytes. If you do not want to specify the job execution host, do not specify this parameter, alternatively, specify a null (zero-byte) string.	--
timePeriods	object[]	Specify the maximum number of concurrently executable jobs by using an object array. If you do not want to specify the maximum number of concurrently executable jobs, do not specify this parameter, alternatively, specify an empty object (zero-element object) or the string null.	--
timePeriod	string	Specify (in hh:mm-hh:mm format) the time period in 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
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. If you do not want to specify the job transfer restriction status of an execution agent, do not specify this parameter, alternatively, specify a null (zero-byte) string.	--
description	string	Specify a description by using a character string of no more than 80 bytes. If you do not want to specify a description, do not specify this parameter, alternatively, specify a null (zero-byte) string.	--

Status code

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

Status code	Text description	Description
200	OK	An execution agent was added 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 adding an execution agent 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 add an execution agent.

Example request:

POST /ajs/api/v1/objects/execAgents 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":20
    }],
    "status":"BLOCKADE",
    "description":"test"
  }
}

Example response (message body):

{
    "results":
    [
        {
            "rtnCode":"0",
            "output":null,
            "execAgent":"AGT01"
        }
    ]
}

To Page Top