Universal Template Web Services

Overview

Universal Controller supports the following RESTful-based web services for Universal Templates, which are listed alphabetically on this page.

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

See Universal Template Properties.

Field Properties

See Field Properties.

Choice Properties

See Choice Properties.

Example Response

  • Status 200 /OK
    Successfully created the universal template with sysId {sysId}.
  • Status 400 /Bad Request
    Create universal template failed. (message)

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

 XML
<universalTemplate exportReleaseLevel="7.2.0.0" retainSysIds="true">
    <agent />
    <agentCluster />
    <agentClusterVar />
    <agentFieldsRestriction>No Restriction</agentFieldsRestriction>
    <agentType>Windows</agentType>
    <agentVar />
<alwaysCancelOnFinish /> <automaticOutputRetrievalFieldsRestriction>Hidden</automaticOutputRetrievalFieldsRestriction> <broadcastCluster /> <broadcastClusterVar />
<commands>         <command>             <asynchronous>true</asynchronous>             <executionOption>In Process</executionOption>             <fields />             <label>1</label>             <name>command</name>             <statuses>                 <status>Queued</status>             </statuses>             <sysId>db947be2c7f046dea54e3e49d3c1d349</sysId>             <timeout />         </command>         <command>             <asynchronous>false</asynchronous>             <executionOption>Out Of Process</executionOption>             <fields/>             <label>2</label>             <name>command2</name>             <statuses>                 <status>Queued</status>             </statuses>             <sysId>e9ddbdbba21d451c8baf3cf11db48c3b</sysId>             <timeout />         </command>     </commands>
   
<createConsole>false</createConsole>
   <credentialFieldsRestriction>Hidden</credentialFieldsRestriction>
   <credentials />
   <credentialsVar />
   <description />
   <desktopInteract>false</desktopInteract>
   <elevateUser>false</elevateUser>
   <environment />
   <environmentVariablesFieldsRestriction>Read Only</environmentVariablesFieldsRestriction>
  <events>         <event>
             <attributes>
                <attribute>
                   <label>attribute_label1</label>
                  <name>attribute_name1</name>
                    <type>Text</type>
              </attribute>
              <attribute>
                     <label>attribute_label2</label>
                     <name>attribute_name2</name>
                     <type>Integer</type>
              </attribute>
              <attribute>
                     <label>attribute_label3</label>
                     <name>attribute_name3</name>
                     <type>Boolean</type>
              </attribute>
              <attribute>
                     <label>attribute_label4</label>
                     <name>attribute_name4</name>
                     <type>Float</type>
              </attribute>
             </attributes>
             <attributesPolicy>Include Attributes</attributesPolicy>
             <description>Global universal event template description.</description>
             <label>Global Universal Event - Label</label>
             <name>global_universal_event_template</name>
             <sysId>66c6e90f5a334378809884a11cb12ac0</sysId>
             <ttl>11</ttl>
        </event>
  <events>

   <exitCodeOutput />
   <exitCodeProcessing>Success Exitcode Range</exitCodeProcessing>
   <exitCodeProcessingFieldsRestriction>Hidden</exitCodeProcessingFieldsRestriction>
   <exitCodeText />
   <exitCodes>0</exitCodes>
   <fields>
       <field>
           <arrayNameTitle />
           <arrayValueTitle />
           <booleanNoValue />
           <booleanValueType>true/false</booleanValueType>
           <booleanYesValue />
           <choiceAllowEmpty>false</choiceAllowEmpty>
           <choiceAllowMultiple>false</choiceAllowEmpty>
           <choiceSortOption>Sequence</choiceSortOption>
           <choices />
           <defaultListView>false</defaultListView>
           <fieldLength />
           <fieldMapping>Text Field 1</fieldMapping>
           <fieldType>Text</fieldType>
           <fieldValue />
           <formColumnSpan>1</formColumnSpan>
           <formEndRow>false</formEndRow>
           <formStartRow>false</formStartRow>
           <hint />
           <intFieldMax />
           <intFieldMin />
           <label>Service</label>
           <name>service</name>
           <noSpaceIfHidden>true</noSpaceIfHidden>
           <preserveValueIfHidden>false</preserveValueIfHidden>
           <required>false</required>
           <requireIfField />
           <requireIfFieldValue />
           <requireIfVisible>true</requireIfVisible>
           <sequence>0</sequence>
           <showIfField>Boolean Field 1</showIfField>
           <showIfFieldValue>true</showIfFieldValue>
           <sysId>f30ae218f2c64e0a96c5c64a7523e215</sysId>
       </field>
       <field>
           <arrayNameTitle />
           <arrayValueTitle />
           <booleanNoValue />
           <booleanValueType>true/false</booleanValueType>
           <booleanYesValue />
           <choiceAllowEmpty>false</choiceAllowEmpty>
           <choiceAllowMultiple>false</choiceAllowEmpty>
           <choiceSortOption>Sequence</choiceSortOption>
           <choices>
               <choice>
               <fieldValue>1</fieldValue>
               <fieldValueLabel>Start</fieldValueLabel>
               <sequence>0</sequence>
               <sysId>95b7d388a2ec407cb5f36768482449b0</sysId>
               <useFieldValueForLabel>false</useFieldValueForLabel>
               </choice>
               <choice>
                   <fieldValue>2</fieldValue>
                   <fieldValueLabel>Stop</fieldValueLabel>
                   <sequence>1</sequence>
                   <sysId>07802a9cae3945769cfecbaeb2d1de70</sysId>
                   <useFieldValueForLabel>false</useFieldValueForLabel>
               </choice>
           </choices>
           <defaultListView>false</defaultListView>
           <fieldLength />
           <fieldMapping>Choice Field 1</fieldMapping>
           <fieldType>Choice</fieldType>
           <fieldValue />
           <formColumnSpan>1</formColumnSpan>
           <formEndRow>false</formEndRow>
           <formStartRow>false</formStartRow>
           <hint /> <intFieldMax />
           <intFieldMin />
           <label>Command</label>
           <name>command</name>
           <noSpaceIfHidden>false</noSpaceIfHidden>
           <preserveValueIfHidden>false</preserveValueIfHidden>
           <required>false</required>
           <requireIfField />
           <requireIfFieldValue />
           <requireIfVisible>false</requireIfVisible>
           <sequence>1</sequence>
           <showIfField>Boolean Field 2</showIfField>
           <showIfFieldValue>false</showIfFieldValue>
           <sysId>88ba718e6b8b4ee984266faf362c3fde</sysId>
       </field>
   </fields>
   <name>UT1</name>
   <outputFailureOnly>true</outputFailureOnly>
   <outputReturnFile />
   <outputReturnNline>100</outputReturnNline>
   <outputReturnSline>1</outputReturnSline>
   <outputReturnText />
   <outputReturnType>NONE</outputReturnType>
   <outputType>STDOUT</outputType>
   <runtimeDir />
   <script />
   <scriptTypeWindows />
   <scriptUnix />
   <scriptWindows>exit 0</scriptWindows>
   <sendVariables>None</sendVariables>
   <sysId>32e34b8d138f40a2afbdda79cb1b1d56</sysId>
   <templateType>Extension</templateType>
   <useCommonScript>false</useCommonScript>
   <variablePrefix>ut1</variablePrefix>
   <waitForOutput>false</waitForOutput>
