Scripting Guide

Introduction

The Edge DX scripting engine is a powerful and infinitely extensible way to distribute and run scripts on Windows, Linux and Mac devices to perform IT administration tasks and to collect results and data.

For general Edge DX features and capabilities, see Welcome to Edge DX.

To see the scripts in your environment and to add new scripts, go to Configuration > Scripts.

Click on a script to see all of it's settings. The settings here determine how the Script is used in Edge DX, and the actual content of the script itself. See Script Configuration Options below for a description of all of the settings.

Script Configuration Options

The table below describes all of the script configuration options.

Existing Scripts Available in your Tenant

In the Configuration menu, click Scripts to access the Scripts page, where you can see a list of existing scripts available in your tenant.

On the Scripts page, you can filter the existing scripts by Name, Description and/ or Trigger.

Click on an individual script to drill down and see the script identification and configuration details. See Script Details for additional information about the script identification and configuration fields.

Revise an Existing Script

To revise an existing script, input the changes you want to make to the script in the relevant script identification and configuration fields, and then click Update Script.

Create a New Script based on an Existing Script

To create a new script based on an existing script, input changes to the existing script , and then click Save to New Script.

Create a New Script from a Blank Template

To create a new script from a blank template, click Add Script on the Scripts page. A blank script template opens.

Input identification and configuration details for the new script and then click Create Script to create the script.

See Script Details for additional information about the script identification and configuration fields in the script template.

Data Collection

Data Collection includes an option for selecting Sends Data, and if Sends Data is selected, Overwrite Existing Data and a Data Index can be selected.

If the Sends Data option is selected and the script completes before the timeout with no errors (empty stderr), then the stdout is inspected for a section having the format:

### SIP DATA BEGINS ###
[{"ip_address":"192.168.137.16","hostname":"test test.jar.local"}]
### SIP DATA ENDS ###

The data between the “### SIP DATA BEGINS/ENDS ###” lines is a JSON-formatted array of dictionaries that contains rows for the selected index. Examples of how to create this output with PowerShell, Python and other script languages are included in the scripts in your tenant. Any errors in the format are rejected by the Edge DX Agent and the reason is captured in System Events.

When the Edge DX Agent finds output that matches this pattern, it is sent to the Edge DX service for the specified Data Index, where it can be inspected with the Data view, or in a report if one exists.

When adding data to a custom index, we strongly recommend using only integer and not floating-point values. For example: It is better to store milliseconds as 375ms, than as 0.375 seconds. This avoids issues which can occur with data that spans multiple time periods.

The Overwrite Existing Data setting determines whether the data output appends new rows or overwrites existing data for that device. Select Overwrite Existing Data for Reports that show only the most recent status of the device. Do not select Overwrite Existing Data for Reports that keep a historical log of device activity.

Whether or not the Sends Data option is selected, the stdout from the script is also inspected for a section having the format:

### SIP EVENT BEGINS ###
Memory block size: 134217728 Total online memory: 8589934592 Total offline memory: 0
### SIP EVENT ENDS ###

If the stdout from the script contains a section in the above format, then a System Event is created with the script Name as the System Event Title and the System Event Description containing the output.

Additional Options

Additional Options includes a Run Only When Online option and a Run Only When Idle option.

Run Only when Online

The configuration of this setting determines whether the script runs when the end-user device is offline, i.e., it is not able to connect to the Edge DX service.

Several aspects of the Run Only When Online setting are explained by the three scenarios presented in the table below:

Run Only when Idle

The configuration of this setting determines whether the script runs when the end-user is idle.

If a script is triggered to run when the option Run Only When Idle is selected and the device is not idle, then the script does not start. This option is useful for scripts that consume a lot of system resources and could adversely impact user experience while running. You can set the CPU level and duration thresholds for determining idle status in Agent Settings.

Targeting and Distribution

Scripts are distributed to end-user devices on the basis of their platforms. Windows scripts are distributed to all Windows devices, Linux scripts are distributed to all Linux devices, and Mac scripts are distributed to all Mac devices.

When script settings are changed, they are updated and securely cached on each device when it next does a configuration update, as determined by the Configuration Update Interval in Agent Settings. At that time, any new or changed scripts are downloaded by the device and cached locally in a secured folder. Any old or unrecognized files in that folder are removed.

Script Triggers

A script can be set to run as a result of a trigger by specifying one of the triggers listed in the Trigger menu in the Trigger field of the script template:

