Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

Anchor
Create a Global Variable
Create a Global Variable

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 63553556, below.

Example Response

  • Status 200 /OK
    Successfully created the variable with sysId {sysId} to version {version}.

Anchor
Create a Global Variable Example Request
Create a Global Variable Example Request

Create a Global Variable: Example Request

XML Request

JSON Request


Expand
titleXML 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>



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



Anchor
Global Variable Properties
Global Variable Properties

Global Variable Properties

Property

UI Field Name

Description

Specifications

Required

Anchor
description - GV
description - GV
description

Description

User-defined; description of this record.


N

Anchor
name - GV
name - GV
name

Name

Name used within the Controller to identify this Global Variable.

Contains a maximum of 40 alphanumerics.

Y

Anchor
opswiseGroups - GV
opswiseGroups - GV
opswiseGroups

Member of Business Services

Business Services that this record belongs to.
 
XML


Panel


Html bobswift
<pre>
&lt;opswiseGroups&gt;
      &lt;opswiseGroup&gt;test&lt;/opswiseGroup&gt;
&lt;/opswiseGroups&gt;
</pre>



 
JSON


Panel


Html bobswift
<pre>
"opswiseGroups": ["test"]
</pre>




N

Anchor
retainSysIds - GV
retainSysIds - GV
retainSysIds

n/a

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


Html bobswift
<ul>
<li> If <b>retainSysIds</b>="true" and <code>sysId</code> is included in the request/response, <code>sysId</code> will be persisted to the database.
<li> If <b>retainSysIds</b>="false" and  <code>sysId</code> is included in the request/response, <code>sysId</code> will be ignored; it will be autogenerated by the Controller. 
</ul>



Note
titleNote

In XML, retainSysIds is specified as an attribute in the <variable> element.


Valid values: true/false (default is true).

N

Anchor
sysId - GV
sysId - GV
sysId

n/a

System ID field in the database for a record.

Persisted only if retainSysIds is set to true.

N

Anchor
vale - GV
vale - GV
value

Value

Value of this variable.

Maximum = 25000 characters.

N

Anchor
Delete Global Variable
Delete Global Variable

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.

Anchor
Delete a Global Variable URI Parameters
Delete a Global Variable URI Parameters

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

Anchor
List Variables
List Variables

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.

Anchor
List Variables XML and JSON Examples
List Variables XML and JSON Examples

List Variables: XML and JSON Examples

Examples

XML

JSON

Example Request


Expand
titleXML
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>



Expand
titleJSON
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


Expand
titleXML
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>



Expand
titleJSON
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" } ]


Anchor
List Variables Request Properties
List Variables Request Properties

List Variables: Request Properties

Property

UI Field Name

Description

Specifications

Required

Anchor
scope - LReq
scope - LReq
scope

n/a

Type of variable to be returned in the Response.

Valid values (case insensitive):

  • global
  • local
  • task
  • trigger

Default is global.

N

Anchor
taskName - LReq
taskName - LReq
taskName

n/a

If scope is task; Name of task.


Y

Anchor
triggerName - LReq
triggerName - LReq
triggerName

n/a

If scope is trigger; Name of the trigger.


Y

Anchor
variableName - LReq
variableName - LReq
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

Anchor
List Variables Response Properties
List Variables Response Properties

List Variables: Response Properties

Property

UI Field Name

Description

Anchor
description - LRes
description - LRes
description

Description

Description of the variable.

Anchor
name - LRes
name - LRes
name

Name

Name of the variable.

Anchor
sysId - LRes
sysId - LRes
sysId

n/a

sys_id used within the Controller to identify this variable.

Anchor
taskId - LRes
taskId - LRes
taskId

n/a

ID of the task if the search was for a task-specific variable (scope is task in the Request).

Anchor
taskName - LRes
taskName - LRes
taskName

n/a

Name of the task if the search was for a task-specific variable (scope is task in the Request).

Anchor
triggerId - LRes
triggerId - LRes
triggerId

