Showing results for 
Search instead for 
Did you mean: 
Shaun Roberts
Cisco Employee
Cisco Employee

Howdy out there in automation land!!! Hopefully you are de-thawing from winter and are getting into the greatness of Spring! I have been working on developing with a new API and I thought it would make a great "set" of VODs for a pretty detailed Blog post... so here we are!


Let's see... Cloudy movie posters... I know!




As you can see, I do have kids and well, cartoons have been top of our movie list for quite a few years. But, I do like this movie, and the 2nd one even. So what API are we going to work on today??? Well that would be CloudForms/ManageIQ API which can be found here. But this is a 2 part blog automation friends... so the 1st part we will look at the workings of the API and how to put it together in Cisco Process Orchestrator. In the 2nd we will take a closer look at a new(er) feature in CPO, called Variable Types, and how they can be used and make your code more efficient. Fair warning... the VODs will probably run you near 2 hours in total... but hey, that just means you get to hear and see more of me, right??? 


So let's get onto the 1st part. We are going to start an API package, we have to first start with a couple of templated things I like to do with CPO. I do this for all my APIs...


  1. Create a target type that is an extension of the base Web Target and add target properties that make sense for that API
  2. Add Global Variables to represent configurations for the API. I commonly pick things like "Debug Mode" or similar
  3. Create an API Event handler that will alert you of failure and log things (if you use Content Logger)
  4. Create an authentication routine that runs in the background and saves your authentication needs to the new target type


So that is something we should do (or similar) for all API sets. Now we get on to writing the actual API calls... mine tend to be very similar in nature in a step by step process like...


  1. Insert the web call (HTTP Web Request) activity and just hard code it first and test it. Can you get it to work? Great onto step 2
  2. Now you have to figure out the inputs you are going to take and put those in and make sure those have some error handling/manipulation so you can construct the appropriate URL (especially for GETs) and/or the appropriate JSON/XML for POST/PATCH/etc type messages.
  3. After that works, I like to add in a process event to run my handler above.
  4. Lastly I will put the manipulation or setting of the output. Normally I do pass the complete API output message in JSON or XML format (or both) as we do not know what the end user will do with it. In some cases, however, it is smart to output some particular components of the response message if it makes sense and you want to give the developer/end user quick access. IE. If you are creating a case in a case support system, give them the case number you created!


Alrighty so that is the first part... so let us look at the videos for this!!! We will cover parts 1 and 2 of the VOD series here...


Part 1: Webex Recording

Password: JdJKU32J

Summary: This will take you through my initial look into the API as well as the initial layout and querying a VM.


Part 2: Webex Recording

Password: hGQhSW49

Summary: This will take you through writing an API call from scratch and will focus on Controlling a VM.



Alright, so now you've seen almost an hour of great footage... right? Well what is the next thing for us to cover? It is a new(er) feature in CPO called Variable Types. These are custom variables that you can build and shape on your own!! Almost like a class... in fact, sure it is a class. (Well close enough). We have mentioned these before in a previous blog but did not dive in as deep as we will today. Today the goal of the last VOD and display is to create a new variable type for the CloudForms API and use it to pass data between two separate API calls.


So we want to be able to start a VM and know when it's running... but that's two API calls!!! When we start a VM we get something like this in return:

{ "success": true, "message": "VM id:1922 name:'aab_test_vm' scanning", "task_id": 618, "task_href": "http://localhost:3000/api/tasks/618", "href": "http://localhost:3000/api/vms/1922"}


Well we *could* just JSON Path it out or something but where is the fun in that??? In fact, that means I also need to create 5+ different output variables.... yuck! How about instead, one single output variable that is a custom variable we will call a "Control VM Task" type. Or an object. In this case we can do that! We need to go to the variable type area....



So now we want to...

  1. Call the Control VM web call to start the VM
  2. Have that process "make" the Control VM Task object with all it's important data
  3. Then run a while loop that will use the "Query VM" or "Query Task" call to see if the VM is up and running yet or not -- but we want to pass in the Control VM object to this call and process it

This is easy! We just have to add fields/properties to the variable type and create it. It then functions just like a normal variable as far as inputs/outputs/etc. Just an object. In the video you will see me go through this and explain it... what you will not see is it work fully end to end on video. Sadly I ran into a CloudForms bug with authentication... however it is fixed now. I ended up using the Query VM activity (off camera) and make it work. But on camera we tried the Query Tasks API call which gave us an authentication error. Either way -- we do accomplish the true goal, passing and using Variable Types that are custom!


So here we go... this one is 40+ minutes and enjoy!!!


Webex: Link


Summary: Work through an end to end chaining of API calls as well as use custom variable types to do it


Whew... tired yet??? I hope you enjoyed all the above content. You can also find the basic TAP I used for CloudForms API attached here. As always this is in development and is fully opensource. No support, no warranty, no nothing... just fun for you! If you need the Content Logger, you can find it at my tap emporium page.





Standard End-O-Blog Disclaimer:


Thanks as always to all my wonderful readers and those who continue to stick with and use CPO. Big things are on the horizon and I hope that you will continue to use CPO and find great uses for it! If you have a really exciting automation story, please email me it! (see below) I would love to compile some stories and feature customers or individual stories in an upcoming blog!!!


AUTOMATION BLOG DISCLAIMER: As always, this is a blog and my (Shaun Roberts) thoughts on CPO and automation, my thoughts on best practices, and my experiences with the product and customers. The above views are in no way representative of Cisco or any of it's partners, etc. None of these views, etc are supported and this is not a place to find standard product support. If you need standard product support please do so via the current call in numbers on or email


Thanks and Happy Automating!!!


--Shaun Roberts

Additional Attachments:


Getting Started

Find answers to your questions by entering keywords or phrases in the Search bar above. New here? Use these resources to familiarize yourself with the community:

Recognize Your Peers