Overview

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

Create a Virtual Resource
Delete a Virtual Resource
List Virtual Resources
List Virtual Resources - Advanced
Modify a Virtual Resource
Read a Virtual Resource
Set Limit on a Virtual Resource

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

Create a Virtual Resource

	Description
URI	http://host_name/uc/resources/virtual
HTTP Method	POST
Description	Creates a Virtual Resource.
Example URI	http://localhost:8080/uc/resources/virtual
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example	See Virtual Resource: XML and JSON Examples.
Properties	See Virtual Resource: Properties.
Example Response	Status 200 /OK Successfully created the Business Service with sysId {sysId}. Status 400 /Bad Request Create virtual resource failed. Resource Name must be defined.

Virtual Resource: XML and JSON Examples

The excludeRelated and retainsSysIds properties are specified as attributes in the XML.

XML

JSON

XML

<virtualResource exportReleaseLevel="7.2.0.0" exportTable="ops_virtual_resource" retainSysIds="true">
  <limit>1</limit>
  <name>test</name>
  <opswiseGroups>
     <opswiseGroup>1</opswiseGroup>
  </opswiseGroups>
  <summary>Resource with limit of only 1.</summary>
  <sysId>416d78bac0a801c901de14704e00fa75</sysId>
  <type>Renewable</type>
</virtualResource>

JSON

{
  "exportReleaseLevel": "7.2.0.0",
  "exportTable": "ops_virtual_resource",
  "limit": 5,
  "name": "test",
  "opswiseGroups": [
    "1"
  ],
  "retainSysIds": true,
  "summary": "Resource with limit of only 1.",
  "sysId": "416d78bac0a801c901de14704e00fa75",
  "type": "Renewable"
 }

Virtual Resource Properties

Property	UI Field Name	Description	Specifications	Required
`exportReleaseLevel`	n/a	Universal Controller release that the record was exported from.	read only	N
`exportTable`	n/a	Record table information.	read only	N
`limit`	Resource Limit	Number of resources available for the specific resource type.	Integer; Default is 10.	N
`name`	Name	Name used within the Controller to identify this Virtual Resource.	Contains a maximum of 40 alphanumerics.	Y
`opswiseGroups`	Member of Business Services	Business Services that this record belongs to. XML <opswiseGroups> <opswiseGroup>group1</opswiseGroup> <opswiseGroup>group2</opswiseGroup> </opswiseGroups> JSON "opswiseGroups": ["group1","group2"]		N
`retainSysIds`	n/a	For Create web services; specification for whether or not the web service should persist the sysId property. If `retainSysIds` is true and `sysId` is included in the request/response, `sysId` will be persisted to the database. If `retainSysIds` is 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 <virtualResource> element.	Valid values: true/false (default is true).	N
`summary`	Description	User-defined; description of this record.		N
`sysId`	N/A	System ID field in the database for a record.	Persisted only if retainSysIds is set to true.	N
`type`	Resource Type	Type of Virtual Resource.	Valid values: As String = Renewable, As Value = 1 As String = Boundary, As Value = 2 As String = Depletable, As Value = 3 Default is Renewable (1).	N
`version`	n/a	For Read and List web services; specification of the version being read or listed. Note In XML web services, `version` is specified as an attribute in the <virtualResource> element.		Yes

Delete a Virtual Resource

	Description
URI	http://host_name/uc/resources/virtual
HTTP Method	DELETE
Description	Deletes a Virtual Resource.
URI Parameters	See Delete a Virtual Resource: URI Parameters.
Example URI	http://localhost:8080/uc/resources/virtual?resourceid=77171434c0a801c9016d5b2b5d17ddee
Example Response	Status 200 /OK Virtual Resource deleted successfully. Status 400 /Bad Request Mutual exclusion violation. Cannot specify `resourcename` and `resourceid` at the same time. Status 404 /Not Found A virtual resource with {name/id} "test" does not exist.

Delete a Virtual Resource: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`resourceid`	ID used within the Controller to identify this Virtual Resource.	String; URI parameter.	Y (unless `resourcename` is specified)	`resourcename`
`resourcename`	Name used within the Controller to identify this Virtual Resource.	String; URI parameter.	Y (unless `resourceid` is specified)	`resourceid`

List Virtual Resources

	Description
URI	http://host_name/uc/resources/virtual/list
HTTP Method	GET
Description	Retrieves information on all Virtual Resources.
URI Parameters	See List Virtual Resources: URI Parameters.
Example URI	http://localhost:8080/uc/resources/virtual/list?name=test*&type=renewable
Authentication	HTTP Basic
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Response Example	See List Virtual Resources: XML and JSON Response Examples.
Response Properties	See List Virtual Resources: Response Properties.