</universalTemplate>
 JSON
{
    "agent": null,
    "agentCluster": null,
    "agentClusterVar": null,
    "agentFieldsRestriction": "No Restriction",
    "agentType": "Windows",
    "agentVar": null,
"alwaysCancelOnFinish": false, "automaticOutputRetrievalFieldsRestriction": "Hidden", "broadcastCluster": null, "broadcastClusterVar": null,
"commands": [         {             "asynchronous": true,             "executionOption": "In Process",             "fields": [],             "label": "1",             "name": "command",             "statuses": [                 "Queued"             ],             "sysId": "db947be2c7f046dea54e3e49d3c1d349",             "timeout": null         },         {             "asynchronous": false,             "executionOption": "Out Of Process",             "fields": [],             "label": "2",             "name": "command2",             "statuses": [                 "Queued"             ],             "sysId": "e9ddbdbba21d451c8baf3cf11db48c3b",             "timeout": null         }      ],
     
"createConsole": false,
     "credentialFieldsRestriction": "Hidden",
     "credentials": null,
     "credentialsVar": null,
     "description": null,
     "desktopInteract": false,
     "elevateUser": false,
     "environment": [],
     "environmentVariablesFieldsRestriction": "Read Only",
     "exitCodeOutput": null,
     "exitCodeProcessing": "Success Exitcode Range",
     "exitCodeProcessingFieldsRestriction": "Hidden",
     "exitCodeText": null,
     "exitCodes": "0",
     "exportReleaseLevel": "7.2.0.0",
     "fields": [
           {
                 "arrayNameTitle": null,
                 "arrayValueTitle": null,
                 "booleanNoValue": null,
                 "booleanValueType": "true/false",
                 "booleanYesValue": null,
                 "choiceAllowEmpty": false,
                 "choiceAllowMultiple": false,
                 "choiceSortOption": "Sequence",
                 "choices": [],
                 "defaultListView": false,
                 "fieldLength": null,
                 "fieldMapping": "Text Field 1",
                 "fieldType": "Text",
                 "fieldValue": null,
                 "formColumnSpan": 1,
                 "formEndRow": false,
                 "formStartRow": false,
                 "hint": null,
                 "intFieldMax": null,
                 "intFieldMin": null,
                 "label": "Service",
                 "name": "service",
                 "noSpaceIfHidden": true,
                 "preserveValueIfHidden": false,
                 "required": false,
                 "requireIfField": null,
                 "requireIfFieldValue": null,
                 "requireIfVisible": true,
                 "sequence": 0,
                 "showIfField": "Boolean Field 1",
                 "showIfFieldValue": true,
                 "sysId": "f30ae218f2c64e0a96c5c64a7523e215"
           },
           {
                 "arrayNameTitle": null,
                 "arrayValueTitle": null,
                 "booleanNoValue": null,
                 "booleanValueType": "true/false",
                 "booleanYesValue": null,
                 "choiceAllowEmpty": false,
                 "choiceAllowMultiple": false,
                 "choiceSortOption": "Sequence",
                 "choices": [
                       {
                             "fieldValue": "1",
                             "fieldValueLabel": "Start",
                             "sequence": 0,
                             "sysId": "95b7d388a2ec407cb5f36768482449b0",
                             "useFieldValueForLabel": false
                       },
                       {
                             "fieldValue": "2",
                             "fieldValueLabel": "Stop",
                             "sequence": 1,
                             "sysI": "07802a9cae3945769cfecbaeb2d1de70",
                             "useFieldValueForLabel": false
                       }
                 ],
                 "defaultListView": false,
                 "fieldLength": null,
                 "fieldMapping": "Choice Field 1",
                 "fieldType": "Choice",
                 "fieldValue": null,
                 "formColumnSpan": 1,
                 "formEndRow": false,
                 "formStartRow": false,
                 "hint": null,
                 "intFieldMax": null,
                 "intFieldMin": null,
                 "label": "Command",
                 "name": "command",
                 "noSpaceIfHidden": false,
                 "preserveValueIfHidden": false,
                 "required": false,
                 "requireIfField": null,
                 "requireIfFieldValue": null,
                 "requireIfVisible": false,
                 "sequence": 1,
                 "showIfField": "Boolean Field 2",
                 "showIfFieldValue": false,
                 "sysId": "88ba718e6b8b4ee984266faf362c3fde"
           }
     ],
     "name": "UT1",
     "outputFailureOnly": true,
     "outputReturnFile": null,
     "outputReturnNline": "100",
     "outputReturnSline": "1",
     "outputReturnText": null,
     "outputReturnType": "NONE",
     "outputType": "STDOUT",
     "retainSysIds": true,
     "runtimeDir": null,
     "script": null,
     "scriptTypeWindows": null,
     "scriptUnix": null,
     "scriptWindows": "exit 0",
     "sendVariables": "None",
     "sysId": "32e34b8d138f40a2afbdda79cb1b1d56",
     "templateType": "Extension",
     "useCommonScript": false,
     "variablePrefix": "ut1",
     "waitForOutput": false
}


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

  • Status 200 /OK
    Universal template deleted successfully.
  • Status 400 /Bad Request
    Mutual exclusion violation. Cannot specify templatename and templateid at the same time.
  • Status 404 /Not Found
    A universal template with {name/id} does not exist.

Delete a Universal Template: URI Parameters

Parameter

Description

Specifications

Required

Mutually Exclusive With

templateid

ID used within the Controller to identify this Universal Template.

String; URI parameter.

Y (unless templatename is specified)

templatename

templatename

Name used within the Controller to identify this Universal Template.

String; URI parameter.

Y (unless templateid is specified)

templateid

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

See List Universal Templates: XML and JSON Examples.

Universal Template Properties

See Universal Template Properties.

List Universal Templates: URI Parameters

Parameter

Description

Specifications

Required

templatename

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

 XML
