In this article:
| Overview - Basic overview of the VB Custom Activity | ||
| Creating a new VB (VBScript) activity - How to create a new VB custom activity | ||
| Setting the Activity Details | ||
| Adding Input and Output Properties | ||
| Defining the Script | ||
| Using the Custom VB Activity - Adding the activity to a workflow and using it | ||
| Important Considerations - Items to consider when creating custom VB activities | ||
Overview
The workflow designer supports the creation of custom activities. One such custom activity is the VB custom activity. This facilitates the execution of VBScripts (Visual Basic Scripts [.vbs]) during the workflow execution and supports both the input and output of properties. The VBScript that runs can be used for retrieving data, modifying a setting or simply performing some defined action on a device.
Creating a new VB (VBScript) activity
In this example we are going to create a very simple new VB activity to retrieve the last modified date and time of a file. The name and path to the file will be passed in at design time (or at runtime) and the activity will return the last modified date and time.
Setting the Activity Details
To create a new VB 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 > VB activity.
A new window will appear that is used for specifying the activity metadata, properties and the VBScript 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: GetLastModified
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 last modified date and time of the specified file
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 "LastModified" will show on the canvas as LastModified1, LastModified2 etc.
Adding Input and Output Properties
To add a property, simply click the Add Property button.
The Specify Property Details window appears. The same window is used for both input and output properties and there is no distinction or requirement to specify whether the property that is being created is to be used as an input property, or an output property.
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: FilePath.
When adding the VBScript, the names of the properties must match exactly with the VBScript parameters queried in the script.
Data Type: The type of data that will be passed in. The VB activity only supports input properties of String (Text) or Integer (Whole Number). - examples include:
- Text - any arbitrary text string can be specified e.g. "hello world"
- Whole Number - a positive or negative non-decimal number e.g. -415
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 VB activity editor at a later date. Example: [INPUT] The full path of the file to query
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.
IsHidden: Check this box to not show this property in the workflow designer built-in properties view at design time.
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.
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.
We will create two properties, one for the file path that we will pass IN, and one for the date and time the file was last modified which will we pass OUT.
Defining the Script
The VBScript can be set and edited via the VB Script tab:
Properties/Parameters in the VBScript activity work differently to other activities. These are passed in and out of the activity/workflow using registry. Any properties that were created earlier need to be queried or set via registry. The registry path where these items are stored is passed through as the first argument to the script and can be queried using WScript.Arguments.Item(0).
An example of how to retrieve a property called FilePath is shown below:
Set oShell = WScript.CreateObject("WScript.Shell")
sFilePathReg = WScript.Arguments.Item(0) & "\FilePath"
sFilePath = oShell.RegRead(sFilePathReg)
In this example, we first create a Shell object, define a variable for the full path to the FilePath item in registry, and then use the Shell object to query that path.
The value of the file path property is then stored in the variable sFilePath which can be used later in the script.
We can then use the Scripting.FileSystemObject to retrieve an object representing the file at the path we passed in.
Set oFSO = CreateObject("Scripting.FileSystemObject")
Set oFile = oFSO.GetFile(sFilePath)
sLastMod = CDate(oFile.DateLastModified)
This retrieves the file, queries the DateLastModified property and stores it in a variable called sLastMod.
The final thing left to do is output the last modified date/time back to the workflow. To do this we use the LastModified property that we defined earlier and write back to the same area in registry that we used earlier.
sLastModReg = WScript.Arguments.Item(0) & "\LastModified"
oShell.RegWrite sLastModReg, sLastMod, "REG_SZ"
Here we create a new string (sLastModReg) to build the path to the registry value in question and then use the Shell object again to write a REG_SZ value containing the sLastMod data.
Script:
Set oShell = WScript.CreateObject("WScript.Shell")
sFilePathReg = WScript.Arguments.Item(0) & "\FilePath"
sFilePath = oShell.RegRead(sFilePathReg)
Set oFSO = CreateObject("Scripting.FileSystemObject")
Set oFile = oFSO.GetFile(sFilePath)
sLastMod = CDate(oFile.DateLastModified)
sLastModReg = WScript.Arguments.Item(0) & "\LastModified"
oShell.RegWrite sLastModReg, sLastMod, "REG_SZ"
Using the Custom VB Activity
Once the VB 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 VB Activity also has a few other built-in properties that can be changed, one of which (MaximumDuration) is mandatory:
DisableWow64Redirection: This true/false value indicates whether the file system operation that we choose should allow the OS to redirect operations that target 64-bit folders (such as C:\Windows\System32 or C:\Program Files into their corresponding 32-bit folder on 64-bit machines C:\Windows\SysWow64 or C:\Program Files (x86)). If this setting is true then on 64-bit machines, file system operations will target the 64-bit paths. On 32-bit machines this setting has no effect.
CaptureOutput: If this is set to true, the output text of the vbscript is captured, as if ran from a command prompt. The output text will be contained in and accessible via the OutputString property.
CaptureError: If this is set to true, any errors that occur during script execution are captured. These errors will be contained in and accessible via the ErrorString property.
MaximumDuration: [Mandatory] The maximum duration that the script can run for. To run indefinitely, enter 0 but be mindful that the script and workflow could run until forcibly terminated if there is something wrong with the script logic.
In this example, a logger activity will be placed directly after the VB activity to log the date and time the file specified (in this case C:\Windows\WindowsUpdate.log) was last modified.
The logger activity uses the following runtime expression:
"File " + LastModified1.FilePath + " was last modified on " + LastModified1.LastModified
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 the vbscript activity was successful and the workflow has output "File C:\Windows\WindowsUpdate.log was last modified on 19/04/2018 10:27:59"
Important Considerations
- The VBScript runs with the installed VB Scripting engine on the machine. If the machine is missing or has a corrupted VB Scripting engine then this activity would fail to run.
- The VBScript 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.
- Ensure the MaximumDuration property is set to an appropriate time to accommodate the runtime of the script. If the execution time is variable then a suitable time should be entered that accounts for the largest amount of time that it could take.
The workflow and VB Activity 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.