ℹ️ The Auron SMS Server is now Auron Omni. Learn more here.

How can we help?

Trigger scripts writing and testing

Triggers are custom actions you configure when a message is received or changes state. This page details how to write and test trigger scripts.

Triggers are part of the Auron Omni message bus. You find more information on how to configure triggers here.

This page describes:

Trigger basics

A trigger has these main parts:

  • The message type. The trigger only applies to messages of this type;
  • On status. The trigger runs when a message reaches this status;
  • A condition. An SQL expression that must be true for the trigger to run;
  • The trigger script. This is the script that runs when the condition is true.

The trigger script is either:

  • VBScript;
  • JavaScript;
  • SQL Script.

For most cases there is a trigger template available. If there is no trigger template you can either create a new trigger or create one from a template to customize it.

Trigger scripts always run in sequence according to the processing order of all triggers.

Writing a JavaScript or VBScript trigger

JavaScript and VBScript (Visual Basic Script) triggers are similar. They both run using the Microsoft Active Scripting engine. This means that, despite having different syntax, they have roughly the same capabilities.

You can learn more about JavaScript and VBScript on W3Schools.

An empty trigger script always has the same structure:

STR_DEBUGFILE       = "C:\ProgramData\Auron\Log\TriggerName.txt"
B_ENABLE_DEBUG      = true

// ========================================================================
// Function: ProcessMessageEx
// ------------------------------------------------------------------------
// ProcessMessageEx trigger function to process incoming messages
// ========================================================================
function ProcessMessageEx(objMessageIn, objMessageDB, dctContext)
{
Log(">> ProcessMessageEx")

// ... Your logic here

Log("<< ProcessMessageEx")
}
CONST STR_DEBUGFILE     = "C:\ProgramData\Auron\Log\TriggerName.txt"
CONST B_ENABLE_DEBUG    = True

' // ========================================================================
' // Function: ProcessMessageEx
' // ------------------------------------------------------------------------
' // ProcessMessageEx trigger function to process incoming messages
' // ========================================================================
Function ProcessMessageEx(objMessageIn, objMessageDB, dctContext)

Log ">> ProcessMessageEx"

' ... Your logic here

Log "<< ProcessMessageEx"

End Function

The top two lines declare whether logging (debug) is enabled and the location of the log file.

The service calls ProcessMessageEx for each message that matches the trigger condition.

You can use the top of the trigger script to initialize variables that you reuse in ProcessMessageEx for each message.

The arguments to ProcessMessageEx are:

  • objMessageIn. This is the message object that triggered this trigger. The specific message object depends on the trigger message type;
  • objMessageDB. This is an instance of MessageDB. This object gives access to the message database so you can create new messages or run queries against it;
  • dctContext. This is a dictionary object you can use to keep variables between calls to ProcessMessageEx. You can also keep variables in the global scope of the script.

The objMessageIn is always of type:

The trigger script reloads and reinitializes when:

  • The Auron Omni service starts;
  • The trigger script or trigger configuration is modified.
Include files

You can add a number of include files to your trigger. By default there is always the common include file (common.vbs or common.js) that defines the log function, but you can add your own as well.

If you have made modifications to the common include file the setup does not replace it on an update.

The list of include files is appended to the trigger script in memory right before running the script when starting the service. In case of an error the line numbers are corrected in the error message.

Logging debug output

Use the Log function to log information to a debug file. The two constants at the top of the script file determine the logging behavior:

  • STR_DEBUGFILE contains the log file destination path;
  • B_ENABLE_DEBUG set this to false to disable logging.
Creating new messages (SMS or Email)

Create a new SMS or Email message directly from a trigger by using the local API.

Any of the Local API objects can be used in trigger scripts.

How to create a new SMS:

// ProcessMessageEx delivers an instance of objMessageDB that already
// has a connection. Using that instance performs better than creating
// a new instance.
//
// objMessageDB = new ActiveXObject("AxMmServer.MessageDB")

objSms = objMessageDB.Create("SMS")
objSms.ToAddress = "+31611223344"
objSms.Body = "Hello, World!"
objSms.ChannelID = ""   // Specify a channel or depend on the router
objMessageDB.Save(objSms)
' ProcessMessageEx delivers an instance of objMessageDB that already
' has a connection. Using that instance performs better than creating
' a new instance.
'
' Set objMessageDB = CreateObject("AxMmServer.MessageDB")

Set objSms = objMessageDB.Create("SMS")
objSms.ToAddress = "+31611223344"
objSms.Body = "Hello, World!"
objSms.ChannelID = ""   ' Specify a channel or depend on the router
objMessageDB.Save(objSms)

