Virtual Resource Web Services

Overview

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

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

Create a Virtual Resource


Description

URI

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 onlyN

exportTable

n/aRecord table information.read onlyN

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



 
JSON



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
resourcenameName of the resource.

Wildcards are supported.

Nname

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