The purpose of this tutorial is to prepare system users to effectively create Automations which are feature sets that can be used within the SOMA platform or outside of the SOMA platform, and they help us to communicate more effectively with the systems that SOMA integrates with.

At the end of this tutorial, participants will be able to:

2. Select GROUPS

3. Choose the GROUP TYPE

4. Scroll down to the ADMIN section, then check the appropriate Automation boxes.

1) Log in to the SOMA ADMIN area by clicking on the SOMA Switch, 2) go to the Admin area, 3) click the Menu, and 4) choose “Automations.”

Click the “plus” button at the bottom of your Automations list to add a new Automation.

Next, choose a trigger.

There are several types to choose from when using SOMA Automation Triggers, such as

-Record Hook: Triggers the Automation based on the creation, update, view, or deletion of a Record.

-Dispatch Hook: Triggers the Automation based on a Dispatch action, such as a Call created or Unit assigned.

-Scheduled: Triggers the Automation based on a specified Cron schedule, e.g., at 1800 hrs every day, or on the 15th of each month, etc. You can use a Cron generator or view a Tutorial for more information.

-Custom API: Triggers the Automation based on a custom API. This automatically builds an endpoint into your agency’s SOMA tenant (api/1/triggers/custom_endpoint_name).

-File Drop: Triggers the Automation based on a file sent to an S3 bucket.

-Command Line: Triggers the Automation based on a custom command line prefix.

See the example image below:

Once you choose a Trigger:

1) Add a name to your Automation,

2) Add a brief description. Then,

3) Click submit.

Your new Automation will be created at the bottom of the page and default with the toggle switch off.

Click the three dots on the right side and choose Edit Automation Steps to begin adding Automation Steps.

After clicking on the three dots, 1) click on the Edit Automation Steps option, 2) select the Event Type from the drop-down arrow, and 3) click the “plus” button at the bottom of your Automation Sequence to add a new Step.

You can choose the Type of Step that will work best for your Automation. See the example image below:

The Filter Step provides a filter function. If the function returns true, the Automation will continue. If the function returns false, it will stop the Automation at this step.

The function is automatically fired at this step, and it has access to one parameter, steps.

Steps is a global object that persists between steps and contains data attached as properties. For example, if you chose a Records Trigger and attached the Incident Report schema as the Record Type, you can now access the incident report number by referring to:

steps.one.data.incidentNumber

steps.one refers to the first step of the Automation, where steps is initially created.

data.incidentNumber refers to the Schema’s API Property Name.

EXAMPLE FILTER STEP

2. LOOP MULTI-STEP

The Loop Multi-Step allows you to perform the same series of steps using multiple pieces of data. It has one field: The Loop Range Property Name. This is where you identify the data array that should be looped through.

For example, if your Trigger is Scheduled, your Cron schedule would be step

1. Then, you would likely have a Query step as step 2. If you wanted to loop through the resulting data from the step 2 query, you would indicate this by putting steps.two as the property name here.

NOTE: The Loop Step will contain that iteration’s data during the loop. For example, if your Loop Step is the third step of the Automation, then while you’re inside of the Loop Step, refer to steps.three to use the current iteration of the data (e.g., in the Filter or Transformation steps). In other words, if you are familiar with a traditional JavaScript for loop, then steps.<loopStepNumber> would take the place of arrayName[i].

Once you have the property name entered, you can use the “plus” button to add additional steps that will constitute the loop. This can be any Step type.

NOTE: If a Filter Step Type is selected, it will filter each individual piece of data being looped through. If the Filter Step returns false, it will stop the current loop iteration, not the entire loop. Also, a loop step can not be used inside of a loop step at this time.

EXAMPLE LOOP MULTI-STEP

3. TIME DELAY STEP

The Time Delay step only requires one field: the Time Delay in milliseconds. Variables may be used, but the value must be in string format.

For example, using a Transformation step, a delayTime property could be added to the steps object with a value of 1000, but it would need to be transformed into a string before being used in the Time Delay step:

steps.delayTime = JSON.stringify(1000);

Then, that property can be inserted into the Time Delay field using curly braces: {steps.delayTime}

EXAMPLE TIME DELAY STEP

4. HTTP REQUEST STEP

Using the HTTP Request Step, an external API may be easily reached. First, enter the Request Type (GET, PUT, POST, PATCH, and DELETE currently supported), and the next field should be the full API URL path.

Next, the Request Source can be specified (Cloud/Agent). This determines whether the outbound HTTP request originates from our cloud infrastructure or from an on-premise agent.

