RESTful Web Services API

Universal Controller supports a RESTful-based web services API that allows you to perform multiple operations, which are listed alphabetically on the following pages.

Formatting specifications for each web service, including details about field requirements, are provided.

Agents	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
Agent Clusters	Create an Agent Cluster Delete an Agent Cluster List Agent Clusters Modify an Agent Cluster Read an Agent Cluster Resume an Agent Cluster Resume an Agent Cluster Membership Return an Agent from an Agent Cluster Set an Agent Cluster Task Execution Limit Suspend an Agent Cluster Suspend an Agent Cluster Membership
Audits	List Audit Records
Bundles and Promotion	Bundles Bundle Report Create a Bundle Delete a Bundle List Bundles Modify a Bundle Read a Bundle Promotion Bundleless Promotion Cancel a Scheduled Bundle Promotion Delete a Scheduled Bundle Promotion Promote a Bundle or Schedule a Bundle Promotion Create a Promotion Target Modify a Promotion Target List Promotion Targets Delete a Promotion Target Read a Promotion Target Refresh Target Agents
Business Services	Create a Business Service Delete a Business Service List Business Services Modify a Business Service Read a Business Service
Calendars	Add an Existing Custom Day to a Calendar Create a Calendar Delete a Calendar List Calendars List Local Custom Day Qualifying Dates List Local Custom Day Qualifying Periods Modify a Calendar Read a Calendar Read All Custom Days of a Calendar Remove a Custom Day from a Calendar
Cluster Nodes	List All Cluster Nodes Read Current Cluster Node
Connections	Database Connections Email Connections Email Templates PeopleSoft Connections SAP Connections SNMP Managers
Credentials	Create a Credential Delete a Credential List Credentials Modify a Credential Read a Credential
Custom Days	Create a Custom Day Delete a Custom Day List Custom Day Qualifying Dates List Custom Day Qualifying Periods List Custom Days Modify a Custom Day Read a Custom Day
Groups	Create a Group Delete a Group List Group Modify a Group Read a Group
LDAP	Read LDAP Settings Update LDAP Settings Update LDAP Bind Password
Monitoring	Universal Controller Metrics (Prometheus)
OAuth Single Sign-On	Read OAuth Single Sign-On Settings Update OAuth Single Sign-On Settings
OAuth Clients	Create an OAuth Client Modify an OAuth Client Read an OAuth Client Delete an OAuth Client List OAuth Clients
OMS Servers	Create an OMS Server Delete an OMS Server List OMS Servers Modify an OMS Server Read an OMS Server
Passwords	Change a Universal Controller User Password Change Runtime Password on Credentials
Properties	List Properties Modify a Property Read a Property
Reports	Run Report
Scripts	Create a Script Delete a Script List Scripts Modify a Script Read a Script
Server Operations	Export and Import LDAP List/Download Logs Pause and Resume Cluster Node Roll Log Temporary Property Change
Simulation	Create/Update a Simulation Delete a Simulation List Simulations Read a Simulation
System	Retrieve System Details
Task Instances	Cancel a Task Instance Clear All Dependencies Clear Exclusive Dependencies Clear Instance Wait Dependencies Clear Predecessor Dependencies Clear Time Dependency Clear Virtual Resource Dependencies Delete a Task Instance Force Finish a Task Instance Force Finish/Cancel a Task Instance Hold a Task Instance Issue Set Completed Command for a Manual Task Instance Issue Set Started Command for a Manual Task Instance List Task Instances List Task Instances: Advanced List Task Instance Variables (Show Variables) Patch a Task Instance Read a Task Instance Release a Task Instance from Hold Rerun a Task Instance Retrieve Task Instance Output Set or Modify Wait Time/Duration for Task Instance Set Priority for a Task Instance Skip a Task Instance Skip a Task Instance Path Unskip a Task Instance
Tasks	Create a Task Delete a Task Launch a Task List Tasks List Tasks - Advanced Modify a Task Read a Task
Triggers	Assign an Execution User to a Trigger Create a Trigger Delete a Trigger Enable/Disable a Trigger List Trigger Qualifying Times List Triggers List Triggers - Advanced Modify a Trigger Modify Time of Time Trigger Read a Trigger Trigger Now Unassign an Execution User from a Trigger
Universal Event	Universal Event Publishing
Universal Event Templates	Create a Universal Event Template Delete a Universal Event Template List Universal Event Templates Modify a Universal Event Template Read a Universal Event Template
Universal Templates	Create a Universal Template Delete a Universal Template List Universal Templates Modify a Universal Template Read a Universal Template Restore Default Universal Template Icon Set Universal Template Icon Universal Template - Delete Extension Archive Universal Template - Download Extension Archive Universal Template - Upload Extension Archive Universal Template Export Universal Template Import
Users	Create a User Create Personal Access Token Delete a User List Personal Access Tokens List User Preferences List Users Modify a User Read a User Read a User Preference Revoke Personal Access Token Update a User Preference
Variables	Create a Global Variable Delete a Global Variable List Variables List Variables - Advanced Modify a Global Variable Read a Global Variable Set Variables
Virtual Resources	Create a Virtual Resource Delete a Virtual Resource List Virtual Resources List Virtual Resources - Advanced Modify a Virtual Resource Read a Virtual Resource Set Limit on a Virtual Resource
Webhooks	Assign an Execution User to a Webhook Disable a Webhook Enable a Webhook Enable/Disable Multiple Webhooks List Webhooks Modify Webhooks Read a Webhook Register a Webhook Unassign an Execution User from a Webhook Unregister a Webhook
Workflow Task Instances	Insert a Task into a Workflow with Dependencies List Predecessors / Successors of a Task Instance in a Workflow
Workflow Tasks	Create a Workflow List Workflow Forecast Modify a Workflow Read a Workflow Workflow Tasks and Dependencies

