Navigation
TAG: REST

Using vCAC 6.X REST APIs – Part 2

Previously on the using vCAC API blog series, we learned how capture and analyze the JSON code going from the VCAC Web UI, to the appliance.  In this post we’ll learn how to modify the request in order to generate a brand new request that can easily requested using vCO REST APIs abstraction.

Lets get to it!

First, make sure you have a vCAC 6 vCO plugin installed, and that you’ve configured it to work with your vCAC Appliance by running the ‘add a vCAC Host’ workflow.

After we have that sorted out, i’ll explain the basics of the vCO workflow required to submit the request:

Rest Request Workflow

 

Breaking it down, what I do in the first scriptable is get the catalog item object by it’s name, in order to get some of its details like id and such, the second scriptable task basically just submits the JSON code we’ve captured, with a few changes in it for the different field modification’s i’d like to perform.

As inputs, I take:
– Catalog Item Name: <Debian / RHEL 6.4 / whatever else I have in my IaaS catalog>
– Memory Size <1024/2048 whatever you want to put in>
– Cpu Size <1/2/3/4 etc.>
– User Name <any user in the Business Group to request on behalf of>

Get Catalog Item

In the general post i’ve made about the vCAC 6 plugin for VCO i’ve mentioned an object worth getting to know – the vCACCAFEEntitiesFinder in the scriptable Javascript code:

[code lang=”js”]
var founditems = vCACCAFEEntitiesFinder.findCatalogItems(vcacHost, itemName);
if (founditems != null)
{
for (var i in founditems)
{
if (founditems[i].name == itemName)
{
var catalogItem = founditems[i];
}
}
}
[/code]

get item

After I’ve found the item and made sure it exists, i’ll submit the JSON request for that item.

Request Item via REST

I’ve actually modified the formatting so it would be simpler to understand the different key:values that are submitted. I’ll point out all of the changes i’ve made to the JSON in the section below it.

[code lang=”js” collapse=”true” title=”Click to see full REST scriptable task code”]
var item = {
"@type":"CatalogItemRequest",
"catalogItemRef":{"id":catalogItem.id},
"organization":{"tenantRef":"vmdemo", "subtenantRef":"ce43f3ed-a3f0-42d0-b8e6-897239f52dbc"},
"requestedFor":UserName,
"state":"SUBMITTED",
"requestNumber":0,
"requestData":
{"entries":[
//{"key":"provider-blueprintId", "value":{"type":"string", "value":"ab5f5a5c-281b-49bf-a549-595789c07957"}},
{"key":"provider-provisioningGroupId", "value":{"type":"string", "value":"ce43f3ed-a3f0-42d0-b8e6-897239f52dbc"}},
{"key":"requestedFor", "value":{"type":"string", "value":UserName}},
{"key":"provider-VirtualMachine.CPU.Count", "value":{"type":"integer", "value":CPUs}},
{"key":"provider-VirtualMachine.Memory.Size", "value":{"type":"integer", "value":MemorySize}},
{"key":"provider-VirtualMachine.Disk0.Size", "value":{"type":"string", "value":"1"}},
{"key":"provider-VirtualMachine.LeaseDays", "value":{"type":"integer", "value":0}},
{"key":"provider-__Notes", "value":{"type":"string", "value":""}},
{"key":"provider-Vrm.DataCenter.Location", "value":{"type":"string", "value":"Lab"}},
{"key":"provider-Cafe.Shim.VirtualMachine.TotalStorageSize", "value":{"type":"decimal", "value":0}},
{"key":"provider-Cafe.Shim.VirtualMachine.Description", "value":{"type":"string", "value":""}},
{"key":"provider-Cafe.Shim.VirtualMachine.NumberOfInstances", "value":{"type":"integer", "value":1}},
{"key":"provider-Cafe.Shim.VirtualMachine.Reason", "value":{"type":"string", "value":""}},
{"key":"provider-Cafe.Shim.VirtualMachine.AssignToUser", "value":{"type":"string", "value":UserName}},
{"key":"provider-Cafe.Shim.VirtualMachine.MinCost", "value":{"type":"string", "value":"0"}},
{"key":"provider-Cafe.Shim.VirtualMachine.MaxCost", "value":{"type":"string", "value":"0"}},
{"key":"description", "value":{"type":"string", "value":""}},
{"key":"reasons", "value":{"type":"string", "value":""}
}]}
}

