PowerShell CmdLet Foundry User Guide – Adaptiva Support Portal

Overview

The Adaptiva PowerShell CmdLet Foundry enables Administrators to convert workflows into powerful PowerShell Cmdlets (scripts that perform a single function). This feature also allows Administrators to integrate and utilize PowerShell without writing any PowerShell code.

Getting Started

The workflow may contain input properties (user-defined properties on the Start node) and output properties that provide output to the PowerShell command window upon execution (such as the ResultText property on the End node).

Creating a Workflow Execution Policy

Before developing a PowerShell CmdLet, you must create a workflow execution policy. Create a client workflow execution policy that targets all Adaptiva clients or one or more target groups. You may also choose create a server execution policy that executes the PowerShell Cmdlet on the Adaptiva Server.

Add a Client Workflow

Select Workflows > Execution Policies > Client from the left navigation menu on the Adaptiva OneSite Admin Portal.
Choose a client workflow on the Client Workflow Execution workspace using the following steps:
1. Select +New to add a client workflow.
  
  This opens the General Settings workspace:
2. Select Browse to find a client workflow.
  
  This opens the Workflows dialog:
3. Search for the desired client workflow using the following search methods:
  - Select Show All on the upper-right corner of the Workflows workspace to see all client workflows.
  - Select a Workflows folder on the Add Workflow dialog to find the desired client workflow.
  - Use the navigation tools on the lower-right to scroll through the pages to find and select a client workflow.
  - Enter a client workflow name on the search line, and then click Search to find and select a specific client workflow.
4. Select the desired client workflow in the Workflows list, and then select Add Workflow to return to the General Settings workspace.
  
  This opens the General Settings workspace with the execution policy appearing on the Client Workflow line:
(Optional) Enter a password on the Password line to be validated when executing the workflow.
(Optional) Select Use All Adaptiva Clients to allow the workflow to execute on any client.
Add target groups using the following steps:
1. Select + Add Groups in the Target Collections section.
  
  This opens the Groups workspace:
