Custom Conditions

In this section:

About Custom Conditions

Use the Custom condition to create, import and export conditions using PowerShell, Visual Basic or Java Script. Custom conditions can be used to cater for scenarios which are not available as standard from the Environment Manager console. For example, to check if the Windows Firewall is switched on.

The scripts are held within the AEMP configuration, copied to disk at runtime, executed and then deleted upon completion. Scripts can be imported and exported to enable reuse.

Large scripts and high numbers of scripts increase the size of an AEMP configuration which can impact the time required to deploy configurations to end points and affect configuration execution time.
It is recommended that custom conditions using PowerShell scripts should not be used on the Logon trigger as running these scripts can cause slow logon times.

As Custom condition scripts are run in batch mode, any prompts or message boxes are not displayed and the script times-out without being executed. To ensure that a condition script runs correctly, remove or comment out any prompts or message boxes from the script.

Custom Working Directory

Environment Manager executes Custom condition scripts from the system or user temporary directory (%TEMP%). You can choose a custom working directory from which to execute the scripts. When multiple script conditions are executed in a custom directory, the directory will be removed after the final script completes execution. Pre-existing directories will not be removed.

To create the custom working directory:

  1. From the Custom Condition dialog, choose the Custom tab.

  2. In the Working Directory field, enter the name of the working directory to use for script execution.

    To keep an environment variable from expanding, replace % with %%. To reference a session variable, enter $(SessionVariableName).

    If this directory does not exist, it automatically will be created and removed after the script completes execution.

Custom conditions can be applied to both computer and user triggers.

Exit Codes

All custom scripts must specify an exit code which when returned, is used by the Environment Manager agent to determine whether the script has passed or failed. For scripts without an exit code a success (0 value) is assumed by the agent. Each script type must use a specific exit statement.

Language Exit Statement
VBScript WScript.Quit [value]
JScript WScript.Quit([value])
PowerShell exit ([value])

Replace [value] with the exit code for the script: 0 for success and 1 for failure. For example: WScript.Quit 0, WScript.Quit(0), exit (0).

PowerShell Scripts

Windows PowerShell scripts use various execution policies which can prevent the scripts from running or only allow those signed by trusted publishers to run. Environment Manager overrides execution policies and bypasses any restrictions to enable the PowerShell scripts to run.

Execution polices for users and computers can also be set through Group Policy which override all PowerShell execution policies. A user policy which does not allow any scripts, or only those which are signed, will not affect the running of PowerShell Custom conditions if they are run as System. However, if run as the current user the user policy will not allow the scripts and the Custom condition will fail. A computer policy which does not allow any scripts, or only those which are signed, will not allow the running of any PowerShell Custom conditions.

Therefore, to successfully run Custom conditions which use PowerShell, your Group Policy must be set to allow these scripts to run for users and computers.

Environment Manager is compatible with PowerShell versions 1.0, 2.0 and 3.0.

Create a Custom Condition

  1. In the Policy Configuration navigation tree, select the node or trigger to which you want to add the condition. This can be:
    • A new node
    • An existing node
    • The Environment tab of a trigger
  2. In the Conditions ribbon, select Custom to display the Custom Condition dialog.
  3. Select the Type of scripting; PowerShell, VBScript or JScript.

  4. Set the Time allowed to run. This is the number of seconds after which the script is terminated. Setting the value to zero or leaving the field blank gives the script infinite time to complete.

    Custom conditions override default node and condition timeouts.

  5. Click the Options drop-down and configure the following options as required:
    • Evaluate Once Per Session - Select this option to run the condition once and cache the result for the duration of the session. Otherwise the condition is evaluated each time it is called upon within a configuration.
    • Run As System User - Select this option to enable the script to use functionality which would not otherwise be accessible to the currently logged on user. For user triggers, if this option is not selected, the script runs in the context of the logged on user.
  6. Enter the script using one of the following methods:
    • Type directly into the field
    • Drag and drop or copy and paste from another location.

    • Click the import button and select a file to open and use in the script field.

    Session Variables can be added to the script from the Insert menu. The drop-down contains any user-defined Session Variables and the following inbuilt variables:

    • SessionID - The current Session ID
    • UserSID - The user’s Security Identifier
    • UserTemp - The location of user’s Temporary Directory
  7. On the Network Available, Network Connected and Network Disconnected triggers, further built-in Session Variables can be added to the script to determine connection attributes. These built-in Session Variables cannot be amended or deleted.
  8. Click OK to save the script.

When triggered, the script runs to its completion and the resulting success or failure of the condition is detailed in the debug log files.

Custom scripts which timeout are classed as failing and any child nodes and their associated actions will not run.

Export Custom Scripts

Scripts can be exported and saved from the Custom Action dialog and imported into other conditions and configurations.

  1. Open a Custom condition.
  2. Click the export button Export Custom Condition Button and select a location to save the PowerShell, VBS or JS file.
  3. Click Save to complete the export.

Related Topics

Condition Management