var catalogRest = vcacHost.createRestClient(vCACCAFEServicesEnum.CATALOG_SERVICE);
var response = catalogRest.post("consumer/requests",item);
System.log(response);
[/code]

~UPDATE~
For this to work with vCAC 6.1, you’ll need to serialize the request prior to submitting it, with the following code:

[code]item = System.getModule("org.dojotoolkit.dojo.json").serialize(item);[/code]

So be sure to add this line in your scriptable with vCAC 6.1
~UPDATE~

Screen Shot 2014-06-10 at 12.14.30 PM

Running through the code, you can notice some replacements i’ve done to the JSON text strings with my own variables, like:

[code lang=”js”]
"@type":"CatalogItemRequest",
"catalogItemRef":{"id":catalogItem.id},
[/code]

I’ve used the catalog item object to get it’s id so the proper item would be requested.
Also I’ve modified the memory and cpu parameters to fit the users input values:

[code lang=”js”]
{"key":"requestedFor", "value":{"type":"string", "value":UserName}},
{"key":"provider-VirtualMachine.CPU.Count", "value":{"type":"integer", "value":CPUs}},
{"key":"provider-VirtualMachine.Memory.Size", "value":{"type":"integer", "value":MemorySize}},
[/code]

Last part of the scriptable task code actually creates an internal , pre authenticated REST Client in vCO , to actually submit the request itself:

[code lang=”js”]
var catalogRest = vcacHost.createRestClient(vCACCAFEServicesEnum.CATALOG_SERVICE);
var response = catalogRest.post("consumer/requests",item);
System.log(response);
[/code]

the response variable will hold the servers response to our request, which will usually consist of a request item we can follow on to get progress updates with the request’s ‘Phase’ field.

To summarize the workflow, you can opt to change any one of the JSON parameters to expose less or more properties for user input, it all depends what is your use case and who are you giving this capability to. Of course your organization could have other custom properties needed to provision a vm, these appear as just another key:value in the JSON request.
Keep in mind that in more complicated environments you will probably have to add error checks, and might need to change the ‘subtenantidref ‘ value which is the value for the Business Group that the item is being provisioned by.

Day 2 operations via REST API

To allow for a day 2 action of a catalog VM with vCAC , we will repeat the process depicted in this two part series, grab the JSON code for a ‘destroy’ operation for example, and we will get the same kind of workflow. This time we will use a different vCACCAFEEnititiesFinder function called ‘

[code lang=”js”]
var founditems = vCACCAFEEntitiesFinder.findCatalogResources(vcacHost, resourceName);
[/code]

After that, we’ll get the resource object id, and post a ‘destroy action’ JSON request, for that specific VM. The code below is for posting the ‘destroy action’ after we’ve found the catalog resource item (our provisioned VM)

[code lang=”js”]
var resourceAction = {
"@type":"ResourceActionRequest",
"resourceRef":{"id":resourceItem.id},
"resourceActionRef":{"id":"a7eb7daf-de73-4cf9-b2c7-0c8aeded3b01"},
"organization":{"tenantRef":"vmdemo", "tenantLabel":"vmdemo.local", "subtenantRef":"ce43f3ed-a3f0-42d0-b8e6-897239f52dbc", "subtenantLabel":"Lab-BG"},
"state":"SUBMITTED", "requestNumber":0,
"requestData":{"entries":[]}
}
var catalogRest = vcacHost.createRestClient(vCACCAFEServicesEnum.CATALOG_SERVICE);
var response = catalogRest.post("consumer/requests",resourceAction);
System.log(response);
[/code]

Rest operations

Calling a vCO workflow with REST API

The main thing after we built this workflow, is to wrap it all up by simply letting users access this vCO workflow with vCO’s REST API! Now, users or any 3rd party system , can simply call vCO’s REST interface to run this specific workflow, and get a VM of choice with a quick API call.
You can read about calling vCO via REST in this article by our awesome vCOTeam @ VMware.