List Virtual Resources: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`name`	Name of this Virtual Resource.	String; URI wild card parameter (that is, `test*`).	N	`resourcename`
`resourcename`	Name of the resource.	Wildcards are supported.	N	`name`
`type`	Type of this Virtual Resource.	Valid Values: As String = Renewable, As Value = 1 As String = Boundary, As Value = 2 As String = Depletable, As Value = 3 If `type` is not specified, it defaults to all types.	N

List Virtual Resources: XML and JSON Response Examples

XML

JSON

XML

<virtual-resources>
   <virtual-resource>
      <limit>8</limit>
      <name>test1</name>
      <sysId>416d78bac0a801c901de14704e00fa75</sysId>
      <type>Renewable</type>
      <used>1</used>
      <used-by-tasks>
         <task>
             <amount>1</amount>
             <taskInstanceName>uc - Sleep 60</taskInstanceName>
         </task>
      </used-by-tasks>
      <version>1</version>
   </virtual-resource>
   <virtual-resource>
      <limit>10</limit>
      <name>test2</name>
      <sysId>416d78bac0a801c901de14704e00fa76</sysId>
      <type>Renewable</type>
      <used>1</used>
      <used-by-tasks>
         <task>
             <amount>1</amount>
             <taskInstanceName>uc - Sleep 60</taskInstanceName>
         </task>
      </used-by-tasks>
      <version>1</version>
   </virtual-resource>
</virtual-resources>

JSON

[ {
  "limit": 8,
  "name": "test",
  "sysId": "416d78bac0a801c901de14704e00fa75",
  "type": "Renewable",
  "used": 1,
  "usedByTasks": [ {
    "amount": 1,
    "taskInstanceName": "uc - Sleep 60"
  } ],
  "version": 1
  },
  {
  "limit": 10,
  "name": "test2",
  "sysId": "416d78bac0a801c901de14704e00fa76",
  "type": "Renewable",
  "used": 1,
  "usedByTasks": [ {
    "amount": 1,
    "taskInstanceName": "uc - Sleep 60"
  } ],
  "version": 1
  }
]

List Virtual Resources: Response Properties

Property	UI Field Name	Description
`limit`	Resource Limit	Number of resources available for the specific resource type.
`name`	Name	Name used within the Controller to identify this Virtual Resource.
`sysId`	n/a	System ID field in the database for a record.
`type`	Resource Type	Type of Virtual Resource.
`used`	Resource Used	System-supplied if `type` is Renewable; Number of units currently in use at the time the web service is executed.
`used-by-tasks`	Currently in Use	List of task instances that have acquired this virtual resource, and the number of units acquired, at the time the web service was executed. Note `used-by-tasks` is defined as "usedByTasks" in JSON.
`version`	Version	System-supplied; version number of the virtual resource.

List Virtual Resources - Advanced

	Description
URI	http://host_name/uc/resources/virtual/listadv
HTTP Method	GET
Description	Retrieves information on all Virtual Resources.
URI Parameters	See List Virtual Resources Details: URI Parameters.
Example URI	http://localhost:8080/uc/resources/virtual/listadv?resourcename=test*&type=renewable&businessServices=A
Authentication	HTTP Basic
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Response Example	See List Virtual Resources - Advanced: XML and JSON Response Examples.

List Virtual Resources - Advanced: URI Parameters

Parameter	Description	Specifications	Required
`resourcename`	Name of this Virtual Resource.	String; URI wild card parameter (that is, `test*`).	N
`type`	Type of this Virtual Resource.	Valid Values: As String = Renewable, As Value = 1 As String = Boundary, As Value = 2 As String = Depletable, As Value = 3 If `type` is not specified, it defaults to all types.	N
`businessServices`	Business Services that this Virtual Resource belongs to.	String value of comma-separated Business Services.	N

List Virtual Resources - Advanced: XML and JSON Response Examples

XML

JSON

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<virtualResources>
    <virtualResource exportReleaseLevel="7.2.0.0" exportTable="ops_virtual_resource" retainSysIds="true" version="3">
        <limit>1</limit>
        <name>VR-1</name>
        <opswiseGroups>
            <opswiseGroup>A</opswiseGroup>
        </opswiseGroups>
        <summary>VR test 1</summary>
        <sysId>10e1664d8fe44a4482c6b6d6a64ecc05</sysId>
        <type>Renewable</type>
    </virtualResource>
    <virtualResource retainSysIds="true" version="2">
        <limit>1</limit>
        <name>VR-2</name>
        <opswiseGroups>
            <opswiseGroup>B</opswiseGroup>
        </opswiseGroups>
        <summary>VR test 2</summary>
        <sysId>459020efeff3476682be1a6c8df8f799</sysId>
        <type>Boundary</type>
    </virtualResource>
    <virtualResource exportReleaseLevel="7.2.0.0" exportTable="ops_virtual_resource" retainSysIds="true" version="1">
        <limit>1</limit>
        <name>VR-3</name>
        <opswiseGroups>
            <opswiseGroup>C</opswiseGroup>
        </opswiseGroups>
        <summary>test 3</summary>
        <sysId>f4bfd4882af24948b6f7abd7baad91b1</sysId>
        <type>Depletable</type>
    </virtualResource>