<universalTemplates>
<universalTemplate> exportReleaseLevel="7.2.0.0"
<agent />
<agentCluster />
<agentClusterVar />
<agentFieldsRestriction>No Restriction</agentFieldsRestriction>
<agentType>Windows</agentType>
<agentVar />
<alwaysCancelOnFinish />
<automaticOutputRetrievalFieldsRestriction>Hidden</automaticOutputRetrievalFieldsRestriction>
<broadcastCluster /> <broadcastClusterVar />
<commands>         <command>             <asynchronous>true</asynchronous>             <executionOption>In Process</executionOption>             <fields />             <label>1</label>             <name>command</name>             <statuses>                 <status>Queued</status>             </statuses>             <sysId>db947be2c7f046dea54e3e49d3c1d349</sysId>             <timeout />         </command>         <command>             <asynchronous>false</asynchronous>             <executionOption>Out Of Process</executionOption>             <fields/>             <label>2</label>             <name>command2</name>             <statuses>                 <status>Queued</status>             </statuses>             <sysId>e9ddbdbba21d451c8baf3cf11db48c3b</sysId>             <timeout />         </command>     </commands>
<createConsole>false</createConsole>
<credentialFieldsRestriction>Hidden</credentialFieldsRestriction>
<credentials />
<credentialsVar />
<description />
<desktopInteract>false</desktopInteract>
<elevateUser>false</elevateUser>
<environment />
<environmentVariablesFieldsRestriction>Read Only</environmentVariablesFieldsRestriction>
<exitCodeOutput />
<exitCodeProcessing>Success Exitcode Range</exitCodeProcessing>
<exitCodeProcessingFieldsRestriction>Hidden</exitCodeProcessingFieldsRestriction>
<exitCodeText />
<exitCodes>0</exitCodes>
<fields />
<name>UT1</name>
<noSpaceIfHidden>true</noSpaceIfHidden>
<preserveValueIfHidden>false</preserveValueIfHidden>
<outputFailureOnly>true</outputFailureOnly>
<outputReturnFile />
<outputReturnNline>100</outputReturnNline>
<outputReturnSline>1</outputReturnSline>
<outputReturnText />
<outputReturnType>NONE</outputReturnType>
<outputType>STDOUT</outputType>
<runtimeDir />
<script />
<scriptTypeWindows />
<scriptUnix />
<scriptWindows>exit 0</scriptWindows>
<sendVariables>None</sendVariables>
<sysId>32e34b8d138f40a2afbdda79cb1b1d56</sysId>
<templateType>Extension</templateType>
<useCommonScript>false</useCommonScript>
<variablePrefix>ut1</variablePrefix>
<waitForOutput>false</waitForOutput>
</universalTemplate>
<universalTemplate> exportReleaseLevel="7.2.0.0"
<agent />
<agentCluster />
<agentClusterVar />
<agentFieldsRestriction>No Restriction</agentFieldsRestriction>
<agentType>Windows</agentType>
<agentVar />
<alwaysCancelOnFinish />
<automaticOutputRetrievalFieldsRestriction>Hidden</automaticOutputRetrievalFieldsRestriction>
<broadcastCluster />
<broadcastClusterVar />
<commands>         <command>             <asynchronous>true</asynchronous>             <executionOption>In Process</executionOption>             <fields />             <label>1</label>             <name>command</name>             <statuses>                 <status>Queued</status>             </statuses>             <sysId>db947be2c7f046dea54e3e49d3c1d349</sysId>             <timeout />         </command>         <command>             <asynchronous>false</asynchronous>             <executionOption>Out Of Process</executionOption>             <fields/>             <label>2</label>             <name>command2</name>             <statuses>                 <status>Queued</status>             </statuses>             <sysId>e9ddbdbba21d451c8baf3cf11db48c3b</sysId>             <timeout />         </command>     </commands>
<createConsole>false</createConsole>
<credentialFieldsRestriction>Hidden</credentialFieldsRestriction>
<credentials />
<credentialsVar />
<description />
<desktopInteract>false</desktopInteract>
<elevateUser>false</elevateUser>
<environment />
<environmentVariablesFieldsRestriction>Read Only</environmentVariablesFieldsRestriction>
<exitCodeOutput />
<exitCodeProcessing>Success Exitcode Range</exitCodeProcessing>
<exitCodeProcessingFieldsRestriction>Hidden</exitCodeProcessingFieldsRestriction>
<exitCodeText />
<exitCodes>0</exitCodes>
<fields />
<name>UT1</name>
<outputFailureOnly>true</outputFailureOnly>
<outputReturnFile />
<outputReturnNline>100</outputReturnNline>
<outputReturnSline>1</outputReturnSline>
<outputReturnText />
<outputReturnType>NONE</outputReturnType>
<outputType>STDOUT</outputType>
<runtimeDir />
<script />
<scriptTypeWindows />
<scriptUnix />
<scriptWindows>exit 0</scriptWindows>
<sendVariables>None</sendVariables>
<sysId>32e34b8d138f40a2afbdda79cb1b1d56</sysId>
<templateType>Extension</templateType>
<useCommonScript>false</useCommonScript>
<variablePrefix>ut1</variablePrefix>
<waitForOutput>false</waitForOutput>
</universalTemplate>
</universalTemplates>
 JSON

