Agent Web Services
Overview
Universal Controller supports the following RESTful-based web services for Agent operations, which are listed alphabetically on this page.
- Delete an Agent
- List Agents
- List Agents - Advanced
- Modify an Agent
- Read an Agent
- Resume an Agent
- Set an Agent Task Execution Limit
- Suspend an Agent
Formatting specifications for each web service, including details about property requirements, are provided.
Delete an Agent
Description | |
---|---|
URI | http://host_name/uc/resources/agent |
HTTP Method | DELETE |
Description | Deletes an Agent. |
URI Parameters | See Delete an Agent: URI Parameters, below. |
Example URI | |
Authentication | HTTP Basic |
Example Response |
|
Delete an Agent: URI Parameters
Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| Unique ID for this Agent, created during installation. | Y |
| |
| Name used within the Controller to identify this agent. | Maximum 40 alphanumerics. | Y |
|
List Agents
Description | |
---|---|
URI | http://host_name/uc/resources/agent/list |
HTTP Method | GET |
Description | Retrieves information on all agents. |
Example URI | http://localhost:8080/uc/resources/agent/list |
Authentication | HTTP Basic |
Produces Content-Type | application/xml, application/json |
Example | |
Properties |
List Agents: XML and JSON Examples
The following XML and JSON examples are for the List Agents web service.
XML | JSON |
---|---|
List Agents: Properties
Property | UI Field Name | Description |
---|---|---|
| Accept Extensions | Indication of whether or not the Agent will accept deployment of Universal Extensions. |
| Accept List | If
|
| API Level Minimum | Minimum extension API level supported. |
| API Level Maximum | Maximum extension API level supported. |
| Extensions | List of deployed Universal Extensions and their corresponding checksums. |
| Host Name | IP address or domain/name of the host machine where the Agent resides. |
| IP Address | TCP/IP address of the machine where the Agent is running. If the currently logged in user is a non-Administrator (ops_admin) user, and the Agent Address Information Restricted Universal Controller system property is set to true, ipAddress will be set to <ipAddress /> (XML) and "ipAddress": null (JSON). Note This also applies to the ipAddress of z/OS secondary Agents. |
| Agent Name | Name used within the Controller to identify this Agent. |
| Retrieve Output Prohibited | Specification (true or false) for whether or not Retrieve Output requests are disallowed from being performed for this Agent. |
| Agent Id | Unique ID for this Agent. |
| Status | Status of the Agent. |
| Suspended | Indication (true or false) of whether or not the Agent currently is suspended. |
| n/a | System ID field in the database for this Agent record. |
| Transient | For Linux Unix Agents only; Specification (true or false) for whether or not the Agent is considered a Transient Agent. |
| Operating System | Operating system on which the Agent is running. |
| Version | Version number of the Agent program. |
List Agents - Advanced
Description | |
---|---|
URI | |
HTTP Method | GET |
Description | Retrieves Agent details using specific query parameters. |
Example URI | |
Authentication | HTTP Basic |
Produces Content-Type | application/xml, application/json |
URI Parameters | |
Example Response |
List Agents - Advanced: URI Parameters
Name | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| n/a | Type of Agent | Valid values (case insensitive):
| N |
| n/a | Name used within the Controller to identify this Agent. | Wildcards are supported. | N |
businessServices | n/a | Business Services that this Agent belongs to. | String value of comma-separated business services. | N |
List Agents - Advanced: XML and JSON Examples
The following XML and JSON examples are for the List Agents - Advanced web service.
XML | JSON |
---|---|
Modify an Agent
Description | |
---|---|
URI | http://host_name/uc/resources/agent |
HTTP Method | PUT |
Description | Modifies the Agent specified by the |
Example URI | http://localhost:8080/uc/resources/agent |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | |
Agent Properties | See Agent: Properties. |
Email Notification Properties | |
SNMP Notification Properties | |
Example Response |
|
Read an Agent
Description | |
---|---|
URI | http://host_name/uc/resources/agent |
HTTP Method | GET |
Description | Retrieves information on a specific Agent. |
URI Parameters | |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example URI | http://localhost:8080/uc/resources/agent?agentid=SS0001 |
Example Response | |
Agent Properties | See Agent: Properties. |
Email Notification Properties | |
SNMP Notification Properties |
Read an Agent: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this Agent. | String; URI parameter. | Y (unless |
|
| Name used within the Controller to identify this Agent. | String; URI parameter. | Y (unless |
|
Agent: XML and JSON Examples
XML | JSON |
---|---|
Agent: Properties
Property | UI Field Name | Description | Specifications |
---|---|---|---|
| Authentication Version | Type of encryption in use for this Agent. | Read only. |
| Build Id | Build ID of the Agent. | Read only. |
| Build Date | Date that the Agent program was last built. | Read only. |
| CPU | Information about the CPU on the Agent machine. | Read only. |
| CPU Load | Current CPU load on the Agent machine. | Read only; Integer. Expressed as a percentage. For example, 1 means 1% currently utilized. |
| Credentials | Credentials under which this Agent runs tasks. These credentials are overridden by any credentials provided in the task definition for any tasks being run by this Agent. | |
| Current Task Count | If | Read only. |
| Decommissioned | For Linux Unix Agents only; Specification (true or false) for whether or not the Agent is decommissioned. | Valid values: true/false (default is false). |
| Decommissioned Date | For Linux Unix Agents only; If decommissioned is true: Date when the Agent was decommissioned. | Read only. |
| n/a | For the Modify Agent web service; specification for whether or not to exclude related records from the update, even if they are provided in the request. Note In XML, | Valid values: true/false (default is false). |
| Accept Extensions | Indication of whether or not the Agent will accept deployment of Universal Extensions. | Read only. |
| Accept List | If
| Read only. |
| API Level Minimum | Minimum extension API level supported. | Read only. |
| API Level Maximum | Maximum extension API level supported. | Read only. |
| Extensions | List of deployed Universal Extensions and their corresponding checksums. | Read only. |
| Last Heartbeat | Date and time that the most recent heartbeat was received from the Agent. | Read only. |
| Heartbeat Grace Period | Grace period, in seconds, that the Controller will allow for a delayed heartbeat message | Integer. |
| Heartbeat Interval | Heartbeat interval (in seconds). The heartbeat is a status message sent from the Agent to the Controller. | Integer. |
| Host Name | Read only; IP address or domain/name of the host machine where the resource resides. | Read only. |
| IP Address | Read only; TCP/IP address of the machine where the Agent is running. If the currently logged in user is a non-Administrator (ops_admin) user, and the Agent Address Information Restricted Universal Controller system property is set to true, ipAddress will be set to <ipAddress /> (XML) and "ipAddress": null (JSON). Note This also applies to the ipAddress of z/OS secondary Agents. | Read only. |
| Jobs Run | Read only; Total number of jobs that have been run through the Controller to this Agent. | Read only; Integer. |
| Limit Amount | If | Integer. |
| Task Execution Limit | Specification for whether a Limited or Unlimited number of task instances can be run concurrently on the Agent. | Valid values:
Default is Unlimited (1). |
| Retrieve Output Prohibited | Specification for whether or not Retrieve Output requests are disallowed from being performed for this Agent. | Read only; Boolean. Valid values: true/false. |
| Log Level | Level of logging that the Agent can perform | Valid values:
Default is Informational. |
| Name | Name used within the Controller to identify this Agent. | |
| OMS Server | Host name of the OMS Server. | Read only. |
| Member of Business Services | One or more Business Services that this Agent belongs to. | Read only. |
| Operating System | Operating system on which the Agent is running. | Read only. |
| Operating System Release | Release information for the operating system on which the Agent is running. | Read only. |
| PID | Process ID of the Agent. | Read only. |
| Agent ID | Unique ID for this Agent, created during installation. | Read only. |
| Secondary Agent Licenses | For z/OS Agents only; Number of secondary agent licenses. | Read only; Integer |
| Secondary Agent(s) | For z/OS Agents only; List of secondary agent information. | Read only. Format:
|
| Started Date | Date/timestamp when the Agent was last started. | Read only. |
| Status | Status of the Agent. | Read only. Valid values:
|
| Suspended | Indication that the Agent's ability to run tasks has been suspended. | Read only; Boolean. Valid values: true/false. |
| n/a | System ID field in the database for this Agent. | Read only. |
| System Name | For z/OS Agents only; System name. | Read only. |
| Transient | For Linux Unix Agents only; Specification (true or false) for whether or not the Agent is considered a Transient Agent. | Valid values: true/false (default is false). |
| Version | Version number of the Agent program. | Read only. |
Agent: Email Notification Properties
Property | UI Field Name | Description | Specifications |
---|---|---|---|
| Bcc | Email address of the party being sent a blind (hidden) copy of the email, if any. | Use commas to separate multiple recipients. Variables and Functions are supported. |
| Body | Text of the email message. | Variables and Functions are supported. If the |
| Cc | Email address of the party being sent a copy of the email, if any. | Use commas to separate multiple recipients. Variables and Functions are supported. |
| Email Connection | Name of an Email Connection. | If you specify both an |
| Email Template | Name of an Email Template. | If you specify both an |
| Reply-To | Email address of the sender of the email. | Use commas to separate multiple recipients. Variables and Functions are supported. |
| Status Options | Comma-separated list of statuses | Valid values:
|
| Subject | Subject line of the email. | Variables and Functions are supported. |
| n/a | sys_id used within the Controller to identify this Email Notification. | |
| To | Email address of the recipient. | Use commas to separate multiple recipients Variables and Functions are supported. |
Agent: SNMP Notification Properties
Property | UI Field Name | Description | Specifications |
---|---|---|---|
| Notification Severity | Severity level of this notification. | Valid values:
Default is Normal (1). |
| SNMP Manager | SNMP Manager that will receive this notification. | |
| Status Options | Comma-separated list of statuses | Valid values:
|
| n/a | sys_id used within the Controller to identify this SNMP Notification. |
Resume an Agent
Description | |
---|---|
URI | http://host_name/uc/resources/agent/ops-resume-agent |
HTTP Method | POST |
Description | Resumes the specified agent. |
Example URI | http://localhost:8080/uc/resources/agent/ops-resume-agent |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | application/xml, application/json |
Example Request | |
Request Properties | |
Example Response |
Resume an Agent: XML and JSON Examples
Example | XML | JSON |
---|---|---|
Example Request | ||
Example Response |
Resume an Agent: Request Properties
Properties | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
| Agent ID | Unique ID for this Agent, created during installation. | Y |
| |
| Agent Name | Name used within the Controller to identify this resource. | Maximum 40 alphanumerics. | Y |
|
Set an Agent Task Execution Limit
Description | |
---|---|
URI | http://host_name/uc/resources/agent/ops-set-agent-task-execution-limit |
HTTP Method | POST |
Description | Sets the task execution limit for the specified agent. |
Example URI | http://localhost:8080/uc/resources/agent/ops-set-agent-task-execution-limit |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | application/xml, application/json |
Example Request | See Set an Agent Task Execution Limit: XML and JSON Examples. |
Request Properties | |
Example Response | See Set an Agent Task Execution Limit: XML and JSON Examples. |
Set an Agent Task Execution Limit: XML and JSON Examples
Example | XML | JSON |
---|---|---|
Example Request | ||
Example Response |
Set an Agent Task Execution Limit: Request Properties
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
| Agent ID | Unique ID for this Agent, created during installation. | Y |
| |
| Agent Name | Name used within the Controller to identify this resource. | Maximum 40 alphanumerics. | Y |
|
| Limit Amount | Number of tasks that can be running at the same time by the Agent. | Y | ||
| Task Execution Limit | Specification for whether a Limited or Unlimited number of task instances can be run concurrently on the Agent. | Valid values:
| Y |
Suspend an Agent
Description | |
---|---|
URI | http://host_name/uc/resources/agent/ops-suspend-agent |
HTTP Method | POST |
Description | Suspends the specified agent. |
Example URI | http://localhost:8080/uc/resources/agent/ops-suspend-agent |
Authentication | HTTP Basic |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | application/xml, application/json |
Example Request | |
Request Properties | See Suspend an Agent: Request Properties, below. |
Example Response |
Suspend an Agent: XML and JSON Examples
Example | XML | JSON |
---|---|---|
Example Request | ||
Example Response |
Suspend an Agent: Request Properties
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
| Agent ID | Unique ID for this Agent, created during installation. | Y |
| |
| Agent Name | Name used within the Controller to identify this resource. | Maximum 40 alphanumerics. | Y |
|