Your Request Body should come from a previous step via variable. For example, a jsonPayload property could be assigned to the steps object in a Transformation step, then referenced here as {steps.jsonPayload}. Be sure to specify the Body Type format, and make sure any prior step’s reference variables that will be used are in the correct format: json, xml, text, or none.

Authentication may be done via API Key, Bearer Token, Basic (Username/Password), or None.

Finally, any necessary headers may be added by clicking the “plus” sign. The appropriate key/value pair may then be entered.

EXAMPLE HTTP REQUEST STEP

5. HTTP Response STEP

The HTTP Response Step can be used in conjunction with a Custom API Trigger to provide a custom response to the custom API. The response payload can be configured and calculated in previous steps, then provided via reference variable, e.g., {steps.two.jsonPayload}.

By default, if an API Automation ends without a specified response, it will wait until the sequence ends to send either a 200 OK or Error, so adding this Response step allows the custom response to be provided at a certain step.

Be sure to specify the Body Type to let the system know how to handle the payload; you may choose between xml, json, text, and none.

EXAMPLE HTTP RESPONSE STEP

6. FTP TRANSFER STEP

The FTP Transfer Step allows you to send files via File Transfer Protocol. Reference variables from previous steps may be used in curly braces in the host, contents, or filename fields. Currently, authentication is only available via username and password. It can not exchange SSH keys.

7. SEND TCP PACKET STEP

The Send TCP Packet Step allows you to send a TCP Packet to a specified host and port. The Host and Contents fields can use reference variables from previous steps, e.g., {steps.packetData}

8. QUERY RECORDS STEP

The Query Records Step allows you to query a specific Records Schema with any API filters to restrict the data being pulled. More information on these filters, including multiple examples, can be found on this docs page. These filters can be listed in the field below your schema choice and chained together with the & symbol.

This step also has a built-in Transform function. The (filtered) result of your Query can be accessed using steps.previousResult. Whatever is returned in this Transform function is accessible to future steps by referring to this step. For example, if this is the third step in your Automation sequence, and this Transform function has return steps.previousResult.fullName, then in future steps, this name could be accessed by the reference variable steps.three.

9. CREATE RECORDS STEP

The Create Records Step allows you to create a new record in a specified Schema.

First, specify which Schema will have the record added to it. More information about building Schemas may be found on this docs page.

Next, the Upsert Field can be used to ensure duplicate records do not get created. Reference the API field that would be unique to each record, such as data.inmateID.

The last part of this step is to specify the record data that should be created. This defaults to the Advanced (code) method but may be changed to Simple via the toggle switch.

The Simple method requires the field's name containing the record to create. When used in a Loop step, this is often the loop step index. For example, if the loop is the third step, this would be steps.three.

The Advanced method provides a create function for your customization. This function has access to one input parameter, steps. It must return a JSON object of the form {data: {}}. A commented-out result variable and return result are provided for your convenience.

EXAMPLE CREATE RECORDS STEP

NOTE: This example is simplified for demonstration purposes only.

10. UPDATE RECORDS STEP

The Update Records step allows you to specify a Schema and modify specific records in that Schema.

First, specify which Schema contains the record(s) that will be updated. More information about Schemas may be found on this docs page.

Next, you will add API filters to restrict the records being pulled. More information on these filters, including multiple examples, can be found on this docs page. These filters can be listed in the field below your schema choice and chained together with the & symbol.

The last part of this step is to set up an Update function that can modify the data before sending it for the update. This defaults to the Advanced (code) method but may be changed to Simple via the toggle switch if the record was queried and transformed prior to the update step.

The Simple method requires the field's name containing the record to create.

The Advanced method provides an update function for your customization. This function has access to one input parameter, steps. There is an additional property on the steps object, previousResult, which is the result of the previous query on this step and may be transformed or used in this function.

This update function must return a JSON object array of the form {_id: string, data: {}}. A commented-out result variable and return result are provided for your convenience.

11. TRANSFORMATION STEP

The Transformation Step provides a calculate function. This step allows you to transform the steps object using JavaScript. At the end of this function, you must return steps, so it is accessible to future steps in their newly transformed state.

The function is automatically fired at this step and has access to three objects: steps, users, and agency.

You could also create calculated properties, do the math, or use normal JavaScript functions to transform the data in this step. One simple example would be creating a string property that will be sent as a message in a future step:

Now, this string is on the steps object as the message property, with the property owner’s name dynamically inserted.

EXAMPLE TRANSFORMATION STEP

