Concept

Automation execution Context

An automation execution context ("Context") is a temporary data storage space that Mapsly creates when a workflow, button or schedule is invoked and keeps there the input data, like the record(s) for which a workflow or button was invoked, and data that accumulates over the course of the execution session, including runtime variables.

Automation execution Session

An automation execution session ("Session") is a process that starts when a workflow, button, schedule, or form event handler is invoked. Within a Session, Mapsly executes all the required condition/actions blocks, after which the Session completes.

If one of the button's actions is a Form, Mapsly brings up the Form for the user and continues to execute the remaining condition/actions blocks, after which the Session completes, even while the Form stays open. When the user triggers an event on the form for which a handler is defined, for example, clicks a form button or changes the selection in a picklist field, a new Session is started which completes when all condition/actions blocks of that event handler are executed.

Considerations on Using Forms

Only a button can bring up a form; forms invoked by a workflow, schedule or a form's event handler are ignored.

During one Session, a button can bring up only one form. All subsequent calls to Form actions are ignored.

Note. You may have multiple Form actions in your condition/actions blocks which are invoked in different branches of your automation logic, but only the first Form action that the execution flow encounters will be executed.

Relationship between Context and Session

When a workflow, button that doesn't bring up a form, or schedule is invoked, the Context that is created when execution begins is destroyed immediately after it completes. So in these cases, one Context is created per execution session and it doesn't persist after a session completes.

However, if a button brings up a form, the Context is not destroyed when the button's execution flow completes. Instead, all the form's event handlers are executed within the same Context, which serves as the persistent storage of the form's state and accumulated data between the execution of its event handlers.

Context structure and content

Initial content

A Context is a hierarchical JSON-object that looks like this:

Here's the list of typical objects available at its root level:

records and record: when a Context is created for a workflow or button that was invoked for a particular record or set of records, these two keys are always present:
- records contains the JSON-array of records for which the workflow or button was invoked, even if it is only one record - so your actions can work with any number of records in the same "bulkified" way;
- record contains the record for which the workflow or button was invoked, if it was one record; if a Context is created for a button that was invoked for multiple records, record will contain a random record out of this record set.
oldRecord is present only for a workflow triggered for an Update event (when a record is updated) and contains the old values of the record's fields.
currentMapslyUser contains information about the currently logged-in user and has the following structure:
- userId object contains the user's IDs in the data sources seen in the user's Preferences -> Personal
- location object contains the user's current location if requested by a Button's Make user's location available for actions setting and received from the user's device. Otherwise, all keys in the location object seen on the screenshot above are present with null values.
  
  When Mapsly successfully receives the GPS coordinates, it also attempts to reverse-geocode them into the address, and - if successful - it saves the address components to appropriate keys in the location object as well (see the screenshot above). If the reverse-geocoding was not successful, the address component fields will contain null values.
url contains the URL parameters passed in the Mapsly link.
filter contains the current values of the search bar filter.

Using Set() to create custom Context keys to pass data between actions

In any Twig template and Code statement, you may use the Set(param,value) function to add a custom key or JSON-object to the current level of the Context:

This way, you can pass custom data from one action to another, thus joining actions into a complex business process.

Action's nested Context key

To prevent name conflicts between actions, when an action starts, a nested Context object is created with a unique random key that will store the action's variables and resulting data:

If the action's API name is not empty, a copy of this object is also added under a key with the action's API name:

Also, when the action's execution completes, a copy of its nested Context will be available under the root-level lastAction, which is updated every time a subsequent action's execution completes. So you can always access the last action's data using the lastAction key.

Named Context keys

You may define a custom name under which the result of an action will be also available, which is useful in cases when you use the same action more than once over the course of one Session. To set a name for an action's Context key, while hovering over the added action's name press the Set button and enter the name:

Once a custom name is set, it will appear this way:

System fields in `record` / `records`

In the Context's record object, as well as every item in the records array, there are several system fields regardless of the object to which records belong:

__name: contains the full name of the record filled in from the mapped name field(s), or null if the name is not mapped in the record's object settings;
__address: contains the full address of the record (filled in from the mapped address fields), or null if the address is not mapped for the record's object settings;
__objectApiName: contains the API name of the object to which the record belongs;
__objectLabel: contains the label (visible name) of the object to which the record belongs.

Use these fields in actions that can be executed for various objects - to determine this data at runtime.

For example, to set the value of a polymorphic lookup field, you may use __objectApiName:
{"recordId": "{{ record.id }}", "object": "{{ record.__objectApiName }}"}

Here's how it will look in a Create record or Update record action's field list:

Accessing Context data in Twig templates

Context keys as Twig variables

When Mapsly starts evaluating every Twig template in your automation elements and Code statements, Mapsly adds all Context keys as read-only Twig variables, so you can access any key from the Context by its name. For example:

{{record.Account_Name}} will return the value of the record field with the API name Account_Name;
{{distance}} will return 8497.369 from the example Context above.

In case of a name conflict, the key that is more nested towards the current Context level takes priority.

In Twig, nested keys are properties in the object variable

You may access keys nested in a Context object as properties of an object. For example:

lastActions.someVariable returns the value of someVariable created in the last action's nested Context.

Example of using Context to pass data between actions

Example #1: Displays a message from a variable

In the example below a button's condition/actions block stores a message to be displayed and its style in the Context and the Show 'message' with 'style' Show message action (a system Show message action that comes with your Mapsly account out-of-the-box) displays the message. (If you have multiple different messages across your automation scenarios, you may use this approach to show various messages using one Show message action as opposed to creating separate Show message actions for each of your messages.)

Here is how the Show message action "reads" the message and style variables from the Context:

The content in the Message and Styling fields are simple Twig templates that read values from the message and style variables.

Example #2: Save the check-in distance to check-in record

In this example, we'll take a look at the out-of-the-box check-in button: when a user clicks the Check In button, Mapsly calculates how far away the user is from the location they're checking into, brings up a check-in form, and then stores this distance along with the verified flag to the check-in record. (The distance is calculated before a form is brought up to make it easier for the Mapsly admin to modify the process to prevent the user from checking in if they're too far away from the location.)

Here's the System Check In button:

Here we see that if the user's current location is received by Mapsly from the device and the location's geolocation accuracy is rooftop, Mapsly calculates the distance and saves it to the new Context key distance. Also, if the distance is within 1/4 of a mile or km (depending on the Mapsly account's distance unit), Mapsly saves 1 or 0 into the new Context key verified:

Then brings up the System Check-in form.

The OnClick handler of the form's Check In button calls the Create System Check-in record action, which saves the values from distance and verified into the check-in record's fields:

View Context content in detailed execution logs

You may view the content of the Context for every individual Session in the Execution logs section:

Please note that to see the Context, you need to have detailed logs enabled.