[

  {
"agent": null,
"agentCluster": null, "agentClusterVar": null, "agentFieldsRestriction": "No Restriction", "agentType": "Windows", "agentVar": null,
"alwaysCancelOnFinish": false, "automaticOutputRetrievalFieldsRestriction": "Hidden", "broadcastCluster": null, "broadcastClusterVar": null,
    "commands": [         {             "asynchronous": true,             "executionOption": "In Process",             "fields": [],             "label": "1",             "name": "command",             "statuses": [                 "Queued"             ],             "sysId": "db947be2c7f046dea54e3e49d3c1d349",             "timeout": null         },         {             "asynchronous": false,             "executionOption": "Out Of Process",             "fields": [],             "label": "2",             "name": "command2",             "statuses": [                 "Queued"             ],             "sysId": "e9ddbdbba21d451c8baf3cf11db48c3b",             "timeout": null         }     ],
    "createConsole": false,
    "credentialFieldsRestriction": "Hidden",
    "credentials": null,
    "credentialsVar": null,
    "description": null,
    "desktopInteract": false,
    "elevateUser": false,
    "environment": [],
    "environmentVariablesFieldsRestriction": "Read Only",
    "exitCodeOutput": null,
    "exitCodeProcessing": "Success Exitcode Range",
    "exitCodeProcessingFieldsRestriction": "Hidden",
    "exitCodeText": null,
    "exitCodes": "0",
    "exportReleaseLevel": "0",
    "fields": [],
    "name": "UT1",
    "outputFailureOnly": true,
    "outputReturnFile": null,
    "outputReturnNline": "100",
    "outputReturnSline": "1",
    "outputReturnText": null,
    "outputReturnType": "NONE",
    "outputType": "STDOUT",
    "retainSysIds": true,
    "runtimeDir": null, "script": null,
    "scriptTypeWindows": null,
    "scriptUnix": null,
    "scriptWindows": "exit 0",
    "sendVariables": "None",
    "sysId": "32e34b8d138f40a2afbdda79cb1b1d56",
   "templateType": "Extension",
    "useCommonScript": false,
    "variablePrefix": "ut1",
    "waitForOutput": false },
{
    "agent": null,
    "agentCluster": null,
    "agentClusterVar": null,
    "agentFieldsRestriction": "No Restriction",
    "agentType": "Windows",
    "agentVar": null,
    "alwaysCancelOnFinish": false,
    "automaticOutputRetrievalFieldsRestriction": "Hidden",
    "broadcastCluster": null,
    "broadcastClusterVar": null,
    "commands": [         {             "asynchronous": true,             "executionOption": "In Process",             "fields": [],             "label": "1",             "name": "command",             "statuses": [                 "Queued"             ],             "sysId": "db947be2c7f046dea54e3e49d3c1d349",             "timeout": null         },         {             "asynchronous": false,             "executionOption": "Out Of Process",             "fields": [],             "label": "2",             "name": "command2",             "statuses": [                 "Queued"             ],             "sysId": "e9ddbdbba21d451c8baf3cf11db48c3b",             "timeout": null         }      ],
    "createConsole": false,
    "credentialFieldsRestriction": "Hidden",
    "credentials": null,
    "credentialsVar": null,
    "description": null,
    "desktopInteract": false,
    "elevateUser": false,
    "environment": [],
    "environmentVariablesFieldsRestriction": "Read Only",
    "exitCodeOutput": null,
    "exitCodeProcessing": "Success Exitcode Range",
    "exitCodeProcessingFieldsRestriction": "Hidden",
    "exitCodeText": null,
    "exitCodes": "0",
    "exportReleaseLevel": "0",
    "fields": [],
    "name": "UT1",
    "outputFailureOnly": true,
    "outputReturnFile": null,
    "outputReturnNline": "100",
    "outputReturnSline": "1",
    "outputReturnText": null,
    "outputReturnType": "NONE",
    "outputType": "STDOUT",
    "retainSysIds": true,
    "runtimeDir": null,
    "script": null,
    "scriptTypeWindows": null,
    "scriptUnix": null,
    "scriptWindows": "exit 0",
    "sendVariables": "None",
    "sysId": "32e34b8d138f40a2afbdda79cb1b1d56",
   "templateType": "Extension",
    "useCommonScript": false,
    "variablePrefix": "ut1",
    "waitForOutput": false
}
]


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.
 
To modify Universal Template properties without modifying related records, see the excludeRelated property.

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

See Universal Template Properties.

Field Properties

See Field Properties.

Choice Properties

See Choice Properties.

Example Response

  • Status 200 /OK
    Successfully updated the universaltemplate with sysId <sysId>.
  • Status 400 /Bad Request
    Update universal template failed. (message)

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

See 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

templateid

Unique ID for this Universal Template.


Y
(unless templatename
is specified)

templatename

templatename

Name used within the Controller to identify this Universal Template.

Maximum 40 alphanumerics.

Y
(unless templateid
is specified)

templateid

Properties

Universal Template Properties

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

agent

Agent

Name of the Agent to use.


N

agentVar,
broadcastCluster, and
broadcastClusterVar

agentCluster

Agent Cluster

Group of Agents, one of which the Controller will choose to run this task (compare with broadcastCluster).


N

agentClusterVar,
broadcastCluster, and
broadcastClusterVar

agentClusterVar

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

agentCluster,
broadcastCluster, and
broadcastClusterVar

agentFieldsRestriction

Agent Fields

Restriction to apply to the group of Agent Fields.

Valid values:

  • As String = No Restriction, As Value = 0
  • As String = Read Only, As Value = 1
  • As String = Hidden, As Value = 2

N


agentType

Agent Type

Type of Agent on which Universal Tasks based on this template can be run.

Valid values:

  • As String = Any, As Value = 1
  • As String = Linux/Unix, As Value = 2
  • As String = Windows, As Value = 3

Y


agentVar

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

agent,
broadcastCluster, and
broadcastClusterVar

alwaysCancelOnFinish

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


automaticOutputRetrievalFieldsRestriction

Automatic Output Retrieval Fields

Restriction to apply to the group of Automatic Output Retrieval Fields.

Valid values:

  • As String = No Restriction, As Value = 0
  • As String = Read Only, As Value = 1
  • As String = Hidden, As Value = 2

N


broadcastCluster

Cluster Broadcast

Group of Agents, all of which will run this task (compare with agentCluster). Each instance of the task running on its own Agent becomes a separate task instance record in the database and displays separately on the Activity Monitor.


N

broadcastClusterVar,
agent,
agentVar,
agentCluster, and
agentClusterVar

broadcastClusterVar

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

broadcastCluster,
agent,
agentVar,
agentCluster, and
agentClusterVar

createConsole

Create Console

If desktopInteract is true; Specification for whether or not to allocate a new console for the process, rather than having it inherit one.

Boolean; Valid values: true/false. Default is false.

N


credentialFieldsRestriction

Credential Fields

Restriction to apply to the group of Credential Fields.

Valid values:

  • As String = No Restriction, As Value = 0
  • As String = Read Only, As Value = 1
  • As String = Hidden, As Value = 2

N


credentials

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

credentialsVar

credentialsVar

Credentials Variable

Name of a variable that will be resolved at run time to the name of the {Credentials] to use.


N

credentials

description

Description

Description of this Universal Template.


N


desktopInteract

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.
 
This property is effective only for tasks executed on Windows XP or Server 2003. Windows Vista introduced the desktop isolation feature, which prevents tasks from accessing the interactive desktop session on Vista, Windows 7, Server 2008, Windows 8, and Server 2012. The Windows agent will execute the task, but the Interact with Desktop option has no effect. Therefore, an interactive application's GUI will not be visible on those platforms.

N


elevateUser

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.
 
This property will not give a user account privileges that have are not already granted to it. For example, taking ownership of a file is a privileged operation by default. A task will still fail even with this option selected if it is run with a regular user account that has not been granted the ability to change file ownership.

N


environment

Environment Variables

Environment variables needed by the program to run.

List of environment variables:
 


N


environmentVariableFieldsRestriction

Environment Variable Fields

Restriction to apply to the group of Environment Variables Fields.

Valid values:

  • As String = No Restriction, As Value = 0
  • As String = Read Only, As Value = 1
  • As String = Hidden, As Value = 2

N


excludeRelated

n/a

Specification for whether or not to exclude related records.

Boolean; Valid values: true/false. Default is false.
 
For XML, excludeRelated is specified as an attribute on the universalTemplate element.

N


exitCodeOutput

Output File