Swagger UI and OpenAPI

Universal Controller offers an OpenAPI specification along with a Swagger UI page that provides an interactive interface for easily visualizing and interacting with Universal Controller RESTful API endpoints.

The Swagger UI page can be accessed from the Universal Controller user interface by clicking on the icon in the toolbar.

The OpenAPI document can be accessed in either JSON or YAML formats by going to <Controller URL>/resources/openapi.json or <Controller URL>/resources/openapi.yaml.

Methods of API Operations

Every API operation is performed using one of the following methods.

Method	Description
GET	Retrieves records from the Controller database.
POST	Creates, or performs an action on, a record in the Controller database.
PUT	Modifies a record in the Controller database. info PUT, by itself, actually replaces an existing record with whatever information you include in the PUT operation. If you include only partial record information in a PUT, the record in the database will then contain only that information. In order to modify information in a record and retain all of its unmodified information, you must first GET the record from the database, modify (add/delete/change) information in the record, and then PUT the record back in the database.
DELETE	Deletes a record in the Controller database.

Authentication

Universal Controller requires Web Service requests to be authenticated using one of Basic Authentication or Personal Access Token Authentication.

For Basic Authentication, use the following Authorization header, where the username:password is base64 encoded.

Authorization: Basic <username:password>

For Personal Access Token Authentication, use the following Authorization header.

Authorization: Bearer <access-token>

While it is recommended you use the Authorization header, if required, you can alternatively pass the Personal Access Token using the access_token query parameter.

http://<hostname>:<port>/uc/resources/task?access_token=<access-token>&taskname=MyTask If you cannot use any of the above, you can configure an alternative authorization header. To configure an alternative authorization header, refer to the Web Service Personal Access Token Auth Headers system property.

X-Gitlab-Token: <access-token>

See User Impersonation for information on how to impersonate a user when invoking Universal Controller Web Service APIs.

Change Description

Change History is supported for the following record types (and any related data for these record types):

