Overview

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

Create a Global Variable
Delete a Global Variable
List Variables
List Variables - Advanced
Modify a Global Variable
Read a Global Variable
Set Variable

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

Create a Global Variable

	Description
URI	http://host_name/uc/resources/variable
HTTP Method	POST
Description	Creates a Global Variable.
Example URI	http://localhost:8080/uc/resources/variable
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Create a Global Variable: Example Request, below.
Request Properties	See Global Variable Properties, below.
Example Response	Status 200 /OK Successfully created the variable with sysId {sysId} to version {version}.

Create a Global Variable: Example Request

XML Request

JSON Request

XML Request

 <variable retainSysIds="true">
	<description>description</description>
	<name>demo_ops_global</name>
	<opswiseGroups>
		<opswiseGroup>group 1</opswiseGroup>
		<opswiseGroup>group 2</opswiseGroup>
	</opswiseGroups>
	<sysId>237f9f6c43d2617201b2bd04063f917a</sysId>
	<value>Global</value>
</variable>

JSON Request

{
  "description": "description",
  "name": "demo_ops_global",
  "opswiseGroups": ["group 1", "group 2"],
  "retainSysIds": true,
  "sysId": "237f9f6c43d2617201b2bd04063f917a",
  "value": "Global"
}

Global Variable Properties

Property	UI Field Name	Description	Specifications	Required
`created`	Created	Time when this variable was created	Read only	N
`createdBy`	Created By	User who created this variable	Read only	N
`description`	Description	User-defined; description of this record.		N
`name`	Name	Name used within the Controller to identify this Global Variable.	Contains a maximum of 40 alphanumerics.	Y
`opswiseGroups`	Member of Business Services	Business Services that this record belongs to. XML <opswiseGroups> <opswiseGroup>test</opswiseGroup> </opswiseGroups> JSON "opswiseGroups": ["test"]		N
`retainSysIds`	n/a	Specification for whether or not the Create a Create a Global Variable web service will persist the sysId property. If `retainSysIds`="true" and `sysId` is included in the request/response, `sysId` will be persisted to the database. If `retainSysIds`="false" and `sysId` is included in the request/response, `sysId` will be ignored; it will be autogenerated by the Controller. Note In XML, `retainSysIds` is specified as an attribute in the <variable> element.	Valid values: true/false (default is true).	N
`sysId`	n/a	System ID field in the database for a record.	Persisted only if retainSysIds is set to true.	N
`updated`	Updated	Time when this variable was last updated	Read only	N
`updatedBy`	Updated By	User who last updated this variable	Read only	N
`value`	Value	Value of this variable.	Maximum = 25000 characters.	N

Delete a Global Variable

	Description
URI	http://host_name/uc/resources/variable
HTTP Method	DELETE
Description	Deletes a Global Variable.
URI Parameters	See Delete a Global Variable: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/variable?variableid=dadf6b84c0a8016500a01a10da5e2c15
Example Response	Status 200 /OK Variable deleted successfully. Status 400 /Bad Request Mutual exclusion violation. Cannot specify `variablename` and `variableid` at the same time. Status 404 /Not Found A variable with {name/id} "test" does not exist.

Delete a Global Variable: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`variableid`	ID used within the Controller to identify this Global Variable.	String; URI parameter.	Y (unless `variablename` is specified)	`variablename`
`variablename`	Name used within the Controller to identify this Global Variable.	String; URI parameter.	Y (unless `variableid` is specified)	`variableid`

List Variables

	Description
URI	http://host_name/uc/resources/variable/list
HTTP Method	POST
Description	Retrieves information on variables matching specific search criteria.
Example URI	http://localhost:8080/uc/resources/variable/list
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See List Global Variables: XML and JSON Examples.
Request Properties	See List Variables: Request Properties.
Example Response	See List Global Variables: XML and JSON Examples.
Response Properties	See List Variables: Response Properties.

List Variables: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

Global Variable
<variable-query-filter>
    <scope>global</scope>
</variable-query-filter>

<variable-query-filter>
    <scope>global</scope>
    <variableName>demo*</variableName>
</variable-query-filter>

Local Variable
<variable-query-filter>
    <scope>local</scope>
</variable-query-filter>

<variable-query-filter>
    <scope>local</scope>
    <variableName>*2</variableName>
</variable-query-filter>

Task Variable
<variable-query-filter>
    <scope>task</scope>
    <taskName>UT-WS-Task</taskName>
