PowerShell - Run script

Declaration

<AMPSHELL PASSWORD="text (encrypted)" USERNAME="text" DOMAIN="text" URI="text" AUTHTYPE="text (options)" ERRORDATASET="text (dataset name)" RESULTDATASET="text (dataset name)" SCRIPT="text" />

Description

Runs an embedded or external Windows PowerShell script locally or on a remote computer. This activity includes an interactive PowerShell editor used for developing, examining and debugging PowerShell scripts.

NOTE: This activity requires basic knowledge of Windows PowerShell scripting language.

Practical usage

Commonly used by IT professionals and power users to control and automate the administration of the Windows operating system and applications that run on Windows.

Parameters

Script

Property Type Required Default Markup Description
Embedded Text No (Empty) SCRIPT="embedded script" If selected, specifies the PowerShell script to run is embedded in the task (selected by default). Enter the script in the provided text box or click the Edit Script button to access the script editor and integrated debugger (an interactive design environment used for developing, examining, and testing PowerShell scripts). If this parameter is selected, the External parameter becomes disabled.
External Text No (Empty) FILE="c:\temp\scriptName.ps1 If selected, specifies the script is located in an external (.ps1) file (disabled by default). Click the Folder icon to navigate to the desired external .ps1 file or manually enter the full path and file name of the file in the provided text box. If this parameter is enabled, the Embedded parameter becomes disabled.

Output

Property Type Required Default Markup Description
Create and populate dataset with Text No (Empty)
  • RESULTDATASET="theResult"
  • ERRORDATASET="theError"
 Specifies the names of the datasets to create and populate with results and errors. The parameters are:
  • Results - The name of the dataset to create and populate with script execution results.
  • Errors - The name of the dataset to create and populate with script execution error messages (if any).

For more information, see Datasets.

Computer

Property Type Required Default Markup Description
Local computer --- --- --- --- If selected, specifies the PowerShell script runs on the local computer (selected by default). If this parameter is enabled, the Another computer parameter becomes disabled.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Another computer --- --- --- --- If enabled, specifies the PowerShell script runs on another computer (disabled by default). If this parameter is selected, the Local computer parameter becomes disabled and a number of other parameters become active (as described below).
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Uniform resource identifier Text Yes, if Another computer is selected (Empty) URI="https://host_pc:5986/ The Uniform Resource Identifier (URI) of the remote computer. URI is a compact string of characters for identifying an abstract or physical resource (for example, https://hostComputer:5986/). This parameter is required if the Another computer parameter is selected.
Username Text Yes, if Another computer is selected (Empty) USERNAME="computerUser A valid username used to log onto the remote computer. This parameter becomes active if the Another computer parameter is selected.
Domain Text Yes, if Another computer is selected (Empty) DOMAIN="netauto" The domain name of the remote computer. This parameter becomes active if the Another computer parameter is selected.
Password Text Yes, if Another computer is selected (Empty) PASSWORD="encrypted" A valid password used to log onto the remote machine. This parameter is required if the Another computer parameter is selected.
Authentication Text (options) Yes, if Another computer is selected Default
  • AUTHTYPE="default"
  • AUTHTYPE="basic"
  • AUTHTYPE="negotiate"
  • AUTHTYPE="digest"
  • AUTHTYPE="kerberos"
  • AUTHTYPE="credssp"
 The type of authentication required for remote connection (if any). This parameter is active only if the Another computer parameter is enabled. The available options are:
  • Default - Default authentication
  • Basic - Uses a username and password to authenticate a service client to a secure endpoint.
  • Negotiate - Also known as Integrated Windows Authentication, uses the security features of Windows clients and servers.
  • Digest - Authentication scheme based on cryptographic hashes.
  • Kerberos - Works on the basis of tickets to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner.
  • CredSSP - Enables an application to securely delegate a user's credentials from a client to a target server.

Description

Error Causes

On Error

Additional notes

Datasets

A dataset is a multiple column, multiple row container object where every column represents a particular variable, and each row corresponds to a given member of the dataset in question. This activity creates and populates a dataset containing a specific set of fields.

NOTE: Dataset fields for this activity vary, based on your PowerShell script.

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description

This sample tasks runs the Get-Service Cmdlet (designed to retrieve information about the services installed on the system) and populate a dataset with results. The dataset is looped, and during each iteration a message dialog displays information about the current service:

  • Service Name - %serviceInfo.ServiceName%
  • Service Display Name - %serviceInfo.DisplayName%
  • Service Type - %serviceInfo.ServiceType%
  • Service Status - %serviceInfo.Status%
Copy 
<AMPOWERSHELL RESULTDATASET="serviceInfo" SCRIPT="Get-Service" />
<AMLOOP ACTIVITY="dataset" DATASET="serviceInfo" />
<AMSHOWDIALOG WINDOWTITLE="SERVICE INFORMATION" BUTTONS="ok_cancel" ONSECONDBUTTONCLICK="stop">Service Name - %serviceInfo.ServiceName%Service Display Name - %serviceInfo.DisplayName%Service Type - %serviceInfo.ServiceType%Service Status - %serviceInfo.Status%</AMSHOWDIALOG>
<AMLOOP ACTIVITY="end" />