How to create a new email:

// ProcessMessageEx delivers an instance of objMessageDB that already
// has a connection. Using that instance performs better than creating
// a new instance.
// 
// objMessageDB = new ActiveXObject("AxMmServer.MessageDB")

objEmail = objMessageDB.Create("EMAIL")
objEmail.ToAddress = "alerting@company.com"
objEmail.BodyPlainText = "Hello, World!"
objEmail.ChannelID = ""   // Specify a channel or depend on the router
objMessageDB.Save(objEmail)
' ProcessMessageEx delivers an instance of objMessageDB that already
' has a connection. Using that instance performs better than creating
' a new instance.
'
' Set objMessageDB = CreateObject("AxMmServer.MessageDB")

Set objEmail = objMessageDB.Create("EMAIL")
objEmail.ToAddress = "alerting@company.com"
objEmail.BodyPlainText = "Hello, World!"
objEmail.ChannelID = ""   ' Specify a channel or depend on the router
objMessageDB.Save(objEmail)
Opening and creating files

For file access you can use the Scripting.FileSystemObject. This is part of Windows.

To write a string to file:

objFso = new ActiveXObject("Scripting.FileSystemObject")

// Arguments are: File path, Overwrite?, Unicode?
objFile = objFso.CreateTextFile("test.txt", true, true)
objFile.WriteLine("This is surprisingly easy ????")
objFile.Close()
Set objFso = CreateObject("Scripting.FileSystemObject")

' Arguments are: File path, Overwrite?, Unicode?
Set objFile = objFso.CreateTextFile("test.txt", True, True)
objFile.WriteLine "This is surprisingly easy ????"
objFile.Close

If you want to read a file into a string without using the file channel:

objFso = new ActiveXObject("Scripting.FileSystemObject")

// Arguments are: File path, IoMode, Create?, Format
// IoMode: 1=Read, 2=Write, 8=Append
// Format: -2=Default, -1=Unicode, 0=ASCII
objFile = objFso.OpenTextFile("test.txt", 1, false, -1)
sText = objFile.ReadAll()
Set objFso = CreateObject("Scripting.FileSystemObject")

' Arguments are: File path, IoMode, Create?, Format
' IoMode: 1=Read, 2=Write, 8=Append
' Format: -2=Default, -1=Unicode, 0=ASCII
Set objFile = objFso.OpenTextFile("test.txt", 1, False, -1)
sText = objFile.ReadAll()
Calling external HTTP APIs

Use the Windows HTTPXML API for making HTTP API calls.

An example of a simple HTTP GET request:

objHttp = new ActiveXObject("MSXML2.ServerXMLHTTP") 
  
// arguments are: Verb, Url, Async, (opt)User, (opt)Password
objHttp.open("GET", "https://www.auronsoftware.com/fortune/", false)
objHttp.send()
sResult = objHttp.responseText
Set objHttp = CreateObject("MSXML2.ServerXMLHTTP") 
  
' arguments are: Verb, Url, Async, (opt)User, (opt)Password
objHttp.open "GET", "https://www.auronsoftware.com/fortune/", false
objHttp.send()
sResult = objHttp.responseText

An example of a more elaborate POST request with authorization header:

objHttp = new ActiveXObject("MSXML2.ServerXMLHTTP") 

// arguments are: Verb, Url, Async, (opt)User, (opt)Password
objHttp.open("POST", "https://www.auronsoftware.com/fortune/", false)
objHttp.setRequestHeader("Content-Type", "application/json")
objHttp.setRequestHeader("Authorization", "{BEARER TOKEN}")
objHttp.send("{\"json\": \"values\"}")
sResult = objHttp.responseText
Set objHttp = CreateObject("MSXML2.ServerXMLHTTP") 

' arguments are: Verb, Url, Async, (opt)User, (opt)Password
objHttp.open "POST", "https://www.auronsoftware.com/fortune/", false
objHttp.setRequestHeader "Content-Type", "application/json"
objHttp.setRequestHeader "Authorization", "{BEARER TOKEN}"
objHttp.send("{""json"": ""values""}")
sResult = objHttp.responseText

If your API uses OAuth2 you can authorize using the OAuth2 Authorizer and use the OAuth2 API to refresh your bearer token when required.

Connecting to an external database

Use the Windows ADODB objects to connect to an external database from your trigger.

For example to handle an unsubscribe message you can do this:

objDatabase = new ActiveXObject("ADODB.Connection")