2. Select a Group Name from the Groups list.
  
  Note
  
  In addition to Groups, you can also target Business Units or (if integrated with Configmgr Collections.
3. Select Add Groups on the lower-left corner to return to the General Settings workspace.
  
  This opens the General Settings workspace with the group appearing in the Target Groups list:
Select Save on the upper-left corner of the Server Workflow Execution Polices workspace to execute this policy on any collection or group:
1. Check the Error View and resolve any errors.
2. Select Save again if you make any changes.

Add a Server Workflow

Select Workflows > Execution Policies > Server from the left navigation menu on the Adaptiva OneSite Admin Portal.
Select +New on the upper-right corner of the the Server Workflow Execution Policies workspace to add a server workflow.

This opens the General Settings workspace:
Choose a server workflow using the following steps:
1. Select Browse to find the desired server workflow.
  
  This opens the Workflows dialog:
2. Select the desired server workflow using the following search methods:
  - Select Show All on the upper-right corner of the Workflows workspace to see all server workflows.
  - Select a Workflows folder on the Add Workflow dialog to find the desired server workflow.
  - Use the navigation tools on the lower right to scroll through the pages to find and select a server workflow.
  - Enter a server workflow name on the search line, and then click Search to find and select a specific server workflow.
3. Select the desired server workflow in the Workflows list, and then select Add Workflow to return to the General Settings workspace.
  
  This opens the General Settings workspace with the workflow appearing on the Server Workflow line:
(Optional) Enter a password on the Password line that validates when the workflow executes.
Select Save to send the policy to the targeted devices and allow execution of the specified workflow when requested.

Creating a PowerShell Cmdlet

After choosing the appropriate Workflow Execution Policy, use the PowerShell Cmdlet workspace to create a PowerShell Cmdlet. You can create either server-side workflow based or client-side workflow based PowerShell CmdLets. Server-side workflows can either run on the Adaptiva Server itself or on Adaptiva Clients using client-side invocation with server-side execution. Client-side workflows will run on any client, including the client running on the server.

For example, when an Administrator wants a PowerShell CmdLet to retrieve data from a SQL database, they can create a server-side workflow that queries the SQL database and returns the results. With this approach, it is not necessary to grant every PC the necessary rights to query SQL, opening network communication to all locations. Clients can then invoke this workflow and retrieve the results from the server.

PowerShell Cmdlet Naming Conventions

Define PowerShell Cmdlet commands with names using verb-noun pairs, such as Get-Process, Set-Location, and New-Item. You can use any text string when naming these commands. Do not use special characters.

For example, use the verb wake and the noun client to send a WOL magic packet to wake up a machine from an offline or sleep state.

Name a PowerShell Cmdlet

Select Tool Foundry > PowerShell Cmdlets from the left navigation menu on the Adaptiva OneSite Admin Portal.
Select +New on the upper-right corner of the PowerShell Cmdlets workspace to create a Cmdlet.

This opens the Cmdlet Name workspace:
Create a PowerShell Cmdlet name using the following steps:
1. Enter a verb on the Cmdlet Verb line.
2. Enter an action on the Cmdlet Action line.

PowerShell Cmdlet Help Text

PowerShell Cmdlet Usage Description displays help text when the user enters the command Get-Help <CmdLetName> into the command prompt window. When creating a new PowerShell CmdLet, you can use PowerShell Cmdlet commands create, modify, and delete help text that displays in the command prompt window. You must use the PowerShell format Get-Help standard to display the help text.

PowerShell Cmdlet Help Text Best Practices

Use the following best practices when creating the help text for the Usage Description:

Replace the text under .Synopsis with a brief overview (usually a one-line description) of the PowerShell CmdLet.
Replace the text under .Description with a full description of how the PowerShell CmdLet behaviors.
Add multiple .Parameter texts to describe each parameter. Be sure to use the correct syntax, which appears as: .Parameter
Add multiple .Example texts to provide example use cases for the PowerShell CmdLet.

PowerShell Cmdlet Command Options

When choosing which PowerShell Cmdlet commands to create help text, you have the options in the table below.

PowerShell Cmdlet Command	Command Function
`.Synopsis`	Wakes a client using WOL Magic Packets.
`.Description`	Wakes a client using WOL Magic Packets. Receives the machine name and wake up timeout as input.
`.Parameter MachineName`	The NetBIOS name or FQDN of the machine set to wake up.
`.Parameter WakeUpTimeOutSecs`	The time out duration (in seconds) for the wake on LAN request. If timeout is reached, failure to wake machine is assumed.
`.Example`	Wakes a machine called MYPC with a timeout of 60 seconds. Use the following example PowerShell Cmdlet command to wake a machine: `Wake-Client -MachineName "MYPC" -WakeUpTimeOutSecs 60`

Create PowerShell Cmdlet Help Text

Select Tool Foundry > PowerShell Cmdlets from the left navigation menu on the Adaptiva OneSite Admin Portal.
Select New on the upper-right corner of the PowerShell Cmdlets workspace.

This opens the Cmdlet Name workspace:
Create a PowerShell Cmdlet name using the following steps:
1. Enter a verb on the Cmdlet Verb line.
2. Enter an action on the Cmdlet Action line.
Enter PowerShell Cmdlet commands into the Usage Description window to display to users in the console window when executing the PowerShell Cmdlet.

Remote Workflow Execution Policy Selection

After creating a Workflow Execution Policy, you must add the execution policy you created to a PowerShell Cmdlet to execute the workflow.

Workflow Execution Policy Options

When choosing the Workflow Execution Policy, you have the following options:

Sever Workflow Execution Policy: Executes the PowerShell Cmdlet on the Adaptiva Server.
Client Workflow Execution Policy: Executes the PowerShell Cmdlet on all clients or one or more target groups.

Add a Server Workflow Execution Policy

Select Tool Foundry > PowerShell Cmdlets from the left navigation menu on the Adaptiva OneSite Admin Portal.
Choose a Cmdlet, and then select Edit from the Actions dropdown menu.
Scroll down to the Remote Workflow Execution Policy section in the PowerShell Cmdlets workspace.
(Optional) Select Allow Cmdlet to from any client to enable the client to invoke the command and the Adaptiva Server to perform the execution. The server then sends the results back to the client.
Add the desired Server Execution Policy from the Server Execution Policy tab using the following steps:
1. Select Browse in the Remote Workflow Execution Policy workspace to find the desired execution policy.
  
  This opens the Add Server Workflow Execution Policy dialog:
2. Search for the desired server execution policy using the following search methods:
  - Select Show All on the upper-right corner of the Workflows workspace to see all server execution policies.
  - Select a Workflows folder on the Add Workflow dialog to find the desired server policy.
  - Use the navigation tools on the lower right to scroll through the pages to find and select a server policy.
  - Enter a server policy name on the search line, and then click Search to find and select a specific server execution policy.
3. Select the server execution policy from the list that appears.
4. Select Add Server Workflow Execution Policy to return to the Server Execution Policy tab.
  
  The server execution policy appears on the Server Execution Policy line on the Server Execution Policy tab.

Add a Client Workflow Execution Policy

Select Tool Foundry > PowerShell Cmdlets from the left navigation menu on the Adaptiva OneSite Admin Portal.
Select a Cmdlet, and then select Edit from the Actions dropdown menu.
Scroll down to the Remote Workflow Execution Policy section.
Add the desired Client Workflow Execution Policy on the Client Execution Policy tab using of the following steps:
1. Select Browse in the Remote Workflow Execution Policy workspace to find the desired execution policy.
  
  This opens the Add Client Workflow Execution Policy dialog:
2. Search for the desired client execution policy using the following search methods:
  - Select Show All on the upper-right corner of the Workflows workspace to see all client execution policies.
  - Select a Workflows folder on the Add Workflow dialog to find the desired client policy.
  - Use the navigation tools on the lower right to scroll through the pages to find and select a client policy.
  - Enter a client policy name on the search line, and then click Search to find and select a specific client execution policy.
3. Select the desired client execution policy from the list that appears.
4. Select Add Client Workflow Execution Policy to return to the Client Execution Policy tab.
  
  The client execution policy appears on the Client Execution Policy line on the Client Execution Policy tab.

PowerShell Cmdlet Input Properties

Define input properties for the CmdLet to pass these parameters 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 this workflow execution example, the workflow uses a string (TEXT) value for MachineName and an integer (WHOLE NUMBER) value for WakeUpTimeOutSecs. These specify the name of the device configured to wake up, along with a timeout value for the WOL operation.

The example command-line in this case appears as Wake-Client -MachineName "MYPC" -WakeUpTimeOutSecs 60. Omit WakeUpTimeOutSecs, as necessary.

Choose the PowerShell Cmdlet Input Properties

Navigate to Tool Foundry > PowerShell Cmdlets on the left navigation menu on the Adaptiva OneSite Admin Portal, and then scroll down to the Cmdlet Input Parameters workspace.
Add an Input Parameter using one of the following options:
Select an Input Parameter from the Input Parameters list.

Note

Inputs appear in the Input Parameters list this list depending on the workflow you selected in the Remote Workflow Execution Property section.
Create an Input Parameter using the following steps:
1. Select Create Input Parameter to create a parameter.
  
  This opens the +Create Input Parameter dialog:
2. Select the Property drop-down menu, and then select the desired property from the menu that appears.
3. (Optional) Select Mandatory to include the input in the Cmdlet. If this option is unchecked, the input will be omitted from the command line.
4. Select Create Input Parameter to return to the Cmdlet Input Parameters workspace.
  
  This opens the Cmdlet Input Parameters workspace with the PowerShell Cmdlet Input property appearing in the Input Parameters list:

PowerShell Cmdlet Output Properties

Use the PowerShell Cmdlet Output Properties to define and map the Output properties to return as the output properties for the returned PowerShell object after execution.

PowerShell Cmdet Output Parameter Best Practices

Use the following best practices when setting the PowerShell Cmdlet Output parameters:

Use any name for the Property Name. This is the name of the property that PowerShell returns.
The Property Binding differs depending on which of the following options return:
- If an object returns, you must use the Property Binding as the property name for the class.
- If a primitive returns, you must select the appropriate binding property that corresponds with the respective property on the workflow End node. For example, the PowerShell Cmdlet returns the text output from the workflow using the End.ResultText property. This is a property called Output with the Property Binding set to ResultText.

PowerShell Cmdlet Output Property Options

When setting the Cmdlet Output Property options, you have the following output property options:

Primitive Type: Use a primitive type when a standard primitive (such as String, Integer, Boolean, etc.) returns.
Object Type: Use an object type when an object returns. When enabling this object, you must specify the class for the returned object.

Choose the PowerShell Cmdlet Output Properties

Navigate to Tool Foundry > PowerShell Cmdlets the left navigation menu on the Adaptiva OneSite Admin Portal, and then scroll down to the Cmdlet Output Parameters section.
Select the Property Type dropdown menu, and then select property type from the menu that appears.
Enter the Property Name on the Property Name line.
Select the Property Binding dropdown menu, and then select the desired binding from the menu that appears.

Save the PowerShell Cmdlet

Select Save on the upper-left corner of the PowerShell Cmdlet workspace to return to the PowerShell Cmdlets workspace:
1. Check the Error View and resolve any errors.
2. Select Save again if you make any changes.
The PowerShell Cmdlet appears in the PowerShell Cmdlets list.

Related to