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" />

Related Topics   

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 enabled, specifies that the PowerShell script to run is embedded in the task (enabled 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 enabled, the External parameter becomes inactive.

External

Text

No

(Empty)

FILE="c:\temp\scriptName.ps1

If enabled, specifies that 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 filename of the file in the provided text-box. If this parameter is enabled, the Embedded parameter becomes inactive.

Output

Property

Type

Required

Default

Markup

Description

Create and populate dataset with results

Text

No

(Empty)

RESULTDATASET="theResult"

The name of the dataset to create and populate with script execution results.

Create and populate dataset with errors

Text

No

(Empty)

ERRORDATASET="theError"

The name of the dataset to create and populate with script execution error messages (if any).

Computer

Property

Type

Required

Default

Markup

Description

Local computer

---

---

---

---

If enabled, specifies that the PowerShell script will run on the local computer (enabled by default). This is a visual mode parameter only used during design time, therefore, contains no markup. If this parameter is enabled, the Another computer parameter becomes inactive.

Another computer

---

--- ---

---

If enabled, specifies that the PowerShell script will run on another computer (disabled by default). This is a visual mode parameter only used during design time, therefore, contains no markup. If this parameter is enabled, the Local computer parameter becomes inactive and a number of other parameters appear (as described below).

Uniform Resource Identifier

Text

Yes if Another computer parameter is enabled

(Empty)

URI="https://host_pc:5986/wsman"

The Uniform Resource Identifier (URI) of the remote computer. URI is a compact string of characters for identifying an abstract or physical resource (i.e. https://hostComputer:5986/wsman). This parameter is active only if the Another computer parameter is enabled.

Username

Text

Yes if Another computer parameter is enabled

(Empty)

USERNAME="computerUser"

A valid username used to log onto the remote computer. This parameter is active only if the Another computer parameter is enabled.

Domain

Text

Yes if Another computer parameter is enabled

(Empty)

DOMAIN="netauto"

The domain name of the remote computer. In Windows 2000, WinXP and Server2003, if a domain name is specified, it is automatically appended to the username and separated with an @ symbol (i.e. username@domain.com). This parameter is active only if the Another computer parameter is enabled.

Password

Text

Yes if Another computer parameter is enabled

(Empty)

PASSWORD="encrypted"

A valid password used to log onto the remote machine. This parameter is active only if the Another computer parameter is enabled.

Authentication

Text (options)

Yes if Another computer parameter is enabled

Default

  1. AUTHTYPE="default"

  2. AUTHTYPE="basic"

  3. AUTHTYPE="negotiate"

  4. AUTHTYPE="digest"

  5. AUTHTYPE="kerberos"

  6. 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

Example

NOTE: The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Description

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%

<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>