| Please Note: The PowerShell CmdLet Foundry is available in Adaptiva version 5.6 onwards |
In this article:
Overview
The Adaptiva PowerShell CmdLet Foundry allows for Administrators to convert workflows into powerful PowerShell commandlets (script that performs a single function). This allows Administrators to provide PowerShell integration and functionality without needing to write PowerShell.
PowerShell CmdLets can be either server-side workflow based or client-side workflow based meaning that they can either run on the Adaptiva Server itself or on Adaptiva Clients. This allows for client-side invocation but server-side execution. For example, let's say the administrator wishes to provide a PowerShell CmdLet that will retrieve something from a SQL database. Instead of having to grant every PC appropriate rights to query SQL and ensuring that all network communication is allowed from every location, the Admin can simply create a server-side workflow that queries from SQL and returns the desired results. The clients can then invoke that workflow and retrieve the results from the server.
Getting Started
Before creating a PowerShell CmdLet, an appropriate workflow will be required. For assistance with creating workflows, please see the Technical Reference Library section.
The workflow may have input properties (user-defined properties on the Start node) and it may also have output properties that will get output to the PowerShell command window upon execution (result properties on the End node e.g. ResultText).
Once an appropriate workflow has been created, the PowerShell CmdLet can be created using the PowerShell Cmdlets Perspective under the Misc folder in the Adaptiva Workbench (Adaptiva Server version 5.6 onwards). Navigate to Misc > PowerShell CmdLets Perspective.
Creating the Workflow Execution Policy
PowerShell CmdLets execute workflows but in order to allow execution of these workflows, a policy must be created.
Before creating the PowerShell Cmdlet, a workflow execution policy must be created.
On the right-hand side of the PowerShell Cmdlets Perspective, there are two tabs, the ServerWorkflowExecutionPolicyExplorer tab and the ClientWorkflowExecutionPolicyExplorer tab. Depending on whether the workflow to run is a Server workflow or a Client workflow, select the appropriate explorer tab.
Then, either right-click any folder and choose Create New Policy or click the green + icon to create a new policy.
The ServerWorkflowExecutionPolicyEditor or ClientWorkflowExecutionPolicyEditor will appear and prompt for data.
Server Workflow:
For a server workflow only two fields are required. The server workflow must be specified by clicking on the Add button to the right of the Server workflow box. Also, optionally a password can be specified. This would require a password to be entered before the workflow would run.
Client Workflow:
For a client workflow, the same two fields are present as with the Server workflow but with a client execution policy it is also possible to specify the scope of machines on which the workflow will be allowed to execute. This can be set to any collection or group. Alternatively, the tickbox Use All Adaptiva Clients can be selected which will allow the workflow to execute on any client.
Note: In this example, no execution password is specified
After setting the field data, click Save to save the workflow execution policy. This will send the policy to the devices that have been targeted and instruct them to allow execution of the specified workflow when requested.
The Workflow Execution Policy Settings window can then be closed.
Creating the CmdLet
To create a new PowerShell CmdLet, in the PowerShell CmdLet Explorer, either right-click on a folder and select Create New PowerShell Cmdlet or click the green + button.
This will open a new blank CmdLet page in the central view.
Cmdlet Name
The first thing to set in this new view is the verb-noun pair. PowerShell CmdLets use verb-noun pairs to define the command that is issued to PowerShell. Examples of this include Get-Process, Set-Location, New-Item etc.
PowerShell has a number of built-in recommended verbs, and these can be selected from the drop-down list. Alternatively, it is possible to manually enter the verb. The noun is specified in the Name field and can be any text string. Avoid using special characters.
For this example we are using a workflow that can send a wake-on-LAN magic packet to a machine to wake it from an offline/sleep state. Therefore, the verb in this case is Wake and the Name is Client. When issuing this command from a PowerShell window, the command Wake-Client would be used.
Remote Workflow Execution Policy Settings
The next step is to select the workflow execution policy that was created earlier in the Creating the Workflow Execution Policy section.
Select the radio button corresponding to the correct type of workflow (Server/Client). If the workflow is a server workflow, an additional checkbox option is available to allow the CmdLet to execute from any client. If this is checked, then the workflow will be published on the server but will be made available for any Adaptiva Client to use. This facilitates the scenario where a client should be able to invoke the command but the Adaptiva Server performs the actual execution and the results get sent back to the client.
Cmdlet Input Properties
The next step is to define any Input properties for the CmdLet. These will be the parameters that can be passed into the PowerShell command on the command-line. For example, the Get-Service PowerShell command supports the -Name, -DependentServices, -RequiredServices -Include and -Exclude properties.
In the case of workflow execution, the available input properties would be any user-defined properties on the Start node of the specified workflow. In the tutorial example, the workflow has two input properties - a string (TEXT) value for MachineName and an integer (WHOLE NUMBER) value for WakeUpTimeOutSecs. These allow for the name of the device to wake up to be specified, along with a timeout value for the WoL operation.
Any valid properties will be shown in the Available Properties box and can be added to the CmdLet by simply dragging them into the Assigned Properties box to the left.
Input properties can be defined as Mandatory by clicking on the checkbox next to the property name. Anything with the Mandatory checkbox unchecked can be omitted from the resultant commandline.
The example command-line in this case would be Wake-Client -MachineName "MYPC" -WakeUpTimeOutSecs 60
Where WakeUpTimeOutSecs could be omitted if desired.
Cmdlet Output Properties
In addition to Input Properties, it is also possible to define and map Output properties. These output properties will be returned as output properties on the returned PowerShell object after execution. To define these properties, select the View/Edit button next to the Output Properties field.
This will bring up the PowerShell Cmdlet Output Property dialogue box.
In here we can define one or more Output properties. Output properties can be one of two types:
- Primitive Type: Used when a standard primitive (String, Integer, Boolean etc.) is returned.
- Object Type: Used when an object is returned. When this option is selected, the class for the return object must be specified.
After selecting the Output property type, click on the Add Property button. This will bring up a further input box where the Property name and binding can be specified. The property name can be anything and will be the name of the property that PowerShell will return. The binding property differs depending on whether a primitive is being returned, or an object.
If an object is being returned, the Binding Property must be the property name of the class.
If a primitive is being returned, the appropriate binding property should be selected from the drop-down list and corresponds to the respective property on the workflow End node.
For example, to have the Cmdlet return the text output from the workflow on the End.ResultText property, a property called Output (could be any other name) can be defined with the Binding Property set to ResultText from the drop-down.
Click OK to add the property to the list of output properties.
Then click OK again to save the output property list.
Resultant View:
Cmdlet Usage Description
The final section is optional and allows for help text to be displayed when the end-user of the CmdLet enters Get-Help <CmdLetName>
The text shown in this box by default on creation of a new CmdLet is example text and can be modified or deleted.
The format shown adheres to the PowerShell Get-Help standard and is required for property displaying of the help text.
The text under .Synopsis can be replaced with a brief overview (normally a 1-line description) of the CmdLet.
The text under .Description can be replaced with a full description of the behaviour of the CmdLet.
Multiple .Parameter texts can be added to describe each of the parameters. Correct syntax here is .Parameter <ParameterName>
Multiple .Example texts can be added to give example uses for the CmdLet
Comments
0 comments
Please sign in to leave a comment.