Virtual Resource Web Services

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.

JSON

JSON

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

XML

XML

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>

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. info 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. info In XML web services, version is specified as an attribute in the <virtualResource> element.		Y

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?resourcename=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
resourcename	Name of the resource.	Wildcards are supported.	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

List Virtual Resources: XML and JSON Response Examples

JSON

JSON

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

XML

XML

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>

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

JSON

JSON

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

XML

XML

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>

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

JSON

Example Request

JSON

JSON

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

Example Response

JSON

JSON

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

XML

Example Request

XML

XML

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

Example Response

XML

XML

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

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 (unless sysID is specified)
limit	Resource Limit	Maximum number of units available for this resource.		Y
sysID	N/A	System ID field in the database for a record.		Y (unless name is specified)