Universal Template Web Services
Overview
Universal Controller supports the following RESTful-based web services for Universal Templates, which are listed alphabetically on this page.
- 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
Formatting specifications for each web service, including details about parameter requirements, are provided.
Note
You cannot create, read, modify, or list Built-In Universal Templates.
You can delete Built-In Universal Templates.
Auditing Universal Events
The Universal Event Web Service Publish Audit lets you specify whether or not an audit record is generated for each Universal Event published through the Universal Event Web Services.
(The Universal Event Extension Publish Audit lets you specify whether or not an audit record is generated for each Universal Event published through an Extension-based Universal Task Instance.)
Note
Enabling these audit properties can generate a large quantity of audit.
Create a Universal Template
Description | |
---|---|
URI | http://host_name/uc/resources/universaltemplate |
HTTP Method | POST |
Description | Creates a new Universal Template. |
Example URI | http://localhost:8080/uc/resources/universaltemplate |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example | See Create, Modify, and Read a Universal Template: XML and JSON Examples, below. |
Universal Template Properties | |
Field Properties | See Field Properties. |
Choice Properties | See Choice Properties. |
Example Response |
|
Create, Modify, and Read a Universal Template: XML and JSON Examples
The excludeRelated and retainSysIds properties are specified as attributes in XML.
The exportReleaseLevel
property is specified as an attribute in XML.
XML | JSON |
---|---|
Delete a Universal Template
Description | |
---|---|
URI | http://host_name/uc/resources/universaltemplate |
HTTP Method | DELETE |
Description | Deletes a Universal Template. |
URI Parameters | See Delete a Universal Template URI Parameters, below. |
Example URI | http://localhost:8080/uc/resources/universaltemplate?templatename=UT1 |
Example Response |
|
Delete a Universal Template: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this Universal Template. | String; URI parameter. | Y (unless |
|
| Name used within the Controller to identify this Universal Template. | String; URI parameter. | Y (unless |
|
List Universal Templates
Description | |
---|---|
URI | http://host_name/uc/resources/universaltemplate/list |
HTTP Method | GET |
Description | Retrieves information on Universal Templates using specific query parameters. |
Example URI | |
Authentication | HTTP Basic |
Produces Content-Type | application/xml, application/json |
Example | |
Universal Template Properties |
List Universal Templates: URI Parameters
Parameter | Description | Specifications | Required |
---|---|---|---|
| Name used within the Controller to identify this Universal Template. | String; URI parameter. Wildcards are supported. | N |
List Universal Templates: XML and JSON Examples
XML | JSON |
---|---|
Modify a Universal Template
Description | |
---|---|
URI | http://host_name/uc/resources/universaltemplate |
HTTP Method | PUT |
Description | Modifies the Universal Template specified by the sysId in the request. |
Example URI | http://localhost:8080/uc/resources/universaltemplate |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example | See Create, Modify, and Read a Universal Template: XML and JSON Examples. |
Universal Template Properties | |
Field Properties | See Field Properties. |
Choice Properties | See Choice Properties. |
Example Response |
|
Read a Universal Template
Description | |
---|---|
URI | http://host_name/uc/resources/universaltemplate |
HTTP Method | GET |
Description | Retrieves information on a specific Universal Template. |
URI Parameters | See Read a Universal Template: URI Parameters, below. |
Example URI | http://localhost:8080/uc/resources/universaltemplate?templatename=UT1 |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Universal Template Properties | |
Field Properties | See Field Properties. |
Choice Properties | See Choice Properties. |
Example Response |
|
Read a Universal Template: URI Parameters
Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| Unique ID for this Universal Template. | Y |
| |
| Name used within the Controller to identify this Universal Template. | Maximum 40 alphanumerics. | Y |
|
Properties
Universal Template Properties
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
| Agent | Name of the Agent to use. | N |
| |
| Agent Cluster | Group of Agents, one of which the Controller will choose to run this task (compare with | N |
| |
| Agent Cluster Variable | Name of a variable that will be resolved at run time to the name of the Agent Cluster to use. | Format: ${variable name}. | N |
|
| Agent Fields | Restriction to apply to the group of Agent Fields. | Valid values:
| N | |
| Agent Type | Type of Agent on which Universal Tasks based on this template can be run. | Valid values:
| Y | |
| Agent Variable | Name of a variable that will be resolved at run time to the name of the Agent to use. | Format: ${variable name}. | N |
|
| Always Cancel On Finish | Specification for whether or not to always perform a Cancel when Force Finishing a Universal Task for this template. | Boolean; Valid values: true/false. Default is false. | N | |
| Automatic Output Retrieval Fields | Restriction to apply to the group of Automatic Output Retrieval Fields. | Valid values:
| N | |
| Cluster Broadcast | Group of Agents, all of which will run this task (compare with | N |
| |
| Cluster Broadcast Variable | Name of a variable that will be resolved at run time to the name of the Cluster Broadcast to use. | Format: ${variable name} | N |
|
| Create Console | If | Boolean; Valid values: true/false. Default is false. | N | |
| Credential Fields | Restriction to apply to the group of Credential Fields. | Valid values:
| N | |
| Credentials | Credentials under which an Agent runs this task. These credentials override any credentials provided in the Agent Details for any Agent running this task. | N |
| |
| Credentials Variable | Name of a variable that will be resolved at run time to the name of the {Credentials] to use. | N |
| |
| Description | Description of this Universal Template. | N | ||
| Interact with Desktop | Specification for whether or not a task that runs an application with a GUI requires some manual actions from a user (for example, clicking buttons or entering values). | Boolean; Valid values: true/false. Default is false. | N | |
| Run with Highest Privileges | Specification for whether or not to execute the task using an elevated privileges token, rather than one subject to User Account Control (UAC) restrictions. An elevated token allows a process to execute with all the privileges available to its specified credentials. For example, a task executed with an administrative account will behave as though it received permission via a UAC dialog to perform a privileged operation. | Boolean; Valid values: true/false. Default is false. | N | |
| Environment Variables | Environment variables needed by the program to run. | List of environment variables:
| N | |
| Environment Variable Fields | Restriction to apply to the group of Environment Variables Fields. | Valid values:
| N | |
| n/a | Specification for whether or not to exclude related records. | Boolean; Valid values: true/false. Default is false. | N | |
| Output File | Path and file name of the output file that should be scanned for the text in | N | ||
| Exit Code Processing | Specification for how the Controller should determine whether the executed command failed or completed successfully. | Valid values:
Default is Success Exitcode (1). | N | |
| Exit Code Processing Fields | Restriction to apply to the group of Exit Code Processing Fields. | Valid values:
| N | |
| Exit Codes | If | Format: Numeric. Use commas to list a series of exit codes; use hyphens to specify a range. Example: 1,5, 22-30. | Y | |
| Scan Output For | If | The Controller will process this field as a regular expression. | Y | |
| n/a | Universal Controller release that the record was exported from. | read only | N | |
| Name | Name of this Universal Template. | Y | ||
| Failure Only | If | Boolean; Valid values: true/false. Default is false. | N | |
| Output File | If | N | ||
| Number of Lines | If | Default is the value of the Retrieve Output Default Maximum Lines Universal Controller system property. | N | |
| Start Line | If | Default is 1. | N | |
| Scan Text | If | The Controller will process this field as a regular expression. | N | |
| Automatic Output Retrieval | Specificaton for whether you want the Controller to automatically retrieve any output from the job and attach it to the task instance record. | Valid values:
Default is OUTERR (6). Note If | N | |
| Output Type | If | Valid values:
Default is STDOUT (1). | N | |
| n/a | Specification for whether or not the Create a Universal Template web service will persist the | Boolean; Valid values: true/false. Default is false. | N | |
| Runtime Directory | Directory from which the application should be executed. | Variables are supported. | N | |
| Script | If | N | ||
| Linux/Unix Script | If | N | ||
| Windows Script | If | N | ||
| Windows Script File Type | If | Valid values:
| N | |
| Send Extension Variables | If Options:
| Valid values:
Default is None (0). | N | |
| UUID | System ID field in the database for this record. | Persisted only if | N | |
| Template Type | Specification for whether the Universal Template will be executed as a Script or will be executed through the Universal Extension framework. | Valid values:
Default is Script (1). | N | |
| Use Common Script | Indication that the specified | Boolean; Valid values: true/false. Default is false. | N | |
| Variable Prefix | Variable prefix to append to the default prefix (ops_) for the system-assigned variables that are provided for the user-defined Fields in this Universal Template. | Y | ||
| Wait For Output | If | Boolean; Valid values: true/false. Default is false. | N |
Field Properties
Property | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| Name Title | If fieldType is Array; Title to be displayed for the Name column. | N | |
| Value Title | If fieldType is Array; Title to be displayed for the Value column. | N | |
| No Value | If | Y | |
| Boolean Value Type | Type of Boolean value for this Field. | Valid values:
Default is true/false (1). | N |
| Yes Value | If | Y | |
| Allow Empty Choice | If fieldType is Choice; Specification for whether or not an empty (blank) option is available for this Choice field in any Universal Task based on this template, allowing the user to clear the value of this field. | N | |
| Allow Multiple Choices | If fieldType is Choice; Specification for whether or not more than one choice can be selected at a time. When multiple choices are selected, the built-in field variable will resolve to a comma-delimited String of choice values. | N | |
| Choice Sort Option | If | Valid values:
Default is Sequence (1). | N |
| Add To Default List View | Specification that the | Boolean; Valid values: true/false. Default is false. | N |
| Length | If | Integer | N |
| Mapping | Field, from a pool of available fields provided for use in a Universal Template, that this Field is mapped to. | Valid values:
| Y |
| Type | Field type for this Field. | Valid values:
Default is Text (1). | N |
| Default Value | Default value for this Field. | Value values by
| N |
| Column Span | Number of columns (width) in the Universal Task (based on this Universal Template) Details for this Field. | Valid values:
Default is 1. | N |
| End Row | Specification that this Field will end the current row. | Boolean; Valid values: true/false. Default is false. | N |
| Start Row | Specification that this Field will start a new row. | Boolean; Valid values: true/false. Default is false. | N |
| Hint | Field hint for this Field in the Controller user interface. | N | |
| Maximum | If | Integer | N |
| Minimum | If | Integer | N |
| Label | Name of this Field to be displayed in the Controller user interface. | Y | |
| Name | Name of this Field in the Controller database. | Y | |
| No Space If Hidden | Specification that a space should not be reserved in place of the hidden field. | Boolean; Valid values: true/false. Default is false. | N |
| Preserve Value If Hidden | Specification that the value of this field should be preserved if the field is hidden. Note A Field with Also, if a Field's | Boolean; Valid values: true/false. Default is false. | N |
| Required | Specification for whether this Field is required or optional. Note If you modify a Universal Template Field to add a Required condition, review and assign an appropriate field value to any Universal Tasks that are no longer in compliance to avoid a Start Failure. | Boolean; Valid values: true/false. Default is false. | N |
| Require If Field | If Note If you modify a Universal Template Field to add or augment a Require If Field condition, review and assign an appropriate field value to any Universal Tasks that are no longer in compliance to avoid a Start Failure. | Valid values:
| N |
| Require If Field Value(s) | If | Y | |
| Require If Visible | Specification that the Field is required if it is visible. Note If you modify a Universal Template Field to add a Require If Visible condition, review and assign an appropriate field value to any Universal Tasks that are no longer in compliance to avoid a Start Failure. | Boolean; Valid values: true/false. Default is false. | N |
| Sequence | For existing Fields only; System-defined; Sequence of this Field among all user-defined Universal Template Fields to be included in the Universal Task Details. Starting sequence is 0 for the first defined Field. | Integer; Read-only. Note
| N |
| Show If Field | If | Valid values:
| N |