Mini-Lab: Orchestration - Calling a Script With a Custom Run PowerShell Activity - Part 2 (HELSINKI)

[sabell2012]

NOTE: MY POSTINGS REFLECT MY OWN VIEWS AND DO NOT NECESSARILY REPRESENT THE VIEWS OF MY EMPLOYER, ACCENTURE.

DIFFICULTY LEVEL:   ADVANCED

RELEASE DEVELOPED IN:   HELSINKI

Assumes good knowledge and familiarity of Workflows, Scripting and Orchestration in ServiceNow.

____________________________________________________________________________

In Part 1 I showed how to run a PowerShell script using both the un-deprecated Run PowerShell Activity, and also how to construct a simple Custom version to do the same.   Now the thing to do is to make the Custom version act like the original Run PowerShell Activity.   Two things are missing for the Custom version:   1) There needs to be a way to pass in the script name as a variable, and 2) there needs to be a way of passing in a JSON containing multiple dynamic variables.   Well, I am happy to say there is a way to do this.  

So we will be constructing a new Custom Activity from scratch using a format similar to the Echoback Custom Activity we created in the previous article.

Pre-Requisites

You will need to install your own local MID Server if you do not have one already.

Install a MID Server on Windows

You will need work through lab 1.1 of the following article:

Mini-Lab: Orchestration - Bringing Back the Run PowerShell Activity

You will need to then work through the labs in Part 1 of this series:

Mini-Lab: Orchestration - Calling a Script With a Custom Run PowerShell Activity - Part 1

Lab 1.1: Creating the Run PowerShell Script Custom Activity

So we have our requirements to recreate the capabilities of the Run Powershell Activity:

1. The Powershell Script name will be passed into the Custom Activity using a variable.

2. The Powershell parameters will be passed in as JSON not singly as in the example from Part 1.

So let's get started!

1. In the Workflow Editor navigate to the Custom tab, and click the plus ("+") button to create a new Activity.   This will display the context menu where you can choose a custom Activity Template.

2. Choose the Powershell Template from the menu.   This will display the Activity Designer with the template form.

3. Fill out the form with the following:

1. Name: Run PowerShell Script
2. Short Description: Run a given Powershell MID Script
3. Accessible from: All application scopes
4. Category: PowerShell
5. Description: Run a given Powershell MID Script
6. Click on the Continue button to display the Inputs form.

NOTE: We will build this example Globally scoped.   If you want to put one into the actual OOB PowerShell folder then you will need to change the application scope to PowerShell, create the new Custom Activity, and clear out the Category.   Then it will appear in the PowerShell folder, and you can still use it in your Globally scoped workflows.

4. Add four fields

1. Name: Hostname, Type: String
2. Name: Scriptname, Type: String
3. Name: Parameters, Type: String
4. Name: Credential, Type: String
5. Click on the Pre-Processing button to display the Pre-Processing form.

5. On the Pre-Processing form fill out the following:

1. Input Processing Script:

if (activityInput.Parameters !== null) {

  // got this idea from the uncallable Script Include: ExchangeUtil

  // convert the incoming JSON string to an Object array

  var params = new global.JSON().decode(activityInput.Parameters);

  // loop through the array and pull out the key/value pairs

  for (var key in params) {

          var parameter = {};

          parameter.name = key;

          parameter.type = "plain";

          parameter.value = params[key];

          // this is how you actually place the variables into the execution call

          executionParam.powershellVariables.push(parameter);

  }

}

if (activityInput.Scriptname !== null) {

  gs.info('---> activityInput.Scriptname: ' + activityInput.Scriptname);

  // the MID Script File field is a reference field and will only take a sys_id

  // so retrieve the sys_id of the given Script.

  var scriptFileRecords = new GlideRecord('ecc_agent_script_file');

  if (scriptFileRecords.get('name', activityInput.Scriptname)) {

          gs.info('---> sys_id: ' + scriptFileRecords.getValue('sys_id'));

          executionParam.midScriptFile = scriptFileRecords.getValue('sys_id');

  }

  else {

          gs.info('---> bad Scriptname: ' + activityInput.Scriptname + ' does not exist.');

  }

}

else {

  gs.info('---> bad scriptfile: ' + activityInput.Scriptfile);

}

2. Click on the Continue button to go to the Execution Command form.

NOTE:   You can see that we are filling in the MID Script File field from the input variable, and the powershellVariables as well.   The Pre-Processing script gives the developer the ability to manipulate the incoming variables and adjust them for the Execution Command form.

6. Fill in the form with the following:

1. Drag the Hostname field to the Target host field
2. Script Type: MID Server script file
3. MID Server script file:   <<leave this blank>>

NOTE: This field that cannot directly be a variable.   We actually filled it in with the Pre-Processing script.

4. Leave the Powershell variables blank.   We filled these in with the Pre-Processing script as well.
5. Drag the Credential field to the Credential tag field
6. Click the Continue button to continue to the Outputs form.

Your Execute Command form should look something like this:

Nifty, huh?   BTW, you can get the names of the actual fields from this form simply by right-clicking on the field label.   The only one you can't do this with is the Powershell variables field which will always be powershellVariables.

7. Add three Output fields (from this point forward the creation of the new activity will be the same as in my previous two articles).

1. Name: result, Type: String
2. Name: output, Type: String
3. Name: errorMessage, Type: String
4. Click on the Go To Post-Processing button to continue.

8. Fill in the form with the following:

1. Output process script (seem familiar - best way to do this):

if (gs.nil(executionResult.error)) {      

    activityOutput.result = "success";      

      try {      

                  var output = executionResult.output;      

                  if (output != null) {      

                            activityOutput.output = output.substring(output.indexOf('<Objects>'));    

                            gs.info('---> activityOutput.output: ' + activityOutput.output);   // DEBUG    

                  }    

      }      

      catch(err) {    

                  gs.error('---> ERROR: ' + err);      

      }      

}        

else {      

      activityOutput.result = "failure";      

      activityOutput.errorMessage = executionResult.errorMessages;      

      gs.info('---> activityOutput.errorMessage: ' + activityOutput.errorMessage);   // DEBUG    

}      

2. Click the Continue button to continue to the Conditions form.

9. Add two condition fields:

1. Name: Success
   1. Condition:   activityOutput.result == 'success'
   2. Order: 100
2. Name: Failure
   1. Condition: activityOutput.result != 'success'
   2. Order: 200
3. Click on the Save button to save the new Activity.

10. In the Workflow Editor navigate to Custom -> Global -> PowerShell.   You will now see your new Run PowerShell Script Activity present.

11. Open the Powershell Script Test Workflow (from the Part 1 article).

12. Navigate to Custom -> Global -> PowerShell and drag out a Run PowerShell Script activity.   The new Activity form will be displayed.

13. Fill in the form with the following:

1. Name: PowerShell Script Test Generic (Global)
2. Hostname: 127.0.0.1
3. Scriptname: echoback.ps1
4. Parameters: {"parm1":"test1","parm2":"test2","parm3":"test3","parm4":"test4"}
5. Click on Submit to save your work.

NOTE: We are reusing the echoback.ps1 script we created in the Part 1 article.

14. Change the wiring up to look like this:

15. As we have added a new control to the Workflow we will need to modify the Run Script Activity to reflect the Data number of the new control.

NOTE: It is important to understand that workflow.scratchpad (and other workflow variables) are not available inside the Custom Activity!   Only what you send in via the input variables.

NOTE: The Data object number will likely be different than mine.   It is different for every Custom Activity you add to the form.

1. Name: Handle Results
2. Script:

gs.info('---> previous_activity.result: ' + data.get(9).result);  

gs.info('---> previous_activity.output: ' + data.get(9).output);  

//gs.info('---> previous_activity.errorMessage: ' + data.get(9).errorMessage);  

var results = {output : '', error : ''};  

results.output = data.get(9).output;  

results.error = data.get(9).errorMessage;  

workflow.info('---> [{1}] {0}', [results.output, 'WF:Powershell Test']);  

workflow.scratchpad.output = results;

3. Click the Submit button to save your work.

16. Run the workflow.   You should have a successful run that looks like this:

17. From your instance navigate to System Logs -> System Log -> All.   The System Logs list view will be displayed.

18. Filter for messages starting with "--->", and order by Created descending.   You should see an entry like the following:

Eureka (not the version)!   It works!

So there you have it!   All of that to re-create the Run Powershell Activity's ability to dynamically run a powershell script!   Whoosh.

There are some pretty cool capabilities that the Custom Activity Creator gives you.   I have demonstrated the how, and the why.   It is up to you to take it to the next level!

Enjoy!

Steven Bell.

If you find this article helps you, don't forget to log in and "like" it!

Also, if you are not already, I would like to encourage you to become a member of our blog!