Scripting Guide
    • Dark
      Light
    • PDF

    Scripting Guide

    • Dark
      Light
    • PDF

    Article Summary

    Use Edge DX's scripting engine to distribute and run scripts on devices in your environment. Use scripts to perform IT administration tasks, collect data from devices, and more. To view your scripts, go to Configuration > Scripts.

    View scripts.png

    Note

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

    Script permissions

    To view the scripts in your environment, you need the permission View Scripts.

    To make changes to the scripts in your environment, you need the permission View, Create, Edit and Delete Scripts. You should grant this permission only to senior administrators. With great power comes great responsibility.

    Control who can run scripts and on which devices

    You might not want to allow a junior helpdesk employee to run all of the same scripts that a senior administrator can run. You can give a user permission to only run scripts belonging to a specific permission group. For example, you can add low-risk scripts to Permission Group 1 and give your junior helpdesk employees the permission Run Group 1 Scripts.

    NewDexPermissions1.png

    Additionally, you might not want to allow a helpdesk employee to run scripts on devices that they are not responsible for managing. You can give a user permission to run scripts only on specific devices by targeting device groups and tags. Learn how to configure permissions in on the DEX platform.

    NewDexPermissions2.png

    Requires ControlUp DEX Platform

    To limit a user's permission to run scripts only to specific devices, you must be upgraded to ControlUp's DEX platform (accessed from app.controlup.com). If you use Edge DX from solve.controlup.com or by direct tenant URL (tenant-name.sip.controlup.com), upgrade your organization to the new DEX platform.

    Add a script

    To add a new script from a blank template:

    1. Click Add Script.
      Add new script.png

    2. Fill out the script's parameters.

    3. Click Create Script
      save new script.png

    To add a new script using an existing script as a template:

    1. Click on the script name that you want to use as a template to open the script editor.
      create from template1.png

    2. Make your changes to the script's parameters.

    3. Click Save to New Script. The edited script is saved and the original script used as a template is not changed.
      create from template2.png

    Add scripts from the Script Library

    The Script Library is a collection of useful scripts compiled by ControlUp. Learn how to import scripts from the Script Library.

    Script parameters

    The following table describes how to use all of the script parameters. Some parameters are explained in more detail later in the article.

    Parameter nameDescription
    NameEnter a name for the script.

    Note that when the script is cached as a file on the device (in a secured folder), a random sequence of characters is used as the file name. Most events list both the script name and the random file name to help understand which script produced the event.
    DescriptionDescribe what the script does and how to use it.
    ContentThe content of the script itself.

    Use a script editor to develop and test 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.
    PlatformSelect the OS platform (Windows, macOS, or Linux) that the script runs on. The script can run only on the platform that you select.
    Language / InterpreterSelect the language / interpreter for the script. 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. The available options depend on the selected OS Platform.
    TriggerSet what causes the trigger to run. The available options depend on the selected OS Platform.

    Custom Action - User and Custom Action - System allows you to manually run the script on a device by performing a Custom Action in the user or system context. Custom Actions can also be set to run when an alert activates on a device. Note that you can customize the short and long interval timer durations in your Agent settings.
    Permission 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. See Script permissions for more details
    TimeoutAn amount of time in seconds allowed for the process that 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. If the process which runs the script does not complete before timeout and hangs, it is killed. If the 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. See Data Collection for more details.
    Enable ScriptSelect Script Enabled if you want the script to run when the script's trigger is met. Note that this option appears only if a Trigger is selected. See Enable and disable scripts for more details.
    Send EventsClick Add "Send Events" code block to your script to create an event with text from stdout and save it to the System Events log when the script runs.
    Additional OptionsOptionally, select whether you want to limit when the script can run. If you select Run Only When Online, the script will not run on a device if the device isn't actively connected to your Edge DX environment. If this option is not selected, the script can run on an offline device and save the data to a local cache until it reconnects to your environment. Note that this option doesn't affect scripts that are triggered by a Custom Action because a Custom Action can be performed only on online devices.

    If you select Run Only When Idle, the script can run on a device only if the device is idle. This is useful for scripts that consume a lot of resources and could negatively impact user experience when the script is running.

    Triggers

    Setting the script's trigger determines when the script runs. Select from:

    Custom Actions

    A script with a Custom Action trigger can be manually run on a device by performing an action on the device from Edge DX. Choose between Custom Action - User and Custom Action - System to determine whether the script executes in the user context or system context.

    run custom action on device.png

    A script with a Custom Action trigger can also be triggered by an alert activating on a device. Learn more about alerts.

    custom action alert.png

    Time-based triggers

    Select from the following script triggers to run the script at regular intervals:

    • Short/Long Interval Timer - Runs the script at the interval duration that you specify in Configuration > Settings > Agent > Trigger Intervals.
      trigger interval duration.png
    • Once Per Day - Every 15 minutes, the Agent checks if the script has run in the last 24 hours. If the script hasn't run, then the Agent runs the script 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 the script and stores the time the script was last run. If the script is set to Run Only When Online, the Agent tries to run the script every 15 minutes until the device is online, and then the script won't run again for 24 hours.

    Device event triggers

    Select from the following script triggers to run the script on a device after the specified event occurs on the device.

    Device Event Trigger typeTrigger Details
    SIP Service StartThe script runs whenever the service SIP agent service starts or restarts. The service automatically starts when the Operating System is booted. The script runs as soon as the agent starts, using scripts cached previously. It does not attempt to download or update scripts first.
    SIP Service StopThe script 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 ChangeThe script 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.
    Process Started (Windows only)The script 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 (Windows only)The script runs 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 (Windows only)The script runs 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 (Windows only)The script runs 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 (Windows only)The script runs 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 (Windows only)The script runs when the session display is locked.
    Includes both SID and LogonID.
    Session Unlock - Explorer Started (Windows only)The script runs when the session display is unlocked.
    Includes both SID and LogonID.
    Session Disconnect - Explorer Started (Windows only)The script runs when a session is disconnected (except at logoff).
    Includes both SID and LogonID.
    Session Reconnect - Explorer Started (Windows only)The script runs when an existing session is reconnected.
    Includes both SID and LogonID.

    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.

    view data indices.png

    Note

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

    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.

    system events log.png

    Enable and disable scripts

    A script can run only if it is Enabled. If you disable a script then it will not run even if the script's trigger condition is met, and the script won't be available to run as a Custom Action.

    To see which scripts are enabled, go to your scripts settings and look at the Enabled column:

    script enabled checkbox.png

    To enable or disable a script, click the Enabled checkboxes. You can also enable or disable a script by editing the script and selecting the Script Enabled checkbox.

    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 or Save 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?