</virtualResources>

JSON

[
    {
        "exportReleaseLevel": "7.2.0.0",
        "exportTable": "ops_virtual_resource",
        "limit": 1,
        "name": "VR-1",
        "opswiseGroups": [
            "A"
        ],
        "retainSysIds": true,
        "summary": "VR test 1",
        "sysId": "10e1664d8fe44a4482c6b6d6a64ecc05",
        "type": "Renewable",
        "version": 3
    },
    {
        "exportReleaseLevel": "7.2.0.0",
        "exportTable": "ops_virtual_resource",
        "limit": 1,
        "name": "VR-2",
        "opswiseGroups": [
            "B"
        ],
        "retainSysIds": true,
        "summary": "VR test 2",
        "sysId": "459020efeff3476682be1a6c8df8f799",
        "type": "Boundary",
        "version": 2
    },
    {
        "exportReleaseLevel": "7.2.0.0",
        "exportTable": "ops_virtual_resource",
        "limit": 1,
        "name": "VR-3",
        "opswiseGroups": [
            "C"
        ],
        "retainSysIds": true,
        "summary": "test 3",
        "sysId": "f4bfd4882af24948b6f7abd7baad91b1",
        "type": "Depletable",
        "version": 1
    }
]

Modify a Virtual Resource

	Description
URI	http://host_name/uc/resources/virtual
HTTP Method	PUT
Description	Modifies the Virtual Resource specified by the `sysId`.
Example URI	http://localhost:8080/uc/resources/virtual
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example	See Virtual Resource: XML and JSON Examples.
Properties	See Virtual Resource: Properties.
Example Response	Status 200 /OK Successfully updated the virtual resource with sysId <sysId> to version <version>.

Read a Virtual Resource

	Description
URI	http://host_name/uc/resources/virtual
HTTP Method	GET
Description	Retrieves information on a specified Virtual Resource.
Example URI	http://localhost:8080/uc/resources/virtual?resourcename=test
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example	See Virtual Resource: XML and JSON Examples.
Properties	See Virtual Resource: Properties.

Read a Virtual Resource: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`resourceid`	ID used within the Controller to identify this Virtual Resource.	String; URI parameter.	Y (unless `resourcename` is specified)	`resourcename`
`resourcename`	Name used within the Controller to identify this Virtual Resource.	String; URI parameter.	Y (unless `resourceid` is specified)	`resourceid`

Set Limit on a Virtual Resource

	Description
URI	http://host_name/uc/resources/virtual/ops-update-resource-limit
HTTP Method	POST
Description	Updates resource limit for virtual resources.
Example URI	http://localhost:8080/uc/resources/virtual/ops-update-resource-limit
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Set Limit on a Virtual Resource: XML and JSON Examples.
Request Properties	See Set Limit on a Virtual Resource: Request Properties.
Example Response	See Set Limit on a Virtual Resource: XML and JSON Examples.

Set Limit on a Virtual Resource: XML and JSON Examples

Example

XML

JSON

Example Request

XML

<virtual-resource>
      <name>uc - Solo</name>
      <limit>1</limit>
</virtual-resource>

JSON

{
  "name": "uc - Solo",
  "limit": 1
}

Example Response

XML

<command-response>
    <type>update_resource_limit</type>
    <success>true</success>
    <info>Successfully updated the virtual resource.</info>
    <errors />
</command-response>

JSON

{
    "type": "update_resource_limit",
    "success": true,
    "info": "Successfully updated virtual resource "uc - Solo" with limit 1. ",
    "errors": ""
}

Set Limit on a Virtual Resource: Request Properties

Property	UI Field Name	Description	Specifications	Required
`name`	Resource Name	Name used within the Controller to identify this resource.	Maximum 40 alphanumerics.	Y
`limit`	Resource Limit	Maximum number of units available for this resource.		Y

Universal Controller 7.4.x

Virtual Resource Web Services

Overview

Create a Virtual Resource

Virtual Resource: XML and JSON Examples

Virtual Resource Properties

Delete a Virtual Resource

Delete a Virtual Resource: URI Parameters

List Virtual Resources

List Virtual Resources: URI Parameters

List Virtual Resources: XML and JSON Response Examples

List Virtual Resources: Response Properties

List Virtual Resources - Advanced

List Virtual Resources - Advanced: URI Parameters

List Virtual Resources - Advanced: XML and JSON Response Examples

Modify a Virtual Resource

Read a Virtual Resource

Read a Virtual Resource: URI Parameters

Set Limit on a Virtual Resource

Set Limit on a Virtual Resource: XML and JSON Examples

Set Limit on a Virtual Resource: Request Properties

Related content