Edge DX Scripting Guide
  • Dark
    Light
  • PDF

Edge DX Scripting Guide

  • Dark
    Light
  • PDF

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.

Note

The terms SIP and SIP Agent in the UI, scripts and script logs refer to Edge DX.

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.

image.png

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

image.png

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.

image.png

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.

image.png

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.

image.png

Script Details

To view the identification and configuration details of a script that exists and is available in your tenant:

  1. Click Scripts in the Configuration menu.
  2. Click on a script. The script template opens, with the identification and configuration details of the script appearing in the template fields.

To access a blank template for providing identification and configuration details for a new script:

  1. Click Scripts in the Configuration menu.
  2. Click Add Script. A new script template opens, with the identification and configuration fields blank.

See the table below for details about the script identification and configuration fields in the script template:

Script Field Script Field Basic Details Script Field Additional Details
Name A friendly name which identifies the script in the following views: Configuration > Scripts, Configuration > System Events, and Devices > Device Events. When the script is cached as a file on the device (in a secured folder), the friendly name is not used, and a random sequence of characters is used as the file name. Most events list both the friendly name and the random file name to ease understanding of which script produced the event.
Description A description of what the script does and how to use it.
Content The content of the script itself. Use a script editor to develop, test and run your script before copying it and pasting it in the Content field for distribution to end-user devices. Note that scripts often run in System context (see Run Context ) and so might behave differently when they are run by an end-user from when they are run in a script editor.
Platform Platform (Windows, macOS, or Linux) to which the script belongs. The script is distributed to end-user devices which run on the same platform. Selection options for the Language / Interpreter and Trigger fields is dependent upon the selected Platform.
Language / Interpreter The language / interpreter of the script. The options available for selection in the Language / Interpreter field depend on the selected Platform. The script is saved as a local file in a secured folder, and then passed to the selected interpreter on a command line and run in a separate process.
Trigger The trigger which causes the script to run. Selection options for the Trigger field is dependent upon the selected Platform. See Script Triggers for more details.
Timeout An amount of time in seconds allowed for the process which runs the script to execute, before it is timed out. If the script completes within the designated time, before timeout, then stdout (standard output) and stderr (standard error) results are checked. If there are no errors, the stdout text is scanned for data and event results (see below link). If the process which runs the script does not complete before timeout, and hangs, it is killed. If timeout is set to zero seconds, then the script is started in a fire-and-forget manner and is not killed if it hangs, no stdout or stderr results are collected, and no data is sent to the Edge DX service.
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. See Data Collection below for additional details on this field.
Additional Options Additional Options includes a Run Only When Online option and a Run Only When Idle option. See Additional Options below for additional details on this field.

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.

360020280497edgeconfigscriptsdatacollection.png

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.

Note

If the Data Index does not already exist, a new one is dynamically created.

360020388398edgedatacreatecustomreport.png

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.

360020389898edgeconfigsystemevents.png

Additional Options

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

360020282937edgeconfigscriptsadditionaloptions.png

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:

Scenario 1 Scenario 2 Scenario 3
Run Only When Online selection status Run Only When Online is selected Run Only When Online is not selected Run Only When Online is either selected or not selected
Connection status of end-user device to Edge DX service End-user device is offline End-user device is offline End-user device is connected (online)
Additional Condition - The Sends Data option in Data Collection is selected A Custom Action triggers a script.
Outcome when a script is triggered The script does not run The script runs when the device is offline and the data output is cached on the client until the device comes back online. A Custom Action can only run when the device is online and able to receive actions, so the Run Only When Online setting does not apply to scripts triggered by Custom Actions

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:

image.png

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:

Time-Based Trigger type Details
Short Interval A script with a Short Interval trigger runs at short intervals, for example, every 180 seconds (3 minutes). The interval is specified in Configuration > Settings > Agent > Short Trigger Interval (seconds)
Long Interval A script with a Long Interval trigger runs at long intervals, for example, every 600 seconds (10 minutes). The interval is specified in Configuration > Settings > Agent > Long Trigger Interval (seconds)
Once Per Day Every 15 minutes (by default) the Edge dX Agent checks each Once Per Day designated script to check if the script has run in the last 24 hours. If the script has not run in the last 24 hours, the Agent runs it. The Agent retries to run the script every 15 minutes until there are no errors, and then stores the last run time. If the script is set to Run Only When Online, the Agent will retry running the script every 15 minutes until the end-user device is online, and then the script will not run again for 24 hours.

image.png

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 Trigger type Trigger Details
SIP Service Start A script with an SIP Service Start trigger runs whenever the service SIP Agent starts, or restarts. The service automatically starts when the Operating System is booted. It runs as soon as the agent starts, using scripts cached previously. It does not attempt to download or update scripts first.
SIP Service Stop A script with an SIP Service Stop trigger runs whenever the Agent stops, which occurs when it is upgraded, the device is shut down or rebooted, or when it is manually stopped. Devices have up to 5 seconds to send data or events to the Edge DX service before the agent exits. Any script process still running continues, but output from the script is lost after 5 seconds.
Network Change A script with a Network Change trigger runs whenever the network interface changes, which can happen due to power events, network outages, changes of the WiFi Access Point, move from LAN to WLAN, etc. Often there are multiple network change events close together, and so the SIP Agent waits for a second to ensure that only the last network change event triggers the script.

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.
image.png
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 image.png 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.

image.png

  1. 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)
Note

The Action Check interval can be changed in Agent Settings.

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.

Popping a Dialog to a User (Windows)

The UserPrompt.exe executable included with the SIP Agent on Windows can be used to display a dialog to the user.

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 Script4402381652497Edgedxscriptcreatescript1.png
  2. Complete the script fields as follows:
Script Template Field Input
Name Get CPU Data
Description (optional)
Platform Microsoft Windows
Language / Interpreter PowerShell
Trigger Short Interval Timer
Timeout (s) 60
Data Collection: Sends Data Enabled
Overwrite Existing Data Enabled
Data Index cpu_temperature
Content Since the script is going to gather data, include Write-Output.

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:
4402381678993Edgedxscriptsconfigurationdatacputemp2.png
3. When you complete the script fields, click Create Script orSave to New Script /Update Script.
4402374311441Edgedxscriptcreatescriptsavetonewscriptupdatescript7.png

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.
    4402383451153Edgedxsettingsdatacputempcreatecustomreport3.png

  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.
    4402381959441Edgedxreportscustomreportscputemp4.png

  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.
    4402381982737Edgedxreportscustomerreportstemperaturereportjohnrenamecolumns5.png

  6. When you are done, click Save Report Layout.
    4402382003473Edgedxreportscustomerreportstemperaturereportjohnrenamecolumnssavereportlayout6.png

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


Was this article helpful?