Path and file name of the output file that should be scanned for the text in exitCodeText.


N


exitCodeProcessing

Exit Code Processing

Specification for how the Controller should determine whether the executed command failed or completed successfully.

Valid values:

  • As String = Success Exitcode Range, As Value = 1
  • As String = Failure Exitcode Range, As Value = 2
  • As String = Success Output Contains, As Value = 3
  • As String = Failure Output Contains, As Value = 4

Default is Success Exitcode (1).

N


exitCodeProcessingFieldsRestriction

Exit Code Processing Fields

Restriction to apply to the group of Exit Code Processing Fields.

Valid values:

  • As String = No Restriction, As Value = 0
  • As String = Read Only, As Value = 1
  • As String = Hidden, As Value = 2

N


exitCodes

Exit Codes

If exitCodeProcessing is Success Exitcode Range or Failure Exitcode Range; Range of exit codes.

Format: Numeric. Use commas to list a series of exit codes; use hyphens to specify a range. Example: 1,5, 22-30.

Y


exitCodeText

Scan Output For

If exitCodeProcessing is Success Output Contains (3) or Failure Output Contains (4); text for which the Controller should scan the output file.

The Controller will process this field as a regular expression.

Y


exportReleaseLevel

n/a

Universal Controller release that the record was exported from.

read onlyN

name

Name

Name of this Universal Template.


Y


outputFailureOnly

Failure Only

If outputReturnType = STDOUT (2), STDERR (3), FILE (4), or OUTERR (6), and waitForOutput is false; Indication for whether output should be retrieved on task failure only.

Boolean; Valid values: true/false. Default is false.

N


outputReturnFile

Output File

If outputReturnType is FILE; Path and file name containing the output that you want automatically retrieved and attached to the task instance.


N


outputReturnNline

Number of Lines

If outputReturnType is STDOUT, STDERR, FILE, or OUTERR; Limit the retrieved data to this number of lines.

Default is the value of the Retrieve Output Default Maximum Lines Universal Controller system property.

N


outputReturnSline

Start Line

If outputReturnType is STDOUT, STDERR, FILE, or OUTERR; Instructs the Controller to retrieve data beginning at the line indicated.

Default is 1.

N


outputReturnText

Scan Text

If outputReturnType is STDOUT, STDERR, FILE, or OUTERR; Instructs the Controller to scan the data for the text specified and retrieve only that.

The Controller will process this field as a regular expression.

N


outputReturnType

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:

  • As String = NONE, As Value = 1
  • As String = STDOUT, As Value = 2
  • As String = STDERR, As Value = 3
  • As String = FILE, As Value = 4
  • As String = OUTERR, As Value = 6


Default is OUTERR (6).
 


Note

If outputReturnType is not NONE (1), the web service will fail with Start Failure if outputProhibited is true for the specified agent.

N


outputType

Output Type

If exitCodeProcessing is Success Output or Failure Output; Type of output.

Valid values:

  • As String = STDOUT, As Value = 1
  • As String = STDERR, As Value = 2
  • As String = FILE, As Value = 3

Default is STDOUT (1).

N


retainSysIds

n/a

Specification for whether or not the Create a Universal Template web service will persist the sysId property.

Boolean; Valid values: true/false. Default is false.
 
For XML, retainSysIds is specified as an attribute on the universalTemplate element.
 
Used for both the Create and Update web services; for Update, it is used only for the related lists (Fields and Choices). It is recommended that retainSysIds be enabled when updating Choice values so that the command can determine which Choice values have been updated and propagate the new value to Universal Tasks using the previous Choice value.
 
If retainSysIds is not enabled when updating Choice values, the command can determine only which Choice values have been added or removed; Universal Tasks using the previous Choice values will not be updated.

N


runtimeDir

Runtime Directory

Directory from which the application should be executed.

Variables are supported.

N


script

Script

If useCommonScript is true; Script to be executed by the specified Agent.


N


scriptUnix

Linux/Unix Script

If agentType is Any or Linux/Unix; Script to be executed by the Linux/Unix Agent.


N


scriptWindows

Windows Script

If agentType is Any or Windows; Script to be executed by the Windows Agent.


N


scriptTypeWindows

Windows Script File Type

If agentType is Windows; Type of Windows Script to be executed by the Windows Agent.

Valid values:

  • As String = bat
  • As String = cmd
  • As String = js
  • As String = ps1
  • As String = py
  • As String = uapy
  • As String = vbs
  • As String = wsf
  • As String = Other

N


sendVariables

Send Extension Variables

If templateType is Extension; Specification for whether the Extension should be provided with task instance variable data when launched.

Options:

  • None
    Do not provide the Extension with task instance variable data.
  • Local
    Provide the Extension with task instance variable data.

Valid values:

  • As String = None, As Value = 0

  • As String = Local, As Value = 1

Default is None (0).

N

sysId

UUID

System ID field in the database for this record.

Persisted only if retainSysIds is set to true.

N


templateType

Template TypeSpecification for whether the Universal Template will be executed as a Script or will be executed through the Universal Extension framework.

Valid values:

  • As String = Script, As Value = 1

  • As String = Extension, As Value = 2

Default is Script (1).

N

useCommonScript

Use Common Script

Indication that the specified script can be executed by both Linux/Unix and Windows Agents.

Boolean; Valid values: true/false. Default is false.

N


variablePrefix

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


waitForOutput

Wait For Output

If outputReturnType = STDOUT (2), STDERR (3), FILE (4), or OUTERR (6), and outputFailureOnly is false; Specification for whether or not the task should wait for the requested output before completing.

Boolean; Valid values: true/false. Default is false.

N


Field Properties

Property

UI Field Name

Description

Specifications

Required

arrayNameTitle

Name TitleIf fieldType is Array; Title to be displayed for the Name column.
N

arrayValueTitle

Value TitleIf fieldType is Array; Title to be displayed for the Value column.
N

booleanNoValue

No Value

If booleanValueType is Custom; Boolean No value for this Field.


Y
(if booleanValueType
is Custom)

booleanValueType

Boolean Value Type

Type of Boolean value for this Field.

Valid values:

  • As String = true/false, As Value = 1
  • As String = 1/0, As Value = 2
  • As String = Custom, As Value = 3

Default is true/false (1).

N

booleanYesValue

Yes Value

If booleanValueType is Custom; Boolean Yes value for this Field.


Y
(if booleanValueType
is Custom)

choiceAllowEmpty

Allow Empty ChoiceIf 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

choiceAllowMultiple

Allow Multiple ChoicesIf 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

choiceSortOption

Choice Sort Option

If fieldType is Choice; Specification for how Choices will be listed in the Choice field in Universal Task.

Valid values:

  • As String = Sequence, As Value = 1
  • As String = Label, As Value = 2

