Scripting Guide
    • Dark
      Light
    • PDF

    Scripting Guide

    • Dark
      Light
    • PDF

    Article Summary

    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.

    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.

    Script FieldScript Field Basic DetailsScript Field Additional Details
    NameA 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.
    DescriptionA description of what the script does and how to use it.
    ContentThe 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.
    PlatformPlatform (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 / InterpreterThe 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.
    TriggerWhat causes the script to run.The available options for the Trigger depend on the selected Platform. See Script Triggers for more details.
    GroupSets the permission group for the script. A user is allowed to run the script as a custom action only if they have permission to run scripts in the relevant group.You can select from 5 permission groups or select Ungrouped. Permissions to run scripts from each script group (including ungrouped scripts) are located under Device Actions in your Roles settings.

    For example, if the Group is set to Group 1, only users with the Run group 1 scripts permission are allowed to run the script.
    TimeoutAn 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 CollectionData 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 OptionsAdditional 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.

    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.

    20220329_EdgeDX Scripts - Congfig - Scripts.png

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

    20220330_EdgeDX Scripts - Filter - Scripts.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

    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 1Scenario 2Scenario 3
    Run Only When Online selection statusRun Only When Online is selectedRun Only When Online is not selectedRun Only When Online is either selected or not selected
    Connection status of end-user device to Edge DX serviceEnd-user device is offlineEnd-user device is offlineEnd-user device is connected (online)
    Additional Condition-The Sends Data option in Data Collection is selectedA Custom Action triggers a script.
    Outcome when a script is triggeredThe script does not runThe 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 typeDetails
    Short IntervalA 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 IntervalA 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 DayEvery 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 typeTrigger Details
    SIP Service StartA 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 StopA 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 ChangeA 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 StartedA 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 CompleteThe 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 SessionThe 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 StartedThe 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.
    LogoffThe 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 StartedThe Session Lock - Explorer Started trigger fires when the session display is locked.
    Includes both SID and LogonID.
    Session Unlock - Explorer StartedThe Session Unlock - Explorer Started trigger fires when the session display is unlocked.
    Includes both SID and LogonID.
    Session Disconnect - Explorer StartedThe Session Disconnect - Explorer Started trigger fires when a session is disconnected (except at logoff).
    Includes both SID and LogonID.
    Session Reconnect - Explorer StartedThe 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.

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

    UserPrompt example

    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 FieldInput
    NameGet CPU Data
    Description(optional)
    PlatformMicrosoft Windows
    Language / InterpreterPowerShell
    TriggerShort Interval Timer
    Timeout (s)60
    Data Collection: Sends DataEnabled
    Overwrite Existing DataEnabled
    Data Indexcpu_temperature
    ContentSince 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?

    What's Next