Attached below is a very simple example of calling a vCO Worflow with python code (remember to change to py instead of txt)
and REST APIs
If you have any questions, feel free to drop them in the comment section!

Using vCAC 6.0 REST APIs – Part 1

vCloud Automation Center 6.x has a very extensive API that can allow you to automate everything done with your cloud. This ranges from auto creating new tenants, to auto generating catalog items & services. One could even ask to request a catalog item on behalf of another user defined in vCloud Automation Center. The thing is, is at the moment these API’s are considered in a beta state this is due to the fact that they are still under development in 6.0.x and that not all of the functionalities (as you’ll see soon) are still available.

Recently, VMware has released a vCO Plugin for vCAC, which consists of two parts:
– The IaaS ODATA API workflow interface
– A vCAC Appliance API workflow interface.

Interacting with vCAC API

For the purpose of this post, we will learn how to utilize the vCAC-VA APIs, which are the MAIN set of API’s exposed from vCAC to users. Thing is, in order to authenticate we will have to use the vCO Server + vCAC 6.x vCO Plugin , since the natural authentication mechanism isn’t yet exposed (remember? BETA APIs)

vco-vcac-rest

 

In this first of two-part series, i’ll demonstrate how to capture, and make sense of the JSON request generated by the vCAC UI. Next post, will discuss on how to utilize vCO and this JSON code, to generate new automated requests via REST calls.

Capturing the API Call


The first step here is to understand the JSON construct vCAC 6.0 requests (I’m assuming API usage of vCAC would be for using it to consume services like IaaS / ASD)

We’ll begin by downloading Firefox, and FireBug plugin. What firebug does, is to get in between the actual UI click and the HTTP REST call that the browser make. We can leverage this to easily poke around, and re-create some of the REST API calls! So lets dive deeper in the rabbit hole. We will open up our vCAC catalog , and request an item:
Requesting Deb6
We’ll need to enable firebug, and then click the submit button:
FIREBUGON
Once we do that, we’ll see the HTTP responses , GET and POST operations.

HTTP REST Requests

If we click the plus sign and open it, we will get the JSON code posted:

PostMakeRequest

Analyzing the Request’s JSON Code

if we grab the text and format it, we can make some sense out of it. I’ll put the formatted code here, in case you want to take a look, and analyze what we can do further down. An explanation on how to utilize this using vCO will follow.