• Agent Cluster
• Application
• Calendar
• Credentials
• Custom Day (Global)
• Database Connection
• Email Connection
• Email Template
• Business Services
• OAuth Client
• Peoplesoft Connection
• Sap Connection
• Script
• SNMP Manager
• Task
• Task Instance
• Trigger
• Variable (Global)
• Virtual Resource

If the Change History Enabled system property is true, you can specify a Change Description when updating a supported record type via the API by using the X-Change-Description header. A time-stamped entry with the value given in this header will be added to the Change History of the record on a successful Update operation.

If the Change History Description Web Service Required system property is true, the X-Change-Description header is required for supported record types; otherwise, it is optional. X-Change-Description will be ignored when updating an unsupported record type, or when creating any record type.

info

When using the Set Variable Web Service API, the X-Change-Description header is applicable when updating a Global Variable. It is also applicable when creating/updating a Local Variable, in which case the specified Change Description will be propagated to the Change History of the parent task or trigger.

Request Limits

You can implement application- and user-level concurrent request limits to control how many web service API requests can be in progress at the same time via the following Universal Controller system properties:

Web Service Application Concurrent Request Limit	Controls the number of concurrent requests for the application (that is, the Universal Controller server). This application-level concurrent request limit cannot be less than 1 or less than the user-level concurrent request limit (if specified).
Web Service User Concurrent Request Limit	Controls the number of concurrent requests per unique user ID. This user-level concurrent request limit cannot be less than 1 or more than the application-level concurrent request limit (if specified). If the application-level concurrent request limit is exceeded, an HTTP Status of 429 /Too Many Requests will be returned.

These properties are applied in the following order:

1. User-level Concurrent Request Limit
2. Application-level Concurrent Request Limit

Memory Utilization Threshold

You can specify a threshold for prohibiting access to the RESTful Web Service API based on a percentage of allocated memory in use.

Web Service Memory Utilization Threshold

Percentage of allocated memory in use that defines a threshold for prohibiting access to the RESTful Web Service API. The threshold must be a whole number (integer) and cannot be less than 1 or more than 99. If the threshold is exceeded, an HTTP Status of 503 /Service Unavailable will be returned.

Returned Messages

The following table identifies the status codes (part of the HTTP/1.1 standard) that can be returned.

Status Code	Description
200	Success
400	Bad request data.
401	User does not have authorization (username and/or password invalid).
403	User does not have permission to access Web Services. Access options are set via: System Default Web Service Access Universal Controller system property. User Details (Web Service Access field)
404	Resource not found.
429	Too Many Requests.
500	All other errors. For List Variables, 500 is returned if the Web Service fails due to invalid parameters. (A status description also is returned.)
503	Service Unavailable.

Any other failure status codes may be returned by the underlying RESTful services. Most resources (Controller records) are returned as XML.

You can check status codes in the Audits and the uc.log file to determine the cause if their Web Service client is not displaying the error message that comes back with the response.

User Restriction

You can be restricted from logging in to the RESTful Web Services API either of two ways:

1. The system level default for RESTful Web Services API access, specified by the System Default Web Service Access Universal Controller system property, has been set to No, and the Web Service Access field in the User Details for your user account is set to -- System Default --."
2. The Web Service Access field is set to No, which overrides the System Default Web Service Access value.

If either restriction is in place, the following error message will be written to the Audits table and the uc.log file when you attempt to access the RESTful Web Services API:

User <your user name> not permitted to use Web Services. Please check with your administrator.

To remove the restriction, the system administrator must either:

• Set the System Default Web Service Access property to Yes and set the Web Service access field on the User Definition screen for your user account to -- System Default --.
• Set the Web Service access field on the User Definition screen for your user account to Yes.

Password Expiration

While a password is expired, RESTful Web Services API access will be prohibited until the password has been changed.

info

Password expiration is not applicable to LDAP authenticated users.