</variable-query-filter>

<variable-query-filter>
    <scope>task</scope>
    <taskName>UT-WS-Task</taskName>
    <variableName>UT*2</variableName>
</variable-query-filter>

Trigger Variable
<variable-query-filter>
    <scope>trigger</scope>
    <triggerName>UT-WS-Trigger</triggerName>
</variable-query-filter>

<variable-query-filter>
    <scope>trigger</scope>
    <triggerName>UT-WS-Trigger</triggerName>
    <variableName>*2</variableName>
</variable-query-filter>

JSON

Global Variable
{
  "scope": "global"
}

{
  "scope": "global",
  "variableName": "demo*"
}

Local Variable
{
  "scope": "local"
}

{
  "scope": "local",
  "variableName": "*2"
}

Task Variable
{
  "scope": "task",
  "taskName": "UT-WS-Task"
}

{
  "scope": "task",
  "taskName": "UT-WS-Task",
  "variableName": "UT*2"
}

Trigger Variable
{
  "scope": "trigger",
  "triggerName": "UT-WS-Trigger"
}

{
  "scope": "trigger",
  "triggerName": "UT-WS-Trigger",
  "variableName": "*2"
}

Example Response

XML

Example 1
<variables>
    <variable>
        <description />
        <name>demo_ops_download_dir</name>
        <sysId>db5c436ac0a8016501f1ab660b585961</sysId>
        <type>Global</type>
        <version>1</version>
        <value>/home/uc/download</value>
    </variable>
    <variable>
        <description />
        <name>demo_ops_linux_rc</name>
        <sysId>db5c7b72c0a80165004cda781dbf3115</sysId>
        <type>Global</type>
        <version>1</version>
        <value>0</value>
    </variable>
</variables>
 
Example 2
<variables>
    <variable>
        <allowEmptyOption>false</allowEmptyOption>
        <allowUnlistedOption>false</allowEmptyOption>
        <description>varDescription2</description>
        <name>UT_WS_var_2</name>
        <options>
           <option>option1</option>
           <option>option2</option>
        </options>
        <sysId>164a03300a0a0a6475b497e5d985c1aa</sysId>
        <taskId>164a02a80a0a0a644fc9a3d6dd33f72b</taskId>
        <taskName>UT-WS-Task</taskName>
        <type>Task</type>
        <value>varVal2</value>

    </variable>
    <variable>
        <allowEmptyOption>true</allowEmptyOption>
        <allowUnlistedOption>true</allowEmptyOption>
        <description />
        <name>UT_WS_var_2</name>
        <options>
           <option>111</option>
           <option>222</option>
        </options>
        <sysId>164ea9ff0a0a0a6449f209da49f594c0</sysId>
        <triggerId>164ea9a40a0a0a647df8372b88eb2394</triggerId>
        <triggerName>UT-WS-Trigger</triggerName>
        <type>Trigger</type>
        <value>val</value>
    </variable>
</variables>

JSON

Example 1
[
  {    
  "description": null,
  "name": "demo_ops_download_dir",
  "sysId": "db5c436ac0a8016501f1ab660b585961",
  "type": "Global",
  "version": 1,
  "value": "/home/uc/download"
  },
  {
  "description": null,
  "name": "demo_ops_linux_rc",
  "sysId": "db5c7b72c0a80165004cda781dbf3115",
  "type": "Global",
  "version": 1,
  "value": 0
  }
]
 
Example 2
[
  {
  "allowEmptyOption": false,
  "allowUnlistedOption": false,
  "description": "varDescription2",
  "name": "UT_WS_var_2",
  "options": [
     "option1",
     "option2"
  ]
  "sysId": "164a03300a0a0a6475b497e5d985c1aa",
  "taskId": "164a02a80a0a0a644fc9a3d6dd33f72b",
  "taskName": "UT-WS-Task",
  "type": "Task",
  "value": "varVal2"
  },
  {
  "allowEmptyOption": true,
  "allowUnlistedOption": true,
  "description" null,
  "name": "UT_WS_var_2",
  "options": [
     "111",
     "222"
  ]
  "sysId": "164ea9ff0a0a0a6449f209da49f594c0",
  "triggerId": "164ea9a40a0a0a647df8372b88eb2394",
  "triggerName": "UT-WS-Trigger",
  "type": "Trigger",
  "value": "val"
  }
]

List Variables: Request Properties