[code lang=”js” collapse=”true” title=”Click to see full Item Request JSON Code (warning: it׳s a LONG one)”]
"@type": "CatalogItemRequest",
"catalogItemRef": {
"id": "e783893b-3068-498d-b5cc-3be78cf4742d",
"label": "Debian 6"
},
"organization": {
"tenantRef": "vmdemo",
"tenantLabel": "vmdemo.local",
"subtenantRef": "a88b5eb5-210f-4f25-b074-95475f599018",
"subtenantLabel": "Lab-BG"
},
"quote": {
"leasePeriod": null,
"leaseRate": {
"type": "moneyTimeRate",
"cost": {
"type": "money",
"currencyCode": null,
"amount": 177
},
"basis": {
"type": "timeSpan",
"unit": "DAYS",
"amount": 1
}
},
"totalLeaseCost": null
},
"requestedFor": "kushmaro@vmdemo.local",
"requestedBy": "kushmaro@vmdemo.local",
"requestorEntitlementId": "e2117850-88ed-4564-a8e8-6fff77e8fede",
"state": "SUBMITTED",
"requestData": {"entries": [
{
"key": "provider-Cafe.Shim.VirtualMachine.Description",
"value": {
"type": "string",
"value": ""
}
},
{
"key": "provider-blueprintId",
"value": {
"type": "string",
"value": "e0f0b0d0-681d-45ee-9dfe-5b3466b161ef"
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.Reason",
"value": {
"type": "string",
"value": ""
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.MaxCost",
"value": {
"type": "string",
"value": "177.0000"
}
},
{
"key": "provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.NumberOfInstances",
"value": {
"type": "integer",
"value": 1
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.TotalStorageSize",
"value": {
"type": "decimal",
"value": 0
}
},
{
"key": "provider-__Notes",
"value": {
"type": "string",
"value": ""
}
},
{
"key": "provider-provisioningGroupId",
"value": {
"type": "string",
"value": "a88b5eb5-210f-4f25-b074-95475f599018"
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.MinCost",
"value": {
"type": "string",
"value": "177.0000"
}
},
{
"key": "provider-VirtualMachine.Disk0.Size",
"value": {
"type": "string",
"value": "16"
}
},
{
"key": "provider-Cafe.Shim.VirtualMachine.AssignToUser",
"value": {
"type": "string",
"value": "kushmaro@vmdemo.local"
}
},
{
"key": "provider-VirtualMachine.LeaseDays",
"value": {
"type": "integer",
"value": 0
}
},
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
}
]},
"preApprovalId": null,
"postApprovalId": null,
"retriesRemaining": 3
}
[/code]

I’ll review some of the JSON Code above.
If we’ll look at the two first lines, we are able to see what type this JSON request is.

[code lang=”js”]
"@type": "CatalogItemRequest",
  "catalogItemRef":   {
    "id": "e783893b-3068-498d-b5cc-3be78cf4742d",
    "label": "Debian 6"
  },
 [/code]

As mentioned, this specific request is a catalog item request, referencing the specific id and name of the catalog item requested.
By changing these two parameters , and assuming we have multiple catalog items that look the same (in terms of request fields / input params) , we are able to easily shift our request from one item to the other. Like requesting a Red Hat VM or a Windows VM , all according to specific needs.

Next part of the code, depicts which BG & Tenant the request was made for:

[code lang=”js”]
"organization": {
"tenantRef": "vmdemo",
"tenantLabel": "vmdemo.local",
"subtenantRef": "a88b5eb5-210f-4f25-b074-95475f599018",
"subtenantLabel": "Lab-BG"
},
[/code]

The subtenantRef value is actually the Business group UUID within vCAC , and the tenantRef is the UUID kept for the tenant. vCAC keeps tenants by name, which represent a single UUID for the tenant.
Next comes an interesting part, specifying who is this requested for, and by whom:

[code lang=”js”]
"requestedFor": "kushmaro@vmdemo.local",
"requestedBy": "kushmaro@vmdemo.local",
"requestorEntitlementId": "e2117850-88ed-4564-a8e8-6fff77e8fede",
"state": "SUBMITTED",
[/code]

another part of the code determines who is the assigned user for the VM, its owner:

[code lang=”js”]
"key": "provider-Cafe.Shim.VirtualMachine.AssignToUser",
"value": {
"type": "string",
"value": "kushmaro@vmdemo.local"
[/code]

The ‘RequestedFor’ and ‘AssignToUser’ fields, indicates the user that this request is done on behalf of. This opens up some very nice possibilities, in automating requests for other users.
Lets say you want to perform a mass request automatically for new groups or users who joined the organization, or maybe a QA environment for each of your QE team’s members (hint: vCAC Devops Post), so that when they come to work, they have a new build ready for testing.
If you want the API Requested VM to be requested and assigned for a different user, you’ll have to change the ‘AssignToUser’ and ‘Requested For’ parameters for a user of your choice (having the proper entitlement).

Another interesting thing to notice here is the request state. A new request is tagged as submitted, while a request that’s been done is marked as completed.
This allows for tracking of the request, also with the help of a ‘phase’ field, that is non-existing at time of submitting the request.

Lastly comes the request details.
This part of the request details all of the item’s specific details, whether its customer properties, CPUs, Memory etc. For ASD requests , this would hold the ASD form values filled in by the user.

By modifying parameters below, we can easily set the CPU / Memory numbers for the specific request.

[code lang=”js”]
{
"key": "provider-VirtualMachine.Memory.Size",
"value": {
"type": "integer",
"value": 1024
}
{
"key": "provider-VirtualMachine.CPU.Count",
"value": {
"type": "integer",
"value": 1
}
[/code]

This concludes the first part of the vCAC6 REST API series, in the next part (coming soon!) i’ll demonstrate how to use vCO to regenerate a new API request, and help you automate vCAC for different purposes.
As always – Leave your comments below!

There are no more results.