// The ADO connection string for your external database
sCs = "Provider=Microsoft.Ace.OLEDB.12.0;Data Source=students.mdb"
objDatabase.Open(sCs)

// Parameterized update; better resistance against malicious input
// Say this is an incoming unsubscribe message and we update the database
// The email address comes from objMessageIn.FromAddress
// provided by the ProcessMessageEx function
sFromEmail = "alice@school.com" // objMessageIn.FromAddress

objCmd = new ActiveXObject("ADODB.Command")
objCmd.ActiveConnection = objDatabase

// Arguments are: Name, Type, Direction, Size
// Find type values here:
// https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/datatypeenum
// Find direction values here:
// https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/parameterdirectionenum
objParam = objCmd.CreateParameter("@eml", 200, 1, 255, sFromEmail)
objCmd.Parameters.Append(objParam)

objCmd.CommandText = "UPDATE Students SET Subscribed = 0 WHERE Email = @eml"
objCmd.Execute()

objDatabase.Close()
Set objDatabase = CreateObject("ADODB.Connection")

' The ADO connection string for your external database
sCs = "Provider=Microsoft.Ace.OLEDB.12.0;Data Source=students.mdb"
objDatabase.Open sCs

' Parameterized update; better resistance against malicious input
' Say this is an incoming unsubscribe message and we update the database
' The email address comes from objMessageIn.FromAddress
sFromEmail = "alice@school.com" 'objMessageIn.FromAddress

Set objCmd = CreateObject("ADODB.Command")
objCmd.ActiveConnection = objDatabase

' Arguments are: Name, Type, Direction, Size
' Find type values here:
' https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/datatypeenum
' Find direction values here:
' https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/parameterdirectionenum
Set objParam = objCmd.CreateParameter("@eml", 200, 1, 255, sFromEmail)
objCmd.Parameters.Append(objParam)

objCmd.CommandText = "UPDATE Students SET Subscribed = 0 WHERE Email = @eml"
objCmd.Execute()

objDatabase.Close

Or use something like this if you just need to select a value from your database:

objDatabase = new ActiveXObject("ADODB.Connection")

sCs = "Provider=Microsoft.Ace.OLEDB.12.0;Data Source=students.mdb"
objDatabase.Open(sCs)

sName = ""
sQ = "SELECT Name FROM Students WHERE Email = 'alice@school.com'"
objRs = objDatabase.Execute(sQ)

if (!objRs.EOF)
{
sName = objRs("Name").Value
}

// sName is now the name of the student

objDatabase.Close()
Set objDatabase = CreateObject("ADODB.Connection")

sCs = "Provider=Microsoft.Ace.OLEDB.12.0;Data Source=students.mdb"
objDatabase.Open sCs

sName = ""
sQ = "SELECT Name FROM Students WHERE Email = 'alice@school.com'"
Set objRs = objDatabase.Execute(sQ)

If Not objRs.EOF Then
sName = objRs("Name").Value
End If

' sName is now the name of the student

objDatabase.Close()
Opening an MS Excel sheet

Excel sheets work exactly like a database by using Windows ADODB objects. When your tables have names you can select from them and update them.

This is an example of how to handle an unsubscribe if your table is in Excel instead of a database:

objCon = new ActiveXObject("ADODB.Connection")

objCon.Open("Provider=Microsoft.ACE.OLEDB.12.0; Data Source=Students.xls;" +
" Extended Properties='Excel 12.0 Xml; HDR=YES'")

// Parameterized update; better resistance against malicious input
// Say this is an incoming unsubscribe message and we update the data
// The phone number comes from objMessageIn.FromAddress
sFromNumber = "+31612345678" // objMessageIn.FromAddress

objCmd = new ActiveXObject("ADODB.Command")
objCmd.ActiveConnection = objCon

// Arguments are: Name, Type, Direction, Size
// Find type values here:
// https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/datatypeenum
// Find direction values here:
// https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/parameterdirectionenum
objParam = objCmd.CreateParameter("@nr", 200, 1, -1, sFromNumber)
objCmd.Parameters.Append(objParam)

objCmd.CommandText = "UPDATE Students SET Subscribed = 1 WHERE [Phone nr] = @nr"
objCmd.Execute()

objCon.Close()
Set objCon = CreateObject("ADODB.Connection")

objCon.Open "Provider=Microsoft.ACE.OLEDB.12.0; Data Source=Students.xls;" & _
  " Extended Properties='Excel 12.0 Xml; HDR=YES'"

' Parameterized update; better resistance against malicious input
' Say this is an incoming unsubscribe message and we update the data
' The phone number comes from objMessageIn.FromAddress
sFromNumber = "+31612345678" 'objMessageIn.FromAddress

