InSight Alert Scripts

InSight Alert Scipts let you (or your service representative) expand the existing types of InSight Alerts to include additional conditions that are specific to your needs. These new InSight Alerts can include any condition that can be identified using a script written in JavaScript. Once you have created and saved an InSight Alert script, the new script type is displayed on the InSight Alerts setup screen, along with the built-in types.

Support for InSight Alert Scripts is not available in all versions, and requires the Newer InSight Alerts setup screen. If you do not have support for this feature and want to add it, speak to your support representative.

Each script that you create is called every time the server receives a message (such as the regular reports from the units installed in your vehicles). The script takes information provided by the message (in an API object called Context) and returns true if the condition you are looking for has been met, or false if the condition is not met. This value is used by the Exception engine to turn the InSight Alert on or off, to trigger InSight Alerts and send emails when appropriate.

InSight Alert scripts are called every time the server receives a message. This means that they will cause problems if they take too long. Because of this, if you create InSight Alert scripts that take too long, they will be automatically disabled (and an email sent to inform you of this).

InSight Alert Scripts UI

From the Tasks section of the navigation bar choose InSight Alert Scripts to open the InSight Alert Scripts screen.

To define a new InSight Alert script:
 

1.Click the Create button in the left panel. A new script is added to the list and automatically selected.
2.In the right panel, complete the Details page:
 
Assign the new condition a Name. This is the name of the Alert Type that appears in the Setup InSight Alerts screen. It must be unique and cannot contain any spaces.
If you want to be able to set the time to trigger and indicate whether or not the Alert is aggressive, set the Condition Type to ScriptedTimeRangeCondition. If these controls should not be available, set the Condition Type to ScriptedCondition.
Enter any instructions for using the condition in the Instructions field. These appear on the Setup InSight Alerts screen for the scripted condition.
Enter a description in the Description field. This description appears next to the name for the new Alert Type when you create a new InSight Alert.
Under Error Contact Email, enter an email address for whoever should be notified if the script throws an error. This can be because of an exception thrown within the script, or because the script took too long to run and had to be disabled.
Under Target Type, indicate whether the InSight Alert is concerned with a Driver, a Job, or a Unit (vehicle). The Target Type determines what sort of information is available in the Context object.
Select or clear Keep a persistent state for this script. When selected, the global State object keeps its values even after the condition deactivates.
Select or clear This script does not require message from vehicles. When selected, the script runs for every report (point) received from the vehicle.
3.In the right panel, switch to the Parameters page. The parameters tab defines values that need to be provided to the script when you set up the alert in the Setup InSight Alerts screen. For each parameter that you add, you should provide:
 
The Name of the parameter. This is the name of the variable you can use inside your script to refer to the value supplied when the new Alert is created.
The Display Name of the parameter. This is the name that appears on the parameters tab of the Setup InSight Alerts screen.
The Type of the parameter. Select the type of value that can be assigned to the parameter from the drop-down list.
If the Type of the parameter is an enumeration, you must specify the allowable values, separated by semicolons.
4.In the right panel, switch to the Script page. This is where you can write the actual script to identify and trigger the new Alert type.
5.Click the Save button in the lower right corner.

Once you have saved and enabled an InSight Alert Script:
 

The Name you provided appears in the list of Alert Types when you click the Create button on the Setup InSight Alerts page.
When you select the new condition type, the Setup InSight Alert page lists the parameters that you have specified, so that they can be supplied to the script.

Once you have created an InSight Alert based on your new InSight Alert script, it appears on the Conditions page when you select the script. If the InSight Alert fails because the script has errors in it, your script is automatically disabled. To fix and re-enable the script:
 

1.Select the script in the list.
2.Go to the Script page and edit the script to fix the problem.
3.Save your changes.
4.Go to the Conditions page, place the cursor in the Enabled column, and select the check box to re-enabled the script.

 

You can also click the Details tab to check the date the script was first created, and the date it was edited (if it was subsequently edited). The timestamp of the script's creation and that of the last edit are shown in the lower part of the tab.

Writing Scripts

Before writing scripts, read InSight Alerts: under the hood for an understanding of how alerts trigger.

To define a new script, you need to override the ConditionMet function. When ConditionMet returns true, the Alert goes on. When it returns false, the Alert goes off. Aggressive and TimeToTrigger are handled automatically for you, as long as you set the Condition Type to ScriptedTimeRangeCondition.

For example, a single script to detect off-hours usage on weekdays at a Depot marker would look like the following:
 

ConditionMet = function (Context) {

    if (!Context.Time.DayOfWeek.Equals(System.DayOfWeek.Saturday) && 

        !Context.Time.DayOfWeek.Equals(System.DayOfWeek.Sunday) && 

         Context.Unit.IsAtMarkerInCategory(Depot)) {

        if ((5 <= Context.Time.Hour) && (Context.Time.Hour <= 19)) {

            return false;

        }

        return Context.Unit.Ignition;

    }

    return false;

};

 

In this example, the script makes use of a parameter that has its Name set to Depot, which specifies a marker category. The TargetType for this script is Unit, so that the Context object has a defined Unit field. The script starts by checking that it is a weekday and that the vehicle is at a marker with the same category as the Depot parameter. If so, it checks the current hour, and returns true only if it is outside of normal hours and the ignition is on.

If you need special handling for the way the new Alert triggers and is turned off (for example, to create an alert that is never deactivated), you can also override the Process function. The default value of the process function is as follows:
 

function Process(Context) {

    if (ConditionMet(Context) {

        Activate(Context);

    } else {

        Deactivate(Context);

    }

}

For additional examples of InSight Alert Scripts, see Example Scripts.

Global Variables and Methods

Within a script, certain global variables are available to you, which can provide information that is useful for determining when the new Alert condition is met:

Variable

Description

Context

This provides information about the Unit or Driver that is the target of the alert. This object is the same as the Context that is passed as an argument to the function you create. It is the entry point to using the API objects for InSight Alert scripts.

State

State is an empty dictionary that can be used to store information between calls to your script. That is, it is a place for you to define and store any named values that you want. By default, State does not have any properties or pre-defined values. You add values by making an assignment such as State.NAME = VALUE. It is good practice to initialize the values you are using to a default value the first time the script is called, so that you do not try to read an undefined value: if (typeof State.Name === 'undefined') { State.NAME = 0; }

For example, if you want to activate an alert if a driver hard brakes more than 5 times, you could do the following:

ConditionMet = function(Context) {

    if (Context.Unit.HasDiagnosticValue(770) and 

        Context.Unit.GetDiagnosticValue(770) > 0 and

             not IsAlreadyBraking) {

        IsAlreadyBraking = true;

        State["BrakingCount"] += 1;

    } else {

        IsAlreadyBraking = false;

    }

    if (State["BrakingCount"] > 5) {

       return true;

    } else {

       return false;

    }

}

The State variable is only available if you select the Keep a persistent state for this script check box.

Be careful not to add too much information to the persistent state variable. If this dictionary contains too much information, it can slow down your scripts to the point where they are automatically disabled.

EmailFields

This is a dictionary of fields that can be included in emails that are sent when the alert triggers or is turned off. In the email, the name and value are listed as part of the email message. For an example showing how to use this global, see Checking DTCs.

Inside your scripts, you can also call the following global method

Method

Parameters

Return Type

Description

SetTriggerValue

APIContext context,

string triggerName,

object triggerValue

void

Allows a script to specify the trigger value that is displayed in the InSight Alerts inbox and in alert emails. The context argument should be set to the global Context object (which is also the Context parameter of the ConditionMet method you are writing). Typical usage is something such as the following:

SetTriggerValue(Context, "SMR (Engine Hours)", currentHours + " h");

This example displays the SMR (Engine Hours) from a parameter called currentHours, where the result is formatted to look like

SMR (Engine Hours) : 1000h