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. |
|
credentialsRequired |
Credentials Required | Specifies if credentials are required to execute any task on the agent. | Valid Values: true/false (default is false). |
|
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 |
|