Default is Sequence (1).

N

defaultListView

Add To Default List View

Specification that the label of this Field will display, by default, in the list of Universal Tasks based on this template.

Boolean; Valid values: true/false. Default is false.

N

fieldLength

Length

If fieldType is Text or Integer; Length of this Field.

Integer

N

fieldMapping

Mapping

Field, from a pool of available fields provided for use in a Universal Template, that this Field is mapped to.

Valid values:

  • As String =
    • Integer Field [1-10]
    • Boolean Field [1-10]
    • Text Field [1-20]
    • Large Text Field [1-2]
    • Choice Field [1-15]
    • Credential Field [1-6]
    • Script Field [1-2]
    • Array Field [1-4]
    • Float Field [1-4)

Y

fieldType

Type

Field type for this Field.

Valid values:

  • As String = Text, As Value = 1
  • As String = Integer, As Value = 2
  • As String = Boolean, As Value = 3
  • As String = Choice, As Value = 4
  • As String = Credential, As Value = 5
  • As String = Script, As Value = 6
  • As String = Array, As Value = 7
  • As String = Float, As Value = 8

Default is Text (1).

N

fieldValue

Default Value

Default value for this Field.

Value values by fieldType:

  • fieldType = Text, fieldValue = string
  • fieldType = Integer, fieldValue = integer
  • fieldType = Boolean, fieldValue = true/false
  • fieldType = Choice, fieldValue = Choice Value
  • fieldType = Credential, fieldValue = Credential Name
  • fieldType = Script, fieldValue = Script Name
  • fieldType = Array, fieldValue = (not supported)
  • fieldType = Float, fieldValue = float

N

formColumnSpan

Column Span

Number of columns (width) in the Universal Task (based on this Universal Template) Details for this Field.

Valid values:

  • As Value = 1:
  • As Value = 2
  • As Value = 3

Default is 1.

N

formEndRow

End Row

Specification that this Field will end the current row.

Boolean; Valid values: true/false. Default is false.

N

formStartRow

Start Row

Specification that this Field will start a new row.

Boolean; Valid values: true/false. Default is false.

N

hint

Hint

Field hint for this Field in the Controller user interface.


N

intFieldMax

Maximum

If fieldType is Integer; Maximum value for this Field.

Integer

N

intFieldMin

Minimum

If fieldType is Integer; Minimum value for this Field.

Integer

N

label

Label

Name of this Field to be displayed in the Controller user interface.


Y

name

Name

Name of this Field in the Controller database.


Y

noSpaceIfHidden

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

preserveValueIfHidden

Preserve Value If Hidden

Specification that the value of this field should be preserved if the field is hidden.

Note

A Field with preserveValueIfHidden = true will be validated even if the Field is hidden.

Also, if a Field's showIfField or requireIfField specifies a field (for example, Boolean Field 1) that has preserveValueIfHidden = true, when validating whether the Field is visible or required, Boolean Field 1’s value is considered visible.

Boolean; Valid values: true/false. Default is false.

N

required

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

requireIfField

Require If Field

If required is false and showIfField is not specified; Specification that this Field in the template will be required in any Universal Tasks based on this template the Choice Field (Choice Field 1-15) or Boolean Field (Boolean Filed 1-10) selected as the Require If Field has a value corresponding to the value(s) defined in the Require If Filed Value(s) field.

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:

  • As String = Choice Field [1-15]
  • As String = Boolean Field [1-10]

N

requireIfFieldValue

Require If Field Value(s)

If requireIfField is not null/empty; Value(s) for the specified requireIfField.


Y
(if requireIfField
is specified)

requireIfVisible

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

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

sequence is included in the XML/JSON by the Read and List web services; however, it is not used by the Create and Update web services. For Create and Update, the sequence is set based on the Field order specified in the XML/JSON.

N

showIfField

Show If Field

If required is false and requireIfField is not specified; Specification that this Field in the template will be visible in any Universal Tasks based on this template if the Choice Field (Choice Field 1-15) or the Boolean Field (Boolean Field 1-10) selected as the Show If Field has a value corresponding to the value(s) defined in the Show If Field Value(s) field.

Valid values:

  • As String = Choice Field [1-15]
  • As String = Boolean Field [1-10]

N

showIfFieldValue

Show If Field Value

If showIfField is not null/empty; Value(s) for the specified showIfField.


Y
If showIfField
is specified.

sysId

n/a

sys_id used within the Controller to identify this Universal Template Field.

Persisted only if retainSysIds is set to true.

N

Choice Properties

Property

UI Field Name

Description

Specifications

Required

fieldValue

Value

Value of this Choice.

Maximum length = 255 characters.

Y

fieldValueLabel

Label

If useFieldValueForLabel is false; Name that will appear for this Choice in the Choice list for a Universal Task. (Maximum = 50 characters.)


Y
(unless useFieldValueForLabel
is true)

sequence

Sequence

For existing Choices only; System-defined sequence of this Choice among all Choices defined for this Field. Starting sequence is 0 for the first defined Choice.

Read-only
 


Note

sequence is included in the XML/JSON by the Read and List web services; however, it is not used by the Create and Update web services. For Create and Update, the sequence is set based on the Choice order specified in the XML/JSON.

N

sysId

n/a

sys_id used within the Controller to identify this Universal Template Field.

Persisted only if retainSysIds is set to true.

N

useFieldValueForLabel

Use Value For Label

If the fieldValue value is 50 characters or less; Use the fieldValue value as the fieldValueLabel value (which is a maximum 50 characters).

Boolean; Valid values: true/false. Default is false.

N

Command Properties

Property

UI Field Name

Description

Specifications

Required

asynchronous

Asynchronous

If executionOption is In Process; Specification for whether the command runs synchronously or asynchronously.

If executionOption is Out Of Process, asynchronous will be ignored.


Boolean; Valid values: true/false. Default is false.


N

executionOption

Execution Option

Specification for whether the command runs out-of-process execution or in-process execution.

Valid values:

  • As String = Out Of Process, As Value = 0
  • As String = In Process, As Value = 1

Default is Out Of Process.

N

fields

Dependent Fields

Universal Template fields (if any) that are required by the command.

The values of those fields are included in the command request.

            <fields>
                <field>Integer Field 1</field>
                <field>Boolean Field 1</field>
                <field>Text Field 1</field>
                <field>Large Text Field 1</field>
                <field>Choice Field 1</field>
                <field>Credential Field 6</field>
                <field>Script Field 1</field>
                <field>Array Field 1</field>
                <field>Float Field 2</field>
            </fields>
            "fields": [
                "Integer Field 1",
                "Boolean Field 1",
                "Text Field 1",
                "Large Text Field 1",
                "Choice Field 1",
                "Credential Field 6",
                "Script Field 1",
                "Array Field 1",
                "Float Field 2"
            ]

