VMware Orchestrator Beginners guide — Part 3: Actions
In the last chapter we've learnt how to create a simple workflow that interacts with JIRA REST API. Now we are going to learn how to create custom actions.
Actions are basically static JavaScript functions that can be dragged into Workflows, used to fill/validate presentation layers and fill vRealize Automation custom form elements.
Also, when you use Actions you are allowed to re-use your code even inside Scriptable Tasks — that will keep your code well organised and easier to modify. Of course, remember that change an Action will reflect everywhere that calls it.
To start creating your actions you'll need to create a Module, which is basically a group of Actions and a way to organise them, looks like a package on Java or a namespace on C#.
In Orchestrator main screen choose the Design mode and click on the second tab Actions. Right click on the root and choose New module.
If it does not appear, press F5 since there is a bug on vRo that prevents to display the vertical scroll bar.
We are going to name the module as org.company.vroclass, it should look just like this:
Now we are going to create a (very) simple action listIssueTypes to return an array with allowed JIRA's issue types that the user can create using the workflow created previously. So right click on your org.company.vroclass module and press Add action. Name it listIssueTypes and the Action editor will show up just like this:
Now, move to the Scripting Tab. The first thing to do is set the return type, that is, what kind of object should be returned back to the callee. By default, void is set. Click on void and select the radio button Array Of then filter string, it should look like this:
Press Accept.
On the editor textarea we are just going to type the following:
return ["Bug", "Task"];Pretty simple eh? Let's just save this Action and we are going to create a new one, a lit bit more fancier. Remember that we already have a workflow to post an issue, right? We are soon going to create an Action that GET an issue by its key.
You may be asking yourself: why would I prefer to create an Action instead a Scriptable Task into a Workflow?
Actions are way faster than workflows because they aren't queued, no tokens are created and they could be used just like a Scriptable Task — or into a Scriptable Task.
Workflows are way easier to debug, you see things in a more graphical way, they can be used to create XaaS on vRealize Automation, they got presentation and more stuff. Actions are just plain JavaScript functions that may be used as workflow helpers aside from the other usages.
For now, if you think a certain part of your code is going to be used on another workflows, try avoid Scriptable Tasks into Workflows and keep your reusable code into Actions.
Now let's create an Action that will get issues from JIRA.
Move to the Action tab, right click on org.company.vroclass and press New Action. Name it getIssue and press Ok.
Now we are going to create two parameters, one is the RESTHost to connect and the other one, the issue key.
Click on the third icon (Right sign with a plus) twice and you will note an arg0 and arg1 with type string will appear just like this:
Click on arg0 to rename it as jira_endpoint and click on string type change the type to RESTHost. Do the same with arg1 and rename it as issue_key keeping the type string. The result should be like this:
We are now ready to code. You may just copy and paste the following code since it's almost the same code we used when we POSTed to create a new issue.
Note the endpoint changed, HTTP Verb was changed to GET and the payload is now just an empty string, also, System logs were omitted for brevity and we are not performing any exception handling for now.
Just save your action and move back to the JIRA > Issues folder on the Workflow tab. We will create a new workflow called Get issue. Just right click the Issues folder and press New Workflow. Name it Get issue and press OK.
When the workflow designs shows up, instead adding a new Scriptable task we will search our previously created action by type getIssue at the search bar:
Now drag and drop the getIssues on the tiny line between the beginning and the end of workflow. It now should look like this:
Now we need to map the values to the action. There are two ways to do that, either by clicking Setup at the gray bar that just appeared or map previously created workflow variables. You may choose whatever met your needs, but for didactic, we will create the variables on their respective tabs.
We will create an attribute named att_jira_endpoint typed RESTHost with JIRA's REST Host assigned, an input variable named in_issue_key typed string and an output variable name out_result. I hope you remember how to do that, if you don't, you should go back on variable declaration. In case you do, thats how its going to be:
Now just click on your action getIssue and map the Input variables. Move to the Action IN tab and click on "not set"of each parameter and choose the corresponding variable. It should look like this.
Repeat the step for the Output tab:
Don't worry about the Scripting tab as it says it can't be modified. Just press Run,type an issue key and press Submit:
Now if you check the Variables tab at the right, you will see that out_result is filled with the JSON response from the API.
As you can see, things worked accordingly, now what if you want to call the Action into an Scriptable Task?
Pretty easy. Click on the action and delete it by press you Del button or by clicking the red X. Now drag an scriptable task and paste the following code:
out_result = System.getModule("org.company.vroclass").getIssues(jira_endpoint,in_issue_key);
If you just press Run, fill the issue key and Submit you will get a ReferenceError: jira_endpoint is not defined. Remember about the variable IN and OUT? You need to fill them — I always tell people to double check IN and OUT variables before toast their brain into troubleshooting.
Also do remember that, if you add a variable at the OUT tab and do not set any value on it using your script, it will be wiped. So, if you had set a value in past or maybe a static value on your General tab, you will end up with an empty/null variable — this causes a lot of trouble specially if you are into a large workflow and maybe add by mistake an out variable.
Now, lets fix this problem:
Run your Workflow again and we have our out_result filled with the API response JSON exactly how it was being done with the plain action.
Use actions inside Scriptable Tasks is a good option when you have to deal with Workflow-specific code and you don't want to make it too big or declare too many variables (ending up with the variable hell).
Emulating an Object into a Orchestrator Action
If you are into JavaScript you are probably asking yourself "What if I have a library with a lot of functions? Will I need to transform each one into a separate action?". The answer is: depends on what are you going to use.
If you need this class to perform validation inside Orchestrator presentation layer or use as a External function on vRealize Automation, the answer, unfortunately, is Yes — you will need to separate each function in actions. But if you are just going to use this library inside another actions AND/OR into Scriptable Tasks, there is a trick to emulate an Object when you create an action so, lets assume the following JavaScript code:
var MathFunctions = {
sum: function(a, b) {
return a+b;
},
sub: function(a,b) {
return a-b;
},
div: function(a,b) {
return a/b;
}};
Create a new Action into org.company.vroclass called MathFunctions.
- Set its returning type to void
- Do not set any parameters
- Paste the following code:
var MathFunctions = {
sum: function(a, b) {
return a+b;
},
sub: function(a,b) {
return a-b;
},
div: function(a,b) {
return a/b;
}};
return MathFunctions;
Save your Action.
To use it on another Action or an Scriptable Task:
var MathFunctions = System.getModule("org.company.vroclass").MathFunctions();
var result = MathFunctions.sum(1,2);
And there you go, one Action — many functions. This trick is pretty useful and time saving.
I hope you have enjoyed! In the next article we will learn about Workflow Components
