VMware Orchestrator Beginners guide — Part 4: Workflow Components & Debugging
In the last article you’ve learnt how to create a simple workflow that connects to a REST endpoint and create a JIRA issue. Now let’s explore how can we use Orchestrator to take decisions.
Let’s create a workflow called Add Disk, this workflow will (actually, not for real, but you can surely code if you want to) be responsible to attach a data disk to a virtual machine.
The workflow palette have the following components:
I created a mock action called locateVirtualMachine to return the provider for a certain virtual machine. In a real scenario you will probably call your vCenter, Azure/AWS API.
Now I added the action in my workflow, just like the last tutorial, you just type the action name and drag into the canvas. IN and OUT tabs were respectively mapped to my input variable in_hostname and a new attribute att_provider.
Decision
A decision is a simple decision taker, you will basically pick one variable and check if it's equals/contains/match/is defined. As we can see here after add it on our workflow
Although it does have limited functionality such as no code and only one parameter per decision, it does help to prevent writing JavaScript code unless it's really necessary. If the condition is satisfied workflow will follow the green line, otherwise, it will follow the red line. Now, If you need something more customised, then you need a Custom decision.
Custom Decision
A custom decision is basically a Decision but allow us to code it in JavaScript and choose as many input variables as we want. You may click on Bind to workflow parameter/attribute to add all the variables you want to use, just like a Scriptable Task. To satisfy the condition, return true, otherwise, return false. In the following example, I want to make sure the characters VM are in the start of the string.
Switch
Just like most languages' switch() function, it will move the Workflow according to a variable condition. Also, like the regular decision activity, it is also limited. In this example we will move the workflow according to the provider.
As you can see, the "then go" points to an ItemX:, thats because none of our items got names and therefore, we are just ending the workflow in this example. We will fix this by creating scriptable tasks later.
User Interaction
This component allow an end user to interact during a workflow execution. I love to use this particular component to prevent workflow failures and make the end-to-end process more beautiful.
You may have noticed that my previous Action will return a provider accordingly to a Virtual Machine name. However, it will return "unknown" if you type anything different than the 3 values that we treated.
So, we want to attach a Disk but for some reason either the virtual machine does not exists or I had some trouble by while querying the API. What are we supposed to do?
Of course it will depend on your requirements, but let's say we want to tell the user that we didn't found the provider and we will also want ask him what he wants to do.
I've dragged it to the first case of my switch and my workflow now looks like this:
Now click in the User Interaction component and move to the attribute tab:
I think its pretty self explanatory. Those attributes will define who can answer the user interaction. It may be a group, a list of users or a list of groups. Also, you may set a timeout in case nobody answers and the workflow will be aborted. You need to fill at least one of the three first fields so Orchestrator will know what to do, in this example I added two users to the assignees and all the other values are set too NULL
Move to the external inputs tab, you will see something similar to IN/OUT parameters. This tab defines which variables your end user will fill/interact.
I have decided that in case an unknown provider is detected, the user will be prompted about what he wants to do: provide a new name or end the workflow. To accomplish this, I will create a two new attributes named att_abort as boolean and att_hostname as string then add both variables in this tab. Things should just looks like this:
Let's move to the Presentation tab. This is what is going to be displayed to the end user. By click on each element you are able to add a Description, so here is how I made it:
To make things even better, if the user wants to abort the execution, I don't want to display the "Type the new hostname" element. Click in the blue triangle and choose Hide parameter input and press Ok:
This property enable us to Hide this parameter based on a condition. For the sake of simplicity, click on the Pen and mark att_abort, it will just look like this:
Throw exception
This element is used to throw an exception and fail the workflow. Using our user interaction as an example, we want the workflow to Fail in case the user aborts it, so we will wire a decision activity to deal with that.
Add a Decision component and you will not that two Workflow ends will be automatically added.
Delete the green line and drag the Throw exception component to the Decision activity, now it will looks like this:
On the decision activity, choose Decision tab, select att_abort and mark is true
If you now click on Validate you will note there is an error
That happens because you need to bind the exception, You can set the exception binding in the Exception tab or by doing the quick fix action. The exception binding is what is going to be displayed/returned if any component throws an exception.
Orchestrator uses a pre-defined variable called errorCode, but you can use anything you want. Click Bind exception… > Create parameter/attribute in workflow > Press OK
Now we are almost set for some first debugging. Do you remember that the user can re-input the hostname? In case our user do, we need to move our execution back to the beginning.
Before we move on, there is a problem with this workflow. We added our input variable in_hostname in all Decision activities which are responsible to make the workflow do the right things and the end user typed a new value on an attribute called att_hostname. Guess what is going to happen when we move the execution back to the beginning? You are right — nothing.
This is a problem which I stated in past: IN variables are immutable
So, we cannot put the att_hostname value into the in_hostname. We will, sadly need to refactor some actions. Of course this is pretty simple as this workflow does not have any sort of complexity but if you have a big one you are pretty much tending to have problems.
The first thing we are going to do: in_hostname will just receive our input and nothing else — it wont be used to take decisions anymore. att_hostname will hold it's value since we can change it anytime we want.
Lets create a Scriptable Task in the beginning of the workflow with just this code:
att_hostname = in_hostname;
Add in_hostname at the IN tab, and att_hostname at the OUT tab. This will be just like this:
Now the next thing we will do is change the two decisions and the action inputs to use att_hostname instead of in_hostname.
Now that we changed our workflow, the last Decision (which we check if the user typed a new hostname), needs to be changed. Delete the red line, hover into the decision and drag the Red right sign to our first decision, it will be just like this:
You noticed that this red line turned our workflow pretty ugly, so we need to reorder it to make things better. Just drag the elements to prevent this overlapping
Debugging
In orchestrator you can use the debug option to help you to…debug. It's not as powerful as Visual Studio or Eclipse, but surely will help you.
Move to the first Scriptable Task, right click and choose Toggle breakpoint. You will see now a blue circle will show in the bottom left of the Scriptable Task. That means when we start the workflow, it will break in the First element.
Click the Debug button (or press F11).
Fill the in_hostname with the VM-01-VCENTER and press submit. You will notice that our first Scriptable Task will turn green and nothing else will occurs. The breakpoint just paused the execution:
As you may have noticed, the top right now have 5 enabled icons, the first one is to abort the execution and the other 4, just like any regular debugger (Resume, Step Into, Step Out, Step Return).
If you've been debugging in Visual Studio, you know you can move the instruction pointer, change the code in runtime and more stuff. Would be awesome to have this kind of functionality but, there's not. You are pretty much tied to System.log(), which is good — but pretty limited.
Now you can click the Step Over (F6) to see the workflow moving to each element and you will see it will end up in the first gray circle.
There's a home lesson for you. Try those values in this workflow and see what happens on each one.
VM-01-VCENTER
VM-01-AZURE
VM-01-AMAZON
VM-01-GCP
VIRTUALMACHINE-01