Property	UI Field Name	Description	Specifications	Required
`scope`	n/a	Type of variable to be returned in the Response.	Valid values (case insensitive): global local task trigger Default is global.	N
`taskName`	n/a	If `scope` is task; Name of task.		Y
`triggerName`	n/a	If `scope` is trigger; Name of the trigger.		Y
`variableName`	n/a	If `scope` is global (or local), and `variableName` is not specified, all Global (or Local) variables are returned in the Response. If `scope` is Global (or Local), and `variableName` is specified, all Global (or Local) variables matching that name are returned in the Response.	Wildcards are supported.	N

List Variables: Response Properties

Property	UI Field Name	Description
`description`	Description	Description of the variable.
`name`	Name	Name of the variable.
`sysId`	n/a	sys_id used within the Controller to identify this variable.
`taskId`	n/a	ID of the task if the search was for a task-specific variable (`scope` is task in the Request).
`taskName`	n/a	Name of the task if the search was for a task-specific variable (`scope` is task in the Request).
`triggerId`	n/a	ID of the trigger if the search was for a trigger-specific variable (`scope` is trigger in the Request).
`triggerName`	n/a	Name of the trigger if the search was for a trigger-specific variable (`scope` is trigger in the Request).
`type`	n/a	Type of variable.
`value`	Value	Value of the variable.
`version`	Version	Version of the variable.
`options`	Value Options	Not for Global Variables. <options> <option>option1</option> <option>option2</option> </options> Note An `option` value will be set only if non-empty; for example, `<option></option>` will not set an option. Duplicate `option` values will not be set; for example, `<option>option1</option>`, `<option>option1</option>` is not permitted. Only one `option1` entry is added.
`allowEmptyOption`	Allow Empty Option	Not for Global Variables. `<allowEmptyOption>true/false</allowEmptyOption>`
`allowUnlistedOption`	Allow Unlisted Option	Not for Global Variables. `<allowUnlistedOption>true/false</allowUnlistedOption>`

List Variables - Advanced

List Variables - Advanced support filtering results using business services that the variables belongs to. It is only applicable for global and local scope variables.

When passing the business services as a request filter for local scope variable, the results will be filtered on the task or triggers, which belongs to the specified business services.

For task and/or trigger scope , business services filter can be ignored.

	Description
URI	http://host_name/uc/resources/variable/listadv
HTTP Method	GET
Description	Retrieves variables details using specific query parameters.
Example URI	http://localhost:8080/uc/resources/variable/listadv http://localhost:8080/uc/resources/variable/listadv?variablename=test http://localhost:8080/uc/resources/variable/listadv?variablename=test&businessServices=A http://localhost:8080/uc/resources/variable/listadv?variablename=test&scope=task&taskname=task-1 http://localhost:8080/uc/resources/variable/listadv?variablename=test&scope=trigger&triggername=trigger-1
Authentication	HTTP Basic
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
URI Properties	See List Variables - Advanced: URI Parameters.
Example Response	See List Variables - Advanced: XML and JSON Examples.

List Variables - Advanced: URI Parameters

Parameter	Description		Specifications	Required
`businessServices`	n/a	Business Services that this Variable belongs to.	String value of comma separated business service	N
`scope`	n/a	Type of variable to be returned in the Response.	Valid values (case insensitive): global local task trigger Default is global.	N
`taskname`	n/a	If scope is task; Name of task.		Y (if `scope` = task)
`triggername`	n/a	If scope is trigger; Name of the trigger.		Y (if `scope` = trigger)
`variablename`	n/a	If `scope` is global (or local), and `variableName` is not specified, all Global (or Local) variables are returned in the Response. If `scope` is global (or local), and `variableName` is specified, all Global (or Local) variables matching that name are returned in the Response.	Wildcards are supported.	N

List Variables - Advanced: Example Response

XML Response

JSON Response

XML Response

<variables>
    <variable exportReleaseLevel="7.2.0.0" exportTable="ops_variable" retainSysIds="true" version="2">
        <created>2024-11-11 13:59:13 -0500</created>
        <createdBy>ops.admin</createdBy>
        <description>test 1</description>
        <name>var_1</name>
        <opswiseGroups>
            <opswiseGroup>A</opswiseGroup>
            <opswiseGroup>B</opswiseGroup>
        </opswiseGroups>
        <sysId>c4f499ac6a104d3891a5a06398c02fbe</sysId>
        <updated>2024-11-11 13:59:13 -0500</updated>
        <updatedBy>ops.admin</updatedBy>
        <value>test1</value>
    </variable>
