Custom and Execute Actions

In this section:

Custom Action

Custom Actions can be created using PowerShell, Visual Basic or Java Script to allow processing not available from other Environment Manager actions. The scripts are held within the XML configuration, copied to disk at runtime, executed and then deleted upon completion.

Historically, Custom Actions were often created in order to specify required delays to actions. From 2020.3 release, Environment Manager introduced a Delay tab built in to the Actions dialogs negating the need for a custom action.

Actions with invalid scripts return a fail and any child actions do not run.

Separate auditing events are created for successful and unsuccessful actions, these can be viewed through the Auditing button in the Manage ribbon.

' ==========================================================

' Checks to see if a process (EMCoreService.exe) is running

' =========================================================

strComputer = "."

Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")

Set objShell = CreateObject("Wscript.Shell")

Set colProcesses = objWMIService.ExecQuery _

("Select * from Win32_Process Where Name = 'EMCoreService.exe'")

If colProcesses.Count =0 Then

 Wscript.Echo "There are no instances of EMCoreService.exe running"

 Wscript.Quit 0

Else

 Wscript.Echo "EMCoreService.exe is running"

 Wscript.Quit 1

End If

Separate auditing events are created for successful and unsuccessful actions. These can be viewed through the Auditing button in the Manage ribbon.

Select the type of script required; PowerShell, Visual Basic or Java Script and enter the script directly into the dialog. Scripts can also be added using copy and paste or imported using the import button.

The following settings can be applied which affect the behavior of the action:

  • Timeout - Set a timeout for the completion of the script. If the time set is reached the action will fail. There is no maximum value that can be set, however, the value 0 equates to infinite. Timeouts set in Custom Actions overwrite the default node settings.

    It is recommended that a specific timeout value is set for Custom Actions and Custom Conditions. Setting the timeout value to 0 (infinite) may result in a logon or logoff hang if the script fails to complete.

    See Configuring Nodes and Timeout Settings for further details.

  • Prevent script from running interactively - This option is selected by default and means that scripts will run without pop-ups that require user interaction.
  • Apply environment variables to configuration - With this option selected, any environment variable set in the script is also set in the registry and EM Client enabling it to be used outside of the script.
  • Insert - Select a Session Variable to add to the script. The list includes the following built-in variables:
    • SessionID - The current Session ID
    • UserSID - The user's Security Identifier
    • UserTemp - The location of user's Temporary Directory

In the Network Available, Network Connected and Network Disconnected triggers, further built-in Session Variables can be added to the script to determine connection attributes.

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:

  • 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 actions if they are run as System. However, if run as the current user the user policy will not allow the scripts and the Custom action 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 actions.

Therefore, to successfully run Custom actions 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.

Execute Action

These actions execute an application or process when triggered. Browse to the application from the Filename field. The Working Directory is automatically added when the application is selected. Additional Parameters can be added to pass to the program.

To enable the process to run using different user credentials, select the Run As tab and select the user as required.

If the Do not create window (Console based applications) checkbox is selected, any command windows associated with an application or process are hidden from the user.

Avoid including Execute actions at logon in nodes set to execute in sequence for files which require user interaction to complete, such as program files. Otherwise, the logon process is halted indefinitely as the logon script waits for the execute script to complete. For example, if the Execute action launches notepad.exe, the logon script waits for Notepad to end before proceeding with the logon process.

If the Do not execute children of this action until the process has exited option is unchecked this scenario will not be held up as user interaction is turned off.

Related Topics

Action Management