/
Virtual Resource Web Services

Virtual Resource Web Services

May 24, 2023

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



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

JSON

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

{ "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

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



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

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



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

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

JSON

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

[ { "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

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