Valid values for field:

  • As String =

    • Integer Field [1-10]

    • Boolean Field [1-10]

    • Text Field [1-20]

    • Large Text Field [1-2]

    • Choice Field [1-15]

    • Credential Field [1-6]

    • Script Field [1-2]

    • Array Field [1-4]

    • Float Field [1-4]

N

label

Label

User-friendly display name for the command, to be displayed within the client.


Y

name

Name

Unique name of this command, adhering to the same naming convention as a Universal Template field name.


Y

statuses

Supported Status(es)

Task instance status(es) that the dynamic command should be enabled for.

            <statuses>
                <status>Defined</status>
                <status>Waiting</status>              
            </statuses>
"statuses": [
                "Defined",
                "Waiting"
            ]

Valid values for status:

  • As String = Defined, As Value = 0

  • As String = Waiting, As Value = 10

  • As String = Time Wait, As Value = 15

  • As String = Held, As Value = 20

  • As String = Exclusive Requested, As Value = 22

  • As String = Exclusive Wait, As Value = 23

  • As String = Resource Requested, As Value = 25

  • As String = Resource Wait, As Value = 30

  • As String = Execution Wait, As Value = 33

  • As String = Undeliverable, As Value = 35

  • As String = Queued, As Value = 40

  • As String =  Submitted, As Value = 43

  • As String =  Action Required, As Value = 60

  • As String = Started, As Value = 70

  • As String = Running, As Value = 80

  • As String = Running/Problems, As Value = 81

  • As String = Cancel Pending, As Value = 99

  • As String = In Doubt, As Value = 110

  • As String =  Start Failure, As Value = 120

  • As String = Confirmation Required, As Value = 125

  • As String = Cancelled, As Value = 130

  • As String = Failed, As Value = 140

  • As String = Skipped, As Value = 180

  • As String = Finished, As Value = 190

  • As String = Success, As Value = 200

Y

sysId

n/a

sys_id used within the Controller to identify this Universal Template Field.

Persisted only if retainSysIds is set to true.

N

timeout

Timeout (Seconds)

Optional command timeout, in seconds, if the command requires longer than the System-level default of 60 seconds.


N


Universal Event Template Properties

The excludeRelated and retainSysIds properties are specified as attributes in the <eventTemplate> element of XML web services.

Property

UI Field Name

Description

Specifications

Required

attributesPolicy

Unmapped Attributes Policy

Defines how unmapped/unknown attributes that are in the published event are handled.

Valid values:

  • As String = Prohibit Universal Event, As Value = 1

  • As String = Include Attributes, As Value = 2

  • As String = Exclude Attributes, As Value = 3

Default is Prohibit Universal Event (1).

N

attributes

Attributes

Zero or more attributes, specifying their Name, Label, and Type.

 XML
    <attributes>
        <attribute>
            <label>attribute_label1</label>
            <name>attribute_name1</name>
            <type>Text</type>
        </attribute>
        <attribute>
            <label>attribute_label2</label>
            <name>attribute_name2</name>
            <type>Integer</type>
        </attribute>
    </attributes>
 JSON
    "attributes": [
        {
            "label": "attribute_label1",
            "name": "attribute_name1",
            "type": "Text"
        },
        {
            "label": "attribute_label2",
            "name": "attribute_name2",
            "type": "Integer"
        }
    ]
N

description

Description

Description of the Universal Event.


N

label

Label

User-friendly display name for the event, to be displayed within the client.

The Label must be unique.

Y

name

Name

Unique event name, adhering to the same naming convention as a Universal Template field name.


Y

ttl

Time To Live

Default value for Time to live; how long, in minutes, the Universal Event data is valid.

non-negative Integer

N

sysId

n/asys_id used within the Controller to identify this record.Persisted only if retainSysIds is set to true.N

Universal Event Template - Attribute Properties

Property

UI Field Name

Description

Specifications

Required

label

Label

User-friendly display name for the attribute, to be displayed within the client.

Attribute Label must be unique.

Y

name

Name

Unique attribute name, adhering to the same naming convention as a Universal Template field name.


Y

type

Type

Attribute type.

Valid values:

  • As String = Text, As Value = 1

  • As String = Integer, As Value = 2

  • As String = Boolean, As Value = 3

  • As String = Float, As Value = 4

Y


Restore Default Universal Template Icon

A Universal Template cannot have its icon restore or set to the default without appropriate update permissions. Additionally, built-in templates cannot be the targets of these requests.


Description

URI

http://host_name/uc/resources/universaltemplate/restoredefaulticon

HTTP Method

POST

Description

Restores the icon of a specific Universal Template to its default.

URI Parameters

See Restore Default Universal Template: URI Parameters, below.

Example URI

AuthenticationHTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

plain/text

Example Response

  • Status 200

    • Successfully restored the default icon for Universal Template “{templatename}”.

    • Universal Template "{templatename}" already using the default icon.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A Universal Template with name “{templatename}” does not exist.

    • A Universal Template with id "{templateid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Note

The Post request must include an attached binary file; specifically, it must be a 48 x 48 pixel PNG file.

The process will fail if either:

  • The file is omitted.
  • The file is of the wrong MIME type.
  • The file has incorrect dimensions.

Restore Default Universal Template Icon: URI Parameters

Name

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

templateid

n/a

ID used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templatename
is specified)

templatename

templatename

n/a

Name used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templateid
is specified)

templateid

Set Universal Template Icon

A Universal Template cannot have its icon restore or set to the default without appropriate update permissions. Additionally, built-in templates cannot be the targets of these requests.


Description

URI

http://host_name/uc/resources/universaltemplate/seticon

HTTP Method

POST

Note

The Post request must include an attached binary file; specifically, it must be a 48 x 48 pixel PNG file.

If the file is omitted, of the wrong MIME type, or has incorrect dimensions, the process will fail.

Description

Upload a 48 x 48 pixel to be set as the custom icon for a specific Universal Template.

Example URI

AuthenticationHTTP Basic

Consumes Content-Type

application/octet-stream, image/png

Produces Content-Type

plain/text

Example Response

  • Status 200

    • Successfully set icon for Universal Template “{templatename}”.

  • Status 400

    • PNG image is not 48 x 48 pixels.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A Universal Template with name “{templatename}” does not exist.

    • A Universal Template with id "{templateid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Note

The Post request must include an attached binary file; specifically, it must be a 48 x 48 pixel PNG file.

The process will fail if either:

  • The file is omitted.
  • The file is of the wrong MIME type.
  • The file has incorrect dimensions.

Set Universal Template Icon: URI Parameters

Name

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

templateid

n/a

ID used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templatename
is specified)

templatename

templatename

n/a

Name used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templateid
is specified)