</variables>
OR
<variables>
    <variable exportReleaseLevel="7.2.0.0" exportTable="ops_variable" >
        <description>varDescription2</description>
        <name>UT_WS_var_2</name>
        <sysId>164a03300a0a0a6475b497e5d985c1aa</sysId>
        <taskId>164a02a80a0a0a644fc9a3d6dd33f72b</taskId>
        <taskName>UT-WS-Task</taskName>
        <type>Task</type>
        <value>varVal2</value>
    </variable>
    <variable exportReleaseLevel="7.2.0.0" exportTable="ops_variable" >
        <description />
        <name>UT_WS_var_2</name>
        <sysId>164ea9ff0a0a0a6449f209da49f594c0</sysId>
        <triggerId>164ea9a40a0a0a647df8372b88eb2394</triggerId>
        <triggerName>UT-WS-Trigger</triggerName>
        <type>Trigger</type>
        <value>val</value>
    </variable>
</variables>

JSON Response

[
  {
    "created": "2024-11-11 16:04:20 -0500",
    "createdBy": "ops.admin",
    "description": "test 1",
    "exportReleaseLevel": "7.2.0.0",
    "exportTable": "ops_variable",
    "name": "var_1",
    "opswiseGroups": [
      "A",
      "B"
    ],
    "retainSysIds": true,
    "sysId": "c4f499ac6a104d3891a5a06398c02fbe",
    "updated": "2024-11-11 16:09:09 -0500",
    "updatedBy": "ops.admin",
    "value": "test1",
    "version": 2
  }
]
OR
[
  {
    "description": "varDescription2",
    "exportReleaseLevel": "7.2.0.0",
    "exportTable": "ops_variable",
    "name": "UT_WS_var_2",
    "sysId": "164a03300a0a0a6475b497e5d985c1aa",
    "taskId": "164a02a80a0a0a644fc9a3d6dd33f72b",
    "taskName": "UT-WS-Task",
    "type": "Task",
    "value": "varVal2"
  },
  {
    "description" null,
    "exportReleaseLevel": "7.2.0.0",
    "exportTable": "ops_variable",
    "name": "UT_WS_var_2",
    "sysId": "164ea9ff0a0a0a6449f209da49f594c0",
    "triggerId": "164ea9a40a0a0a647df8372b88eb2394",
    "triggerName": "UT-WS-Trigger",
    "type": "Trigger",
    "value": "val"
  }
]

Modify a Global Variable

	Description
URI	http://host_name/uc/resources/variable
HTTP Method	PUT
Description	Modifies the Global Variable specified by the `sysId`.
Example URI	http://localhost:8080/uc/resources/variable
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Modify a Global Variable: Example Request, below.
Request Properties	See Global Variable Properties.
Example Response	Status 200 /OK Successfully updated the variable with sysId <sysId> to version <version>.

Modify a Global Variable: Example Request

XML Request

JSON Request

XML Request

 <variable>
	<description>description</description>
	<name>demo_ops_global</name>
	<opswiseGroups>
		<opswiseGroup>group 1</opswiseGroup>
		<opswiseGroup>group 2</opswiseGroup>
	</opswiseGroups>
	<sysId>237f9f6c43d2617201b2bd04063f917a</sysId>
	<value>Global</value>
</variable>

JSON Request

{
  "description": "description",
  "name": "demo_ops_global",
  "opswiseGroups": ["group 1", "group 2"],
  "sysId": "237f9f6c43d2617201b2bd04063f917a",
  "value": "Global"
}

Read a Global Variable

	Description
URI	http://host_name/uc/resources/variable
HTTP Method	GET
Description	Retrieves information on a specific Global Variable.
URI Parameters	See Read a Global Variable: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/variable?variablename=demo_ops_global
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example Response	See Read a Global Variable: Example Response , below.
Response Properties	See Global Variable Properties.

Read a Global Variable: URI Parameters

Name	Description	Specifications	Required	Mutually Exclusive With
`variableid`	Unique ID for this Global Variable.		Y (unless `variablename` is specified)	`variablename`
`variablename`	Name used within the Controller to identify this Global Variable.	Maximum 40 alphanumerics.	Y (unless `variableid` is specified)	`variableid`

Read a Global Variable: Example Response

XML Response

JSON Response

XML Response