12. GENERATE A UNIQUE ID STEP

The Generate Unique ID Step allows you to generate a universally unique identifier. This is a 32-digit character that automatically returns and stores it as the step number.

This means that, for example, if this is the second step in the Automation sequence, steps.two can be used in subsequent steps to refer to the generated UUID.

You could check this in subsequent Transformation steps by adding a line log(JSON.stringify(steps.two)), and then the UUID would be visible in the logs if the Transformation step runs properly.

There is no customization or input needed from the user for this component.

13. EXECUTE SQL QUERY STEP

The Execute SQL Query Step allows you to connect to a SQL database using basic authentication. You can then run a custom SQL query and add any reference variables to the query using curly braces.

SELECT * FROM db.{steps.config.tablename} WHERE {steps.query}; is automatically provided in the Query Setup field for your convenience.

Configuration variables help you avoid hardcoding values that may not be valid if the Sequence is reused in another context or if the variable’s value may change. If you would like to use a configuration variable for the table name, as the example Query Setup code indicates, you can do so from your agency’s list of Automations. Click the downward arrow (next to the toggle switch), then click the “plus” button to add a configuration variable. You can choose the variable’s name, whether it is text or password type, and then click Submit. You can now access that value throughout the Automation on the steps.config object.

14. INVOKE AWS LAMBDA STEP

This step allows you to easily invoke an AWS Lambda function with just a few pieces of information. If you’re not familiar with AWS Lambda, you can find their documentation here.

This can be useful if your task isn’t easily accomplished within the Transform function or is otherwise outside the scope of the Automations application. A function can be written in AWS Lambda in many different programming languages, then invoked on-demand with a specified payload using this service.

First, you’ll want to set up your Lambda function and retrieve the Lambda name, preconfigured access key, and secret key. You’ll additionally want to configure the payload that will be sent to the Lambda service. This will probably be done with Filter, Query, or Transformation steps prior to this one and stored on the steps object.

Once these are completed, simply choose your AWS Region and enter the Lambda Function’s name. Add the preconfigured access key and secret key. Finally, add the reference variable (in curly braces) that is storing the payload you wish to send. For example, if you previously assigned the data to steps.lambdaPayload, you would enter the Payload name as {steps.lambdaPayload}.

15. UPDATE DISPATCH STEP

The Update Dispatch Step allows you to configure various changes within the Dispatch system based on your Automation sequence.

16. SEND SMS STEP

The Send SMS step allows you to configure a text message (SMS) to be sent to the specified phone number(s) or groups of phone numbers.

The message body can be written directly in the Message Body field while referencing any previous variables within curly braces. For example, if you stored someone’s name in a previous Transformation step on the steps object as the fullName property, then your Message Body field may look like this:

Hi, {steps.fullName}. This is APD with a friendly text message.

NOTE that quotation marks or other extraneous characters are not necessary in the Message Body field.

There are two fields available in the Setup Recipients section. You may manually type specific phone numbers in this field or reference variables stored in previous steps by putting the variable name in curly braces, just like the Message Body. For example, {steps.one.data.victimPhone} could be the right phone number for this use case. Separate any additional phone numbers in this field by using commas.

If using a Group, the message will be texted to all Users currently listed in that Group, as long as they have a phone number listed in their profile.

EXAMPLE SEND SMS STEP

17. SEND EMAIL STEP

The Send Email step allows you to configure an email to be sent to specified email recipients or User groups.

All text fields in this Step can use variables from prior steps by placing the variable in curly braces. For example, if the steps object had a fullName property added to it in a previous step, then you can customize a field with{steps.fullName} inserted where you would like that name placed. Also note that in all text fields, quotation marks or other extraneous characters are not necessary.

First, you can type the Message Subject.

Next, you can choose the Email Body Type. This supports plain text emails, the use of the Basic default template, or a custom template. We will focus on the Basic template here.

The Body Header and Message Body constitute the main message to the recipient.

The Action URL and Action Text work together to create an interactive button for the recipient to click for any action you would like them to take. For example, it can link to a specific incident report using your agency’s SOMA API and variables from previous steps, or it could be linked to a victim resource page, etc.

The Subcontext is an italicized string that appears below the button.

The Basic Template has a preview that appears as you configure it, so you can see what will be sent to the recipient (note the variables are not yet evaluated).

There are two fields available in the Setup Recipients section. You may manually type specific emails in this field, or you may reference variables. Separate any additional emails in this field by using commas.