templateid

Universal Template - Delete Extension Archive


Description

URI

http://host_name/uc/resources/universaltemplate/extension

HTTP Method

DELETE

Description

Delete an Extension Archive for a Universal Template.

URI Parameters

See Delete Extension Archive: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/universaltemplate/extension?templatename=Template1

AuthenticationHTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

n/a

Example Response

  • Status 200

    • Successfully removed Extension Archive from universal template "{templatename}".

  • Status 400

    • Universal template "{templatename}" is not an Extension template type.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A universal template with name “{templatename}” does not exist.

    • A universal template with id "{templateid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Delete Extension Archive: URI Parameters

The following URI parameters will be needed for deleting the Extension Archive.

Name

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

templateid

n/a

ID used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templatename
is specified)

templatename

templatename

n/a

Name used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templateid
is specified)

templateid

Example

curl --request DELETE "http://localhost:8080/uc/resources/universaltemplate/extension?templatename=Template1" --header "Authorization: Basic ****************"

Universal Template - Download Extension Archive


Description

URI

http://host_name/uc/resources/universaltemplate/extension

HTTP Method

GET

Description

Download an Extension Archive for a Universal Template.

URI Parameters

See Download Extension Archive: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/universaltemplate/extension?templatename=Template1

AuthenticationHTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/octet-stream

Example Response

  • Status 200

    • [Binary data sent in response]

  • Status 400

    • Universal template "{templatename}" is not an Extension template type.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A universal template with name “{templatename}” does not exist.

    • A universal template with id "{templateid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Download Extension Archive: URI Parameters

The following URI parameters will be needed for downloading the Extension Archive.

Name

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

templateid

n/a

ID used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templatename
is specified)

templatename

templatename

n/a

Name used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templateid
is specified)

templateid

Example

curl --location --request GET "http://localhost:8080/uc/resources/universaltemplate/extension?templatename=Template1" --header "Content-Type: application/octet-stream" --header "Authorization: Basic ****************" -O -J

Universal Template - Upload Extension Archive


Description

URI

http://host_name/uc/resources/universaltemplate/extension

HTTP Method

POST

Note

The Post request must include an attached binary file; specifically, it must be a zip file.

Description

Upload an Extension Archive for a Universal Template.

URI Parameters

See Upload Extension Archive: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/universaltemplate/extension?templatename=Template1

AuthenticationHTTP Basic

Consumes Content-Type

application/octet-stream, application/zip, application/x-zip-compressed

Produces Content-Type

plain/text

Example Response

  • Status 200

    • Successfully updated Extension Archive for universal template "{templatename}".

  • Status 400

    • Universal template "{templatename}" is not an Extension template type.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A universal template with name “{templatename}” does not exist.

    • A universal template with id "{templateid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Upload Extension Archive: URI Parameters

The following URI parameters will be needed for uploading the Extension Archive.

Name

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

templateid

n/a

ID used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templatename
is specified)

templatename

templatename

n/a

Name used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templateid
is specified)

templateid

Example

curl --data-binary @extension.zip "http://localhost:8080/uc/resources/universaltemplate/extension?templatename=Template1" --header "Content-Type: application/octet-stream" --header "Authorization: Basic ****************"

Universal Template - Export


Description

URI

http://host_name/uc/resources/universaltemplate/exporttemplate

HTTP Method

GET

Description

Download the zip file of a Universal Template specified by a URI parameter.

The file will contain the following entries:

  • template.json
  • template_icon.png (if it exists)
  • extension_archive.zip (if it exists and the excludeExtension parameter is not set to true)

URI Parameters

See Universal Template Export: URI Parameters, below.

Example URI

AuthenticationHTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/octet-stream

Example Response

  • Status 200

    • [Binary data sent in response]

  • Status 403

    • Operation prohibited for built-in universal templates.

    • Operation prohibited due to security constraints.

  • Status 404

    • A universal template with name “{templatename}” does not exist.

    • A universal template with id "{templateid}" does not exist.

  • Status 500

    • Read universal template failed. {errors}

    • Unexpected request failure. See log(s) for more details.

Universal Template Export: URI Parameters

The following URI parameters will be needed for exporting the Universal Template.

Name

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

templateid

n/a

ID used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templatename
is specified)

templatename

templatename

n/a

Name used within the Controller to identify the Universal Template.

String; URI parameter

Y
(unless templateid
is specified)

templateid

excludeExtensionn/a

Indication of whether the extension archive zip file should be excluded in the export operation.

Boolean (True/False, true/false); URI parameter

N
(false by default)

Example

curl --location --request GET "http://localhost:8008/uc/resources/universaltemplate/exporttemplate?templatename=Template1" 
--header "Content-Type: application/octet-stream" --header "Authorization: Basic xxxxxxxxxxxxxxxxxxx" -O -J

Export File Entries

The downloaded Universal Template zip file will include the following required/optional entries:

File Name

Description

Present If…

template.json

The Universal Template definition in JSON format.

Always

template_icon.png

The Universal Template Icon in PNG format.

Icon metadata will be set as attributes in the Universal Template JSON.

The template has an icon.

extension_archive.zip

The Universal Template Extension Archive in ZIP format.

The template has an extension and the optional query parameter excludeExtension is not set to true.

Universal Template - Import


Description

URI

http://host_name/uc/resources/universaltemplate/importtemplate

HTTP Method

POST

Description

Upload the zip file of a Universal Template to be created/updated.

URI Parameters

See Universal Template Import: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/universaltemplate/importtemplate

AuthenticationHTTP Basic

Consumes Content-Type

application/octet-stream, application/zip, application/x-zip-compressed

Produces Content-Type

plain/text

Example Response

  • Status 200

    • Successfully imported universal template. Created new template with id {sysid}

    • Successfully imported universal template. Updated existing template with id {sysId}

  • Status 400

    • The attached Template is invalid. Please re-import your Template.

    • Template cannot be greater than {maximum_template_size} bytes.

    • Template must contain template.json/template_icon.png/extension_archive.zip.

    • Cluster Node release level is {current_release_level}, which does not meet the minimum release level of {min_release_level} for the Template.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

    • Operation prohibited due to security constraints.

Binary Data

The uploaded Universal Template zip file will include the following required/optional entries:

File Name

Description

Optional

template.json

The Universal Template definition in JSON format.

No

template_icon.png

The Universal Template Icon in PNG format.

Icon metadata will be set as attributes in the Universal Template JSON.

Yes

extension_archive.zip

The Universal Template Extension Archive in ZIP format.

Yes

Example

curl --data-binary @unv-tmplt-Template1.zip "http://localhost:8080/uc/resources/universaltemplate/importtemplate" 
--header "Content-Type: application/octet-stream" --header "Authorization: Basic ****************"