<variable exportReleaseLevel="7.2.0.0" exportTable="ops_variable" retainSysIds="true" version="1">
    <created>2024-11-11 13:59:13 -0500</created>
    <createdBy>ops.admin</createdBy>
    <description>description</description>
    <name>demo_ops_global</name>
    <opswiseGroups>
        <opswiseGroup>group 1</opswiseGroup>
        <opswiseGroup>group 2</opswiseGroup>
    </opswiseGroups>
    <sysId>237f9f6c43d2617201b2bd04063f917a</sysId>
    <updated>2024-11-11 13:59:13 -0500</updated>
    <updatedBy>ops.admin</updatedBy>
    <value>Global</value>
</variable>

JSON Response

{
  "created": "2024-11-11 16:04:20 -0500",
  "createdBy": "ops.admin",
  "description": "description",
  "exportReleaseLevel": "7.2.0.0",
  "exportTable": "ops_variable",
  "name": "demo_ops_global",
  "opswiseGroups": ["group 1","group 2"],
  "sysId": "237f9f6c43d2617201b2bd04063f917a",
  "retainSysIds": true,
  "updated": "2024-11-11 16:09:09 -0500",
  "updatedBy": "ops.admin",
  "value": "Global",
  "version": 1
}

Set Variable

	Description
URI	http://host_name/uc/resources/variable/ops-variable-set
HTTP Method	POST
Description	Sets the specified variable.
Example URI	http://localhost:8080/uc/resources/variable/ops-variable-set
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Set Variables: Request Examples.
Example Response	See Set Variables: Response Examples.
Properties	See Set Variables Properties.

Set Variable: Request Examples

XML Request

JSON Request

XML

Global Variable
<set-variable>
    <create>true</create>
    <variable>
        <name>testGlobalVar</name>
        <description>testGlobalVar description</description>
        <value>testGlobalVar val</value>
    </variable>
</set-variable>
 
Task Variable
<set-variable>
    <create>true</create>
    <scope>task</scope>
    <task>Timer 60</task>
    <variable>
        <description>testTaskVar description</description>
        <name>testTaskVar</name>
        <value>testTaskVar val</value>
    </variable>
</set-variable>
 
Trigger Variable
<set-variable>
    <create>true</create>
    <scope>trigger</scope>
    <trigger>uc - Mon-Fri 9-5</trigger>
    <variable>
        <description>testTriggerVar description</description>
        <name>testTriggerVar</name>
        <value>testTriggerVar val</value>
    </variable>
</set-variable>

JSON

Global Variable
{
  "create": true,
   "variable": {
    "name": "testGlobalVar",
    "description": "testGlobalVar description",
    "value": "testGlobalVar val"
  }
}
 
Task Variable
{
  "create": true,
  "scope": "task",
  "task": "Timer 60",  
  "variable": {
    "name": "testTaskVar",
    "description": "testTaskVar description",
    "value": "testTaskVar val"
  }
}
Trigger Variable
{
  "create": true,
  "scope": "trigger",
  "trigger": "uc - Mon-Fri 9-5",  
  "variable": {
    "name": "testTriggerVar",
    "description": "testTriggerVar description",
    "value": "testTriggerVar val"
  }
}

Set Variable: Response Examples

XML Response

JSON Response

XML

<command-response>
    <type>set_variable</type>
    <success>true</success>
    <info>Variable testGlobalVar not found., Successfully created variable=testGlobalVar with value=testGlobalVar val.</info>
    <errors />
</command-response>

JSON

{
  "type": "set_variable",
  "success": true,
  "info": "Variable testGlobalVar not found., Successfully created variable=testGlobalVar with value=testGlobalVar val.",
  "errors": ""
}

Set Variable Properties

Property	UI Field Name	Description	Specifications	Required
`create`	n/a	Specification for whether or not to create a variable.	Boolean; Valid values: true/false.	N
`description`	Description	Description of the variable.		N
`exportReleaseLevel`	n/a	Universal Controller release that the record was exported from.	read only	N
`exportTable`	n/a	Record table information.	read only	N
`name`	Name	Name of the variable.		Y
`scope`	n/a	Type of variable to be returned in the XML Response.	Valid values: global, task, trigger (case insensitive). Default is global.	N
`task`	n/a	If `scope` is task; Name of the task.		Y
`trigger`	n/a	If `scope` is trigger; Name of the trigger.		Y
`value`	Value	Value of the variable.	Maximum = 25000 characters.	Y

Browser not supported