Set objCmd = CreateObject("ADODB.Command")
objCmd.ActiveConnection = objCon

' Arguments are: Name, Type, Direction, Size
' Find type values here:
' https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/datatypeenum
' Find direction values here:
' https://docs.microsoft.com/en-us/sql/ado/reference/ado-api/parameterdirectionenum
Set objParam = objCmd.CreateParameter("@nr", 200, 1, -1, sFromNumber)
objCmd.Parameters.Append(objParam)

objCmd.CommandText = "UPDATE Students SET Subscribed = 1 WHERE [Phone nr] = @nr"
objCmd.Execute()

objCon.Close

Or use something like this if you just need to select a value from your Excel sheet:

objCon = new ActiveXObject("ADODB.Connection")

objCon.Open("Provider=Microsoft.ACE.OLEDB.12.0; Data Source=Students.xls;" +
" Extended Properties='Excel 12.0 Xml; HDR=YES'")

// Use brackets [] if a field or table name has spaces or special characters
q = "SELECT Name FROM Students WHERE [Phone nr] = '+31687654321'"
objRs = objCon.Execute(q)

sName = ""
if (!objRs.EOF)
{
sName = objRs("Name").Value
}

// sName holds the name of the student

objCon.Close()
Set objCon = CreateObject("ADODB.Connection")

objCon.Open "Provider=Microsoft.ACE.OLEDB.12.0; Data Source=Students.xls;" & _
  " Extended Properties='Excel 12.0 Xml; HDR=YES'"

' Use brackets [] if a field or table name has spaces or special characters
q = "SELECT Name FROM Students WHERE [Phone nr] = '+31687654321'"
Set objRs = objCon.Execute(q)

sName = ""
If Not objRs.EOF Then
sName = objRs("Name").Value
End If

' sName holds the name of the student

objCon.Close

Writing a SQL trigger script

Auron Omni already has a database connection open and therefore is able to optimize the execution of a SQL script to a great extent.

There is no structure to a SQL trigger script as there is for JavaScript or VBScript triggers.

It can be a multi-line script, a single update or insert statement, or a stored procedure call.

You can use any message variables in your trigger script by using the field name prefixed with @fld.

For example, this can be a SQL trigger script that handles an unsubscribe message:

 -- @fldFromAddress is set by the Auron Omni service to the value of 'FromAddress'
 -- As an additional optimization the Auron Omni only initializes values that you
 -- actually reference in the SQL script.

UPDATE dbStudents.dbo.tblStudents SET subscribed = 0 WHERE EmailAddress = @fldFromAddress

Another example forwards an incoming SMS to an email message using the 'InsertEmail' view:

INSERT INTO InsertEmail(StatusID, ToAddress, Subject, BodyPlainText) VALUES
  ("SCHEDULED", "alert@yourcompany.com", "SMS from: " + @fldFromAddress, @fldBody)

Testing your triggers

With Auron Omni it is easy to test your triggers. The following sections describe some of the tools you can use.

The trigger activity view

Triggers automatically reload after you modify either the definition or the script file itself.

For JavaScript and VBScript triggers this means a basic syntax check every time you press Ctrl S in your editor.

Therefore it makes sense to keep an eye on the trigger activity view while you are editing your script.

Auron Omni Manager - Trigger activity view

Auron Omni Manager - Trigger activity view

Create incoming messages and reprocess them

You do not need to spend credits to test your trigger. You can simply create an incoming message and reprocess it until your trigger works.

Find out how to create messages from the manager application here. Make sure you select In as your direction and click Create.

Auron Omni Manager - Create an incoming SMS

Auron Omni Manager - Create an incoming SMS

This causes triggers on incoming SMS messages to run on this message.

To continue testing with the same message, right click the message and select Reprocess. Reprocess clears the processed status and causes triggers to run again for this message.

Auron Omni Manager - Reprocess

Auron Omni Manager - Reprocess

If you are testing different states that Received, you can create a message and modify its state in the same way. Just right click the message, select Update message status, and select the status you need to test.

The message trace tab

Every message keeps its own history in the Trace field of the message. This is extremely useful when writing or testing scripts.

Auron Omni Manager - Message trace

Auron Omni Manager - Message trace

The message trace shows the trigger status and which triggers ran on this message. If there is an error it shows the details of the error. Every message type always has this trace tab.

You can add custom trace messages from your trigger by calling the 'AddTrace' method on a message.

The trigger log file

JavaScript and VBScript triggers have the option to keep a log file. The full path is at the top of the trigger file.