Orchestration is becoming one of the most popular applications to use for automating processes, especially outside of the ServiceNow instance. You can use Orchestration activities to Update Active Directory accounts, restart a Linux server, and much more. One of the most common uses of Orchestration is with running Powershell-related commands and scripts against Windows servers.
Some applications, when you install them (e.g. Password Reset), come with Powershell Orchestration activities that you can use. You also have the option of creating your own Powershell activities.
As mentioned in this other great Community article here, as of our Helsinki release, we have deprecated using our general "Run Powershell" activity and require you to use our Orchestration Activity Designer to build out new Powershell activities (although, if you have old workflows still using the old "Run Powershell" activities, these will still work). By using this new Orchestration Activity Designer to build custom Powershell activities, you have much more control of most of the aspects of this activity, from the inputs, to the script/commands you wish to run, to the outputs as well.
Overall, however, when using these Powershell activities (whether custom created or out-of-box), there are also some limitations and issues you can run into if you are not careful with how you are setting this up.
Here are a few quick tips of issues I have personally come across that may be good to be aware of as you are setting up these Powershell activities on your instances.
----------------------------------------------------------------
1. MID Server selection
A very common issue I have seen is understanding how/when a particular MID Server is selected to run these Orchestration activities.
While there is an article here that details the criteria of what is being checked against with regards to selecting a MID Server, this can even be a little confusing with regards to "Capabilities" and "IP Ranges," and even with selecting the "Default MID Server."
Let me try to break down what you should be looking for when trying to select a MID Server to use for these activities.
a) First, you will need to set up any necessary capabilities for the MID Server(s) that you wish to use.
These can be set up on the MID Server records themselves in the Related List appropriately titled "Capabilities" (or, if you go to the "ecc_agent_capability" table and open the particular Capability you want, then there will be a Related List of "Mid Servers" for which you can link any of your MID Servers to this Capability).
Now, the Capabilities that you decide to link to the MID Servers you wish to use need to match with the "Required MID Server capabilities" value that are defined in your Orchestration activity under the "Execution Command" section, as seen in this screenshot below.
For Powershell activities, typically what is already included is this "Powershell" capability, so you will want to make sure that any MID Servers you want to use for this activity have this "Powershell" Capability linked to it.
b) Secondly, you also need to specify which MID Server to use based on the IP or Hostname that you declare for this activity.
As you can see also in the screenshot above, for the "Target host" variable, this is where you decide the IP or hostname that you want this Powershell command or script to run against.
If you put a direct IP address value here, this makes it simple as all you would need is to create a record in your "ecc_agent_ip_range" table that has this IP (or a range that includes this IP) and then (again) there will be a Related List for this record called "MID Server" where you can link your MID Servers to this IP Range.
If you put a hostname value (like the "mycomputer" example I have above), then you would need an additional "cmdb_ip_address_dns_name" record that associates this hostname to a specific IP address, and then again, this IP address can be included in this IP Range record to be used.
Once you have both of these in place, then whatever MID Server(s) match both these criteria can be used to run your Powershell activity.
If you have more than 1 MID Server that meets these criteria, then the MID will be chosen at random.
However, if for example you don't have any MID Servers setup with the Capability defined in the activity, or if you don't have an IP range record linked to any of your MID Server with the IP you are targeting, then we will default to use the Default MID Server.
Please be aware of this when setting up your Orchestration activities in case you are not seeing a specific MID Server being used that you are expecting to be used for these activities.
2. Make sure your "Target" Server and MID Server are different
Another common "mistake" that people make, especially while testing their Powershell activities is that for the "Target host," is choosing the same hostname/IP as the MID Server they want to use to execute the script. For example, you choose a MID Server that is on the IP "10.123.47.8" and the "Target host" for your activity is also "10.123.47.8".
The issue that occurs here has to do with the credentials that you may need to use to run the commands that you are specifying in your activity.
If the command or script you are trying to execute requires you to use a specific credential, then you will have issues when trying to run this Powershell activity against the same IP as your MID Server because there appears to be a Windows restriction where you can't pass in a "Credential" value when executing these commands locally.
What will happen from a ServiceNow perspective (based on default settings) is that we may try to use your Windows credentials to execute this command, but since those will fail, we will end up trying using the "MID Server Service Account" credential (which in most cases is just a "Local System Account"). If this account can't run the script accordingly, then your activity will fail.
The best and easiest way to see how this is occurring is to do manually follow these steps on one of your MID Server hosts:
a) Log in to a Windows machine as an admin (or a user with admin privileges) and open the "Windows Powershell" command window, or open a regular "cmd" window and launch Powershell.
b) Next, type in a simple command like "gwmi win32_operatingsystem" and you should get an output like below:
c) Try adding these following parameters in your command as well:
Computer -> This is where you can declare the IP/Hostname of the target device you want to run this command against.
Credential -> This is where you can type in the username of an account to use to login to this target device.
In this next example, my computer name is "wvmsancthompson", so when I try running this command passing in my current computer name and my currently logged in user ID, I will first be prompted to type the password for this id, but after doing that, I will end up getting this error:
If you remove the "-Computer" parameter from here and just have the additional "-Credential" parameter, you will still get this error to occur as well.
d) However, just to prove that this works if scanning against a different computer, if I pass in an IP of a different device in my network, I get this result:
If you are executing some specific script or commands that are required to be ran as a specific user, you can see how trying to pass in the Credential of that user to try to run this script locally will throw this "User credential cannot be used for local connections" error, and thus cause your activity to error out as well.
Therefore, I would advise you should always set up to have your Powershell activities be ran against different devices other than the server that is hosting your MID Server.
3. Be careful of special characters
Finally, what you may notice on our platform with regards to inputs and outputs for some of these activities is that we sometimes pass in or receive values in a "JSON" format.
For example, in a few of our default AD-related activities like Create AD Object and Update AD Object where we have a parameter called "ObjectData" that are expecting values to be included in a JSON format.
While normally this doesn't cause any problems, if you are including values that may have special characters (like a comma, a quotation mark, or even a backslash), it can create some issues when being converted to be used for Powershell.
So, for example, let's say you are including an "Update AD Object" activity in a workflow and you want to update a Manager AD field to put a manager's name here, like "Murphy, John." Ideally, you would expect to just put this value in the "ObjectData" field as a JSON String like this below:
{"manager" : "Murphy, John"}
However, you would likely get an error to occur with this value because this comma character is not being escaped properly by the time we are trying to pass in this value to the AD Server.
Instead, you need to add backslashes to escape this "comma" character so it can be passed once it's converted in the Powershell script. In fact, in this scenario, you likely would need to add two backslashes to make this look like below:
{"manager" : "Murphy\\, John"}
This is because you need one backslash to escape the comma character, and then you need a second backslash to escape the first backslash character (since the backslash itself is a special character as well).
Also, another issue is that if you are not directly putting the value in the "ObjectData" field itself, but instead grabbing this from a variable or field on a record from the instance, then you may need to use as many as four backslashes to escape a character, because you will likely need two backslashes for escaping when converting the "Javascript" definition of the character to JSON.
You can read this Community article with more details: Constraint Violation with Orchestration when creating an account - the manager attribute has a backs...
Now, I'm not sure overall which characters would have this condition occur for them, but if you are seeing issues occurring with using other characters like ampersand (&), asterisks (*), etc., please check and see if adding these backslashes can help for those characters as well.
----------------------------------------------------------------
I hope this can be helpful to anyone if you are seeing any of these common types of issues or errors arising when setting up your own Powershell Orchestration activities and workflows.
If there are any other common issues that you come across, and if you have some suggestions about how to handle these types of situations, please feel free to comment below. I would love to hear feedback and more ways to fix these types of problems.
3 Comments