If using a Group, the message will be emailed to all Users currently listed in that Group, using the email in their User profile.

EXAMPLE SEND EMAIL STEP

The example below demonstrates the use of reference variables in various fields and also shows how the Basic Template automatically generates a preview of the email (with the variables not yet evaluated).

In the following example, we will create an Automation that sends a text message notification (SMS) to all Shift Supervisors when a Missing Person report is submitted.

A basic schema was built for this example, which included fields for the Missing Person’s name, whether they were still missing or the report was only for informational purposes, and their last known location:

Missing Person Schema Example:

AUTOMATION SETUP

Click the menu button at the top of your screen.

Then select the Automations list to add a new Automation.

2. Click the “plus” button at the bottom of your Automations list to add a new Automation.

3. Next, choose a trigger. There are currently six types of triggers to choose from:

CREATING THE AUTOMATION SEQUENCE

4. In this case, we’ll choose the Record Hook trigger. This will allow us to fire the Automation every time a user adds a record (Missing Person form submission).

5. Choose the name of your new Automation, and type a brief description. Then, click Submit.

Your Automation will be created in the list of Automations and default with the toggle switch Off. Click the three dots on the right side and choose Edit Automation Steps.

Notice it already created the first step in the Automation – the trigger you initially selected. In the first selection box (“Select a Record Type”), choose which Schema that will be used for this trigger. In this example, we used the Missing Person Schema.

Next, you’ll want to select which operation(s) will trigger this Automation. In this example, we’ll only use the record creation. However, we could also use the record Update, View, or Creation to trigger this action. Multiple events can be selected or deselected from this dropdown.

We are now ready to add another Automation step. Click the “plus” button at the bottom of our steps list.

A list of step types will appear.

You’ll often want to use the Filter step next to ensure the events are a certain type before firing the entire Automation. For example, we’ll want to check whether the Missing Person is still missing before we notify all the supervisors since an information-only report would likely not be a high enough priority for such a broadcast.

Select “Filter Step,” and it will be automatically added to your steps.

Select that step in order to edit it.

The filter function takes in the schema (report) data from step 1 as a parameter called steps. This is great news because now you can use the steps object to easily access anything your officer submitted on the report! You’ll first refer to the first step with steps.one, then you can add any of the properties from your schema. For example, the Missing Person schema uses data.stillMissing to store the value indicating whether the person is still missing. The two possible values are missing and found, so we can use that in this filter step. Your function should return either true or false, so we can accomplish that with a simple if statement checking the first step’s stillMissing value, and returning a Boolean variable named isStillMissing:

Let’s “Save Step” and transform our data to a more usable format! Select the “plus” sign to add a step, then select “Transformation.”

In the Transformation step, we find a calculate function that receives the steps object and returns steps at the end. This is important because we can add properties to this steps object and use them in later steps. For example, we can take data from the Missing Person report in step 1 and assign them as easily accessible properties, such as steps.ageCategory and steps.location. In fact, we can even create a property called steps.smsMessage that will hold our entire text message to send later:

Don’t forget to return steps; at the end of your function, so your transformed steps object will be available in future steps.

Finally, we are ready to add some functionality! Let’s add our final step with the “plus” button and select “Send SMS.”

Here, we can write a message or use variables from previous steps to create a dynamic message. In this case, we added the steps.smsMessage property, so all we have to do is put that in the markdown for our Message Body!

Now we can enter the recipients. If we’d like a dynamic recipient (such as the reporting citizen’s phone number), it can be entered with a similar markdown syntax as we used for the body.

For this example, we created a user Group called Shift Supervisors, so this can be selected from the Group select box:

Save this step, then Save the entire Automation using the “Save” button at the top of the screen.

It will send you back to the Automations list – be sure to toggle the Automation to the “on” position to make it active:

Now, we’re ready to test it! Adding a new Missing Person report should send an SMS to the Shift Supervisors group:

A good idea is to click the Automation menu (three vertical buttons) and select “View Automation History” in order to retrieve the logs.

Each Automation Run will be listed in this log. You can click each log to see the results of each step. For debugging, you can use the log( ) function to write a value to this log. For example, writing log(steps.location) in the Transformation step would log the report’s location and help you ensure the property is being read correctly.

Congratulations! You built a simple Automation that included a Trigger, a Filter, a Transformation, and an automatic SMS Message in just a few minutes! Now you can see the power of SOMA Automations. Something that previously took hours, days, or weeks of engineering work can be accomplished with very little programming knowledge. Just another example of how SOMA is transforming the landscape of public safety technology!