PowerShell Custom Activity

 

In this article:

Overview - Basic overview of the PowerShell Custom Activity
Creating a new PowerShell activity - How to create a new PowerShell custom activity
	Setting the Activity Details
	Adding Input and Output Properties
		Input Properties
		Output Properties
	Defining the Script
Using the Custom PowerShell Activity - Adding the activity to a workflow and using it
Important Considerations - Items to consider when creating custom PowerShell activities

 

Overview

The workflow designer supports the creation of custom activities. One such custom activity is the  PowerShell custom activity. This facilitates the execution of PowerShell commands during the workflow execution and supports both the input and output of properties. The PowerShell script that runs can be used for retrieving data, modifying a setting or simply performing some defined action on a device.

 

Creating a new PowerShell activity

In this example we are going to create a new PowerShell activity to retrieve the details about a specific installed Windows Service. The name of the service will be passed in at design time (or at runtime) and the activity will return the Service Name, Display Name and Status (running, stopped, start pending, etc) of the specified service.

 

Setting the Activity Details

To create a new PowerShell activity, first ensure the Workflow Designer Palette tab is selected.

Note: If the Workflow Designer Palette tab is not shown in the workflow designer, it must have been closed. On the top toolbar, select Perspective > Reset Perspective.

Next, right-click on any palette folder (including the Workflow Activities root folder) and select New > PowerShell activity.

A new window will appear that is used for specifying the activity metadata, input and output properties and the PowerShell script to be executed.

Provide the following details:

Activity Name: The name of the activity as it will appear in the workflow designer palette activity list. Example: GetWindowsServiceDetails

Activity Description: A description of what the activity will do. This text will appear when the activity is hovered over with the mouse cursor in the activity list. Example: Retrieves the Service Name, Display Name and Status of the specified service

Node Name Prefix: The name that will appear when the activity is dragged onto the designer canvas. The name is always proceeded with a number. Example: A node name prefix of "ServiceDetails" will show on the canvas as ServiceDetails1, ServiceDetails2 etc.

 

Adding Input and Output Properties

To add either an input or an output property, simply click the Add Property button.

 

Input Properties

For Input properties, ensure the Input Output Type is set to Input. Provide the following details:

Property Name: The name of the property as it will appear in the Built-In Properties list in the Workflow Designer Properties. This should be something that indicates to the designer of the workflow what the value represents. Example: ServiceName.
When adding the PowerShell script, the names of the Input properties must match exactly with the PowerShell parameters passed in on the script.

Property Description: The description for the property. This will appear when the mouse cursor moves over the property icon in the Workflow Designer Properties. It is sometimes useful to add a way to distinguish whether the property is an input or output property if viewing the PowerShell activity editor at a later date. Example: [INPUT] The name of the service to retrieve the details for

Data Type: The type of data that will be passed in - examples include:

• Boolean - a true/false value must be specified e.g. true
• Text - any arbitrary text string can be specified e.g. "hello world"
• Whole Number - a positive or negative non-decimal number e.g. -415
• Fractional Number - a decimal number including the decimal point e.g. 3.1415
• DateTime - an object representing a date and time e.g. 2000-01-01 12:00:00
• Boolean[] - an array of booleans
• Text[] - an array of text strings
• Whole Number[] - an array of non-decimal numbers
• Fractional Number[] - an array of decimal numbers
• DateTime[] - an array of DateTime objects

Can be initialized at design time: Check this box if the property will support adding an 'Initial Value' via the Workflow Designer Properties built-in property editor

Can be changed at run time: Check this box if the property will support setting the value at runtime using the 'Runtime Expression' field in the Workflow Designer Properties built-in property editor

IsMandatory: Check this box to enforce the setting of this property. If this is checked, an error will be thrown in the Workflow Errors view and deployment will not be allowed, if neither an initial value nor runtime expression are specified. 

Editor Type: This defines what type of editor control will be used for inputting the data. If TEXT is specified, a simple text field is specified, if COMBO is selected then multiple values can be added. COMBO is only available when the Data Type is TEXT. When DATETIME is selected the value is changed to Customizer which is the picker control used for datetime objects.

Initial Property Value: This allows for a default value to be specified for this property. This value will be displayed in the Workflow Designer Properties built-in properties list for the respective property.

 

Output Properties

For Output properties, ensure the Input Output Type is set to Output.

Property Name [Important]: The property name for an output property must be correctly defined and it's value is dependent upon one of two criteria:

1. If the PowerShell script outputs a simple primitive data type (i.e. a text string, number or boolean) then the Property Name must be of the correct type in the drop-down list:

• ResultBoolean: Set to this if the PowerShell script returns a boolean (true/false) value
• ResultText: Set to this if the PowerShell script returns a text string
• ResultWholeNumber: Set to this if the PowerShell script returns a non-decimal number (i.e. 31715)
• ResultFractionalNumber: Set to this if the PowerShell script returns a decimal number (i.e. 5.11)

2. If the PowerShell script outputs a .NET object (for example Get-Process returns a System.Diagnostics.Process object, Get-Service returns a System.ServiceProcess.ServiceController object etc.) then the Property Name must exactly match the name of the Property for that object.

Example: Get-Service returns a System.ServiceProcess.ServiceController object with properties Name, DisplayName and Status among others. To retrieve the DisplayName property of all matching services, the output should be the ServiceController object and the Property Name value should be set to DisplayName.

Property Description: The description for the property. This will appear when the mouse cursor moves over the property icon in the Workflow Designer Properties. It is sometimes useful to add a way to distinguish whether the property is an input or output property if viewing the PowerShell activity editor at a later date. Example: [OUTPUT] The displayname for the service

Data Type: The type of data that will be passed in - examples include:

• Boolean - a true/false value must be specified e.g. true
• Text - any arbitrary text string can be specified e.g. "hello world"
• Whole Number - a positive or negative non-decimal number e.g. -415
• Fractional Number - a decimal number including the decimal point e.g. 3.1415
• DateTime - an object representing a date and time e.g. 2000-01-01 12:00:00
• Boolean[] - an array of booleans
• Text[] - an array of text strings
• Whole Number[] - an array of non-decimal numbers
• Fractional Number[] - an array of decimal numbers
• DateTime[] - an array of DateTime objects

 

Bind this property to Dot Net property: This checkbox and text field allows the Property to bind to a specific property without requiring it to be called the same thing. For example, if the 'Name' field for the service was to be retrieved, it would not be possible to give it a Property Name of 'Name' as this would conflict with a built-in property for this activity. Instead, a Property Name of 'ServiceName' could be given and then in the 'Bind this property to Dot Net property' text field we could enter 'Name'.

 

Defining the Script

The PowerShell script can be set and edited via the PowerShell Script tab:

The first thing to do when defining the PowerShell script is to add any input parameters that have been defined earlier. These must use the standard PowerShell variable syntax ($), must match exactly with the name set previously and are defined using a Param(...) block as shown below:

The rest of the script can be defined and data is output by simply outputting the data as you would do normally in PowerShell.

The script below will output a .NET object containing the details of a Windows Service. This will have multiple properties but the ones that match the output properties defined earlier will be output back to the workflow. In this case, the DisplayName and Status of all matching services will be output.

 

Script:

Param (
$ServiceName
)

$Service = (get-service -Name $ServiceName)
$Service

 

Using the Custom PowerShell Activity

Once the PowerShell activity has been created it will appear within the Workflow Designer Palette.

To use the activity, simply drag and drop it into a new or existing workflow. The activity can be used as many times as desired either within multiple workflows or the same workflow.

 

In the Workflow Designer Properties view on the right-hand side, the input and output properties defined earlier will appear at the bottom of the list. These can be filled in as appropriate

The PowerShell activity is iterative, so if the output returns multiple values, the activity will run for each returned value. If an activity is dragged on top of (or slightly below) the custom PowerShell activity, a plus symbol [+] will appear to indicate that this activity will run for each item returned.

To have other activities run only once no matter how many objects are returned by the PowerShell, ensure that those activities are below the PowerShell activity, not inside it.

In this example, a logger activity will be placed inside the PowerShell activity so log the results of every Windows Service on this device that matches the name 'Adaptiva*'. The wildcard is used to indicate any service that starts with Adaptiva and has any other text after it.

 

The logger activity uses the following runtime expression:

"Service Display Name: " + ServiceDetails1.DisplayName + "." +
"Status: " + ServiceDetails1.Status

 

The workflow is then given a name and then Saved and Deployed (with logging enabled) 

The workflow is then executed. The workflow log file shows the output.

Note: The workflow logs can be found in the workflowlogs folder on either client or server (for business/server workflows the workflowlogs folder will be in the Server logs folder [default: C:\Program Files\Adaptiva\AdaptivaServer\logs\workflowlogs]. For client workflows, the workflowlogs folder will be in the Client logs folder [default: C:\Program Files (x86)\Adaptiva\AdaptivaClient\logs\workflowlogs]).

The workflow log name will match the name given to the workflow

We can see from the output that on this device two services were running that matched Adaptiva* (AdaptivaClient and AdaptivaServer) and both were in the 'Running' state.

 

Important Considerations

 

• The PowerShell script runs with a specific version of PowerShell which can change. It is important to ensure that the desired PowerShell script supports the executing version of PowerShell.
• The PowerShell script is executed by the AdaptivaClient in the context of the Local System account. It is important to ensure that the desired functionality is possible under this account.
• It's important to note whether the output of the PowerShell script is an object property or a primitive data type and set the appropriate output property.

 

The workflow and PowerShell script examples used in this article can be downloaded from the link below. Import the obex file using the Object Export-Import perspective in the Adaptiva Workbench.