Variable Web Services

Owned by Stonebranch (Deactivated)
Jul 10, 2024

Overview

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

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

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



 
JSON


N

retainSysIds

n/a

Specification for whether or not the Create a Create a Global Variable web service will persist the sysId property.




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

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

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">
        <description>test 1</description>
        <name>var_1</name>
        <opswiseGroups>
            <opswiseGroup>A</opswiseGroup>
            <opswiseGroup>B</opswiseGroup>
        </opswiseGroups>
        <sysId>c4f499ac6a104d3891a5a06398c02fbe</sysId>
        <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
[
    {
        "description": "test 1",
        "exportReleaseLevel": "7.2.0.0",
        "exportTable": "ops_variable",
        "name": "var_1",
        "opswiseGroups": [
            "A",
            "B"
        ],
        "retainSysIds": true,
        "sysId": "c4f499ac6a104d3891a5a06398c02fbe",
        "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">
	<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 Response
{
  "description": "description",
  "exportReleaseLevel": "7.2.0.0",
  "exportTable": "ops_variable",
  "name": "demo_ops_global",
  "opswiseGroups": ["group 1","group 2"],
  "sysId": "237f9f6c43d2617201b2bd04063f917a",
  "retainSysIds": true,
  "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