Universal Agent REST Web Service
The Universal Agent comes with a REST web service that allows it to be controlled from the command line. The service supports the following operations:
- sending commands and
- showing information.
Commands can be sent to an Agent:
- via any client application that sends the command with an HTTP request (JSON)
- via the start script of the Agent.
The start script makes use of a Java class that implements the HTTP client.
Start Script Status Information
- JS-1426Getting issue details... STATUS
The information is returned in JSON format.
If the Agent is not available, an exit status is returned accordingly.
The web service overview is called using jobscheduler_agent.sh status
.
Web Service Status Information
- JS-1480Getting issue details... STATUS
- JS-1412Getting issue details... STATUS
The Universal Agent provides status information via web services.
URI Syntax
All API URIs start with an optional prefix (if set on starting the Agent with the command line option -uri-prefix= set
) and the /jobscheduler/agent/api
character string.
- General status information is provided by:
/jobscheduler/agent/api
- General status information is also provided by:
/jobscheduler/agent/api/overview
- Information about the Agent tasks running is provided by the web service:
/jobscheduler/agent/
api/task
- Information about the active command is provided by the web service:
/jobscheduler/agent/api/tunnel
- Information about the active command is provided by the web service:
/jobscheduler/agent/api/tunnel
(without an end forward slash)
- A list of tunnels is provided by the web service:
/jobscheduler/agent/api/tunnel
/ (with an end forward slash)
- A summary of the commands running is provided by the web service:
/jobscheduler/agent/api/command
(without an end forward slash)
- A list of the commands running is provided by the web service:
/jobscheduler/agent/api/command
/ (with an end forward slash)
Note
These services are read only (HTTP verb GET). Changes are made using the command service (api/command
). (The only command is terminate
).
The following web services are addressed with the verb POST:
/jobscheduler/agent/api/task/command
/jobscheduler/agent/api/tunnel/id
Status Information Examples
Termination via Web Service
- JS-1400Getting issue details... STATUS
- JS-1401Getting issue details... STATUS
The JobScheduler Universal Agent is terminated
- by use of the start script, e.g.
./jobscheduler_agent.sh stop
- by calling the Agent web service URL for commands with a JSON command
/jobscheduler/agent/api/command
JSON commands to terminate the Agent are sent by an HTTP POST request and include:
- abort immediately:
- the Agent will kill all running tasks and will terminate immediately
- the client sends:
{ "$TYPE": "AbortImmediately" }
- this corresponds to the XML command that is used for a Master:
<modify_spooler cmd='abort_immediately'/>
- terminate:
- the Agent will not start new tasks, existing tasks can continue and the Agent will terminate after all tasks have completed
- optionally a SIGTERM can be sent to the tasks
- the client sends:
{ "$TYPE": "Terminate", "sigtermProcesses": false }
- this corresponds to the XML command that is used for a Master:
<modify_spooler
cmd='terminate'
/>
- terminate with timeout:
- the Agent sends all tasks a SIGTERM command and will wait for the specified timeout.
Should any task not terminate within the specified timeout then it will be killed with a SIGKILL signal. - the client sends:
{ "$TYPE": "Terminate", "sigtermProcesses": false, "sigkillProcessesAfter": 15 }
- this corresponds to the XML command that is used for a Master:
<modify_spooler
cmd='terminate'
timeout='15'
/>
- the Agent sends all tasks a SIGTERM command and will wait for the specified timeout.
References
See also
Change Management References