n/a

ID of the trigger if the search was for a trigger-specific variable (scope is trigger in the Request).

Anchor
triggerName - LRes
triggerName - LRes
triggerName

n/a

Name of the trigger if the search was for a trigger-specific variable (scope is trigger in the Request).

Anchor
type - LRes
type - LRes
type

n/a

Type of variable.

Anchor
value - LRes
value - LRes
value

Value

Value of the variable.

Anchor
version - LRes
version - LRes
version

Version

Version of the variable.

Anchor
options - LRes
options - LRes
options

Value Options

Not for Global Variables.

Code Block
languagexml
linenumberstrue
            <options>
                <option>option1</option>
                <option>option2</option>
            </options>


Note
titleNote

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.


Anchor
allowEmptyOption - LRes
allowEmptyOption - LRes
allowEmptyOption

Allow Empty Option

Not for Global Variables.

<allowEmptyOption>true/false</allowEmptyOption>

Anchor
allowUnlistedOption - LRes
allowUnlistedOption - LRes
allowUnlistedOption

Allow Unlisted Option

Not for Global Variables.

<allowUnlistedOption>true/false</allowUnlistedOption>


Anchor
List Variables - Advanced
List Variables - Advanced

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.

...

Anchor
List Variables - Advanced URI Parameters
List Variables - Advanced URI Parameters

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

Anchor
List Variables - Advanced Example Response
List Variables - Advanced Example Response

List Variables - Advanced: Example Response

XML Response

JSON Response


Expand
titleXML 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>



Expand
titleJSON 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" } ]


Anchor
Modify Global Variable
Modify Global Variable

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 63553556.

Example Response

  • Status 200 /OK
    Successfully updated the variable with sysId <sysId> to version <version>.

Anchor
Modify a Global Variable Example Request
Modify a Global Variable Example Request

Modify a Global Variable: Example Request

XML Request

JSON Request


Expand
titleXML 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>



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


Anchor
Read a Global Variable
Read a Global Variable

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 63553556.

Anchor
Read a Global Variable URI Parameters
Read a Global Variable URI Parameters

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

Anchor
Read a Global Variable Example Response
Read a Global Variable Example Response

Read a Global Variable: Example Response

XML Response

JSON Response


Expand
titleXML 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>



Expand
titleJSON 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 }


Anchor
Set Variable
Set Variable

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 63553556.

Anchor
Set Variable Request Examples
Set Variable Request Examples

Set Variable: Request Examples

XML Request

JSON Request


Expand
titleXML
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> 



Expand
titleJSON
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"
  }
}


Anchor
Set Variable Response Examples
Set Variable Response Examples

Set Variable: Response Examples

XML Response

JSON Response


Expand
titleXML
<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>



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


Anchor
Set Variable Properties
Set Variable Properties

Set Variable Properties

Property

UI Field Name

Description

Specifications

Required

Anchor
create - SV
create - SV
create

n/a

Specification for whether or not to create a variable.

Boolean; Valid values: true/false.

N

Anchor
description - SV
description - SV
description

Description

Description of the variable.


N

Anchor
exportReleaseLevel - SV
exportReleaseLevel - SV
exportReleaseLevel

n/a

Universal Controller release that the record was exported from.

read onlyN

Anchor
exportTable - SV
exportTable - SV
exportTable

n/aRecord table information.read onlyN

Anchor
name - SV
name - SV
name

Name

Name of the variable.


Y

Anchor
scope - SV
scope - SV
scope

n/a

Type of variable to be returned in the XML Response.

Valid values: global, task, trigger (case insensitive). Default is global.

N

Anchor
task - SV
task - SV
task

n/a

If scope is task; Name of the task.


Y

Anchor
trigger - SV
trigger - SV
trigger

n/a

If scope is trigger; Name of the trigger.


Y

Anchor
value - SV
value - SV
value

Value

Value of the variable.

Maximum = 25000 characters.

Y

...