There are three types of script triggers:

1. Time Based
2. Device Event
3. Custom Action

Time-Based Triggers

When a script has a time-based trigger, the script is triggered to run regularly at intervals. The interval is configured as detailed in the table below:

Device Event Triggers

When a script has a Device Event trigger, the script is triggered to run when a particular device event occurs, as detailed in the table below:

Device Event Triggers for Windows Devices Only

Device Event triggers for Windows end-user devices only are listed and described in the table below:

Device Event Trigger type (for Windows Devices Only)	Trigger Details
Process Started	A script with a Process Started trigger runs when a designated process starts. Designate the process in the Process Name field which opens when you select the Process Started trigger from the Trigger menu. The format for the Process Name is application.exe, e.g. notepad.exe. Note that some applications relaunch themselves, causing two Process Started triggers to occur close together when an application is started. The Process Started trigger can run the script in a System or User context (see Run Context). The Process Started trigger adds the SID and LogonID of the user that started the process as parameters on the command line so they can be used by the script.
Logon Complete	The Logon Complete trigger fires 15-20 seconds after userinit.exe exits, which occurs at the end of the Windows logon process. The Logon Complete trigger can run the script in a System or User context (see Run Context). The Logon Complete trigger adds the SID and LogonID of the user that started the process as parameters on the command line so they can be used by the script.
Logon - New Session	The Logon - New Session trigger fires first in the logon process, immediately after the session is created. It is possible that the script runs before the Windows environment is fully established. Only the SID is available to scripts.
Logon - Explorer Started	The Logon - Explorer Started trigger fires as soon as explorer.exe is started during the Windows logon process. The script can be run as System or as User. This trigger adds the SID and LogonID of the user that started the process as parameters on the command line so they can be used by the script.
Logoff	The Logoff trigger fires right before the user logs off and there are approximately 4 seconds for the script to complete before the session closes. The script can only be run as System because once the logoff has begun, no new processes including scripts can be started in the session. Includes both SID and LogonID.
Session Lock - Explorer Started	The Session Lock - Explorer Started trigger fires when the session display is locked. Includes both SID and LogonID.
Session Unlock - Explorer Started	The Session Unlock - Explorer Started trigger fires when the session display is unlocked. Includes both SID and LogonID.
Session Disconnect - Explorer Started	The Session Disconnect - Explorer Started trigger fires when a session is disconnected (except at logoff). Includes both SID and LogonID.
Session Reconnect - Explorer Started	The Session Reconnect - Explorer Started trigger fires when an existing session is reconnected. Includes both SID and LogonID.

Custom Actions

You can use Custom Actions to trigger scripts. Access Custom Actions by clicking Actions in the Devices section of the Edge DX User Interface.

To run a script based on a Custom Action:

1. In the Devices section of the Edge DX User Interface, click a device to drill down and see additional device data.
2. Click Actions. The Actions menu opens.

3. Select a Custom Action from the Actions menu. Clicking on a Custom Action in the Actions menu sends a request to the Device Action queue to run the script. The Edge DX Agent runs these scripts immediately when it receives them.
   Custom Actions can also be triggered by Alerts. (See Alerts)

Run Context

Scripts run in the context of the System , except on Windows where some triggers have the option of running as User .

System context means NT AUTHORITY\SYSTEM (i.e. LocalSystem) on Windows, and sudo (i.e. root) on Linux and Mac. On Windows the User SID and LogonID are provided as command line parameters on some triggers, so that scripts that run as System can still carry out operations on specific user data. The User SID is provided in SDDL format (for example: “S-1-5-21-368573210-3773030013-3569538123-1001”). Logon ID is a 64-bit hex string (for example: “0x00092c61”). See the Tips and Tricks section for information on how to use these.

On Windows the User context means the user who performed the action, for example, the user that started the process or logged on to the desktop. User scripts are copied to a temporary (secured) location, the user is given permissions to execute them, and then they are deleted when complete.

Scripts - Tips and Tricks

Targeting a Script at a Specific Device

To ensure a script only runs on certain devices, you can add a line at the start of the script, for example, in PowerShell:

if ($env:COMPUTERNAME -ne "DESKTOP-BVD8EN4") { return; }

You can also filter by Edge DX device group with the SIPDEVICEGROUP environment variable.

Display a Dialog to a User (Windows)

Use the UserPrompt.exe executable included with the SIP Agent on Windows to display a dialog to the user. Note that UserPrompt.exe must be run in the User context (the Trigger field in the script editor window must be set to Custom Action - User or one of the User Triggers).

Example for cmd.exe Script

Use a line like the example shown below for a cmd.exe script. Note the start /b at the beginning means that the script immediately returns after launching UserPrompt.exe, and so you will not get timeout errors if the user does not acknowledge the dialog for a long time. However, you will still get an error if the command line fails.

start /b "" "C:\program files\Avacee\sip_agent\UserPrompt.exe" "Hello world!"

Example for PowerShell

The following example is for PowerShell:

Start-Process (“C:\program files\Avacee\sip_agent\UserPrompt.exe") -ArgumentList """Hello world!"""

Creating JSON Formatted Output

If you want to send data that can be viewed in a report then you need to format it as data. On Windows this is easily done in PowerShell using a Hashtable (which is very much like a Dictionary):

$MyData = @{} # initialize a hashtable

$MyData["field_1"] = 20
$MyData["field_2"] = 100

Write-Output("### SIP DATA BEGINS ###")
Write-Output(ConvertTo-Json $MyData -Compress)
Write-Output("### SIP DATA ENDS ###")

Every time this script runs it will send a row for that device with two fields and a value for each, which appear as columns in the table report.

If you want to send multiple rows from each device in a single data upload, you can use a .NET List collection like this:

$MyDataList = New-Object 'System.Collections.Generic.List[psobject]'

foreach ($i in $MyDataCollection)
{
$MyData = @{} # initialize a hashtable

$MyData["field_1"] = 20
$MyData["field_2"] = $i.Property

$MyDataList.Add($MyData)

}

Write-Output("### SIP DATA BEGINS ###")
Write-Output(ConvertTo-Json $MyDataList -Compress)
Write-Output("### SIP DATA ENDS ###")

This will iterate through $MyDataCollection adding a Hashtable to the List for each entry, which will appear as rows for each device in the report table.

Choosing cmd.exe or VBScript over PowerShell

PowerShell is very powerful, but it consumes far more resources than cmd.exe and can be slow when iterating through large amounts of data, especially with complete Where-Object queries. Whenever possible, use cmd.exe or VBScript.

Sending data to the Events Log using cmd.exe is very simple. For example:

@echo off
echo ### SIP EVENT BEGINS ###
ping www.google.com
echo ### SIP EVENT ENDS ###

Using the User SID and Logon ID Parameters in Scripts

In the example shown below, a PowerShell script running as System in response to a User Event (e.g. a Logon) can look in the User’s HKEY_CURRENT_USER registry hive by opening a path under HKEY_USERS using the User SID, which was passed to the script as the first parameter:

param ( $UserSID, $LogonID ) # this needs to be the first line

$hku = [Microsoft.Win32.RegistryKey]::OpenBaseKey([Microsoft.Win32.RegistryHive]::Users, 0)
$hkcuRunKey = $hku.OpenSubKey(($UserSID + '\SOFTWARE\Microsoft\Windows\CurrentVersion\Run'), $false)

Avoiding Unicode Problems in Script Data Output

Add the line shown below to PowerShell scripts so that all text output is passed and uploaded to the database using Unicode, which allows all international characters and can be searched with all international characters:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Without this line, PowerShell will sometimes try and convert international characters to their closest ASCII equivalent, which can cause havoc with data formatting.

Script Use Case

The following is a step-by-step guide to creating a script to get the CPU temperature from Microsoft Windows machines, using a PowerShell script, and then displaying the output data in a custom report:

1. In Edge DX click Configuration > Scripts > Add Script
2. Complete the script fields as follows:

The Data Index field defines a new location or table for the data to be pushed into. Once created, the Data Index can be found under Configuration > Data:

3. When you complete the script fields, click Create Script orSave to New Script /Update Script.

To create a custom report showing CPU temperature for your devices:

1. Go to Configuration > Data.

2. Under Index, click on cpu_temperature (that you created previously) and then click Create Custom Report.
   

3. Give the report a name and description and check Public if you want the report to be viewed by everyone in your organization. Click Create.

4. Refresh the page and go to Reports. You will find the report you created under the Custom Reports heading. Click it.
   

5. You can give the columns in your report more reader friendly names by clicking Rename Columns. In this example, columns are changed to Temperature and Device Name.
   

6. When you are done, click Save Report Layout.
   

To learn how to get alerts about a temperature report and other alert types, see Edge DX Alerts.