Pre-action layer

Limit who can access individual Links and surface data from integrated systems to use in your content.

This functionality has only just been released This article is about the pre-action layer, a new feature that was recently released. We're still building in new features to this functionality and so this documentation may not be fully up-to-date.

The pre-action layer adds powerful functionality to your Links, allowing you to set rules to denote who can access a Link, and to surface data that can then be used to add conditional logic and interpolation to your content.

The pre-action layer is part of a wider strategy for the Action Links architecture, which also includes a 'post-action layer'. Where the pre-action layer enables you to fetch data from your integrations that you can use as part of an action, the post-action layer enables you to trigger events based on user interactions with your actions, e.g. to trigger an email to send or to save data back to an integrated system.

Diagram showing the 'layers' of the Action Links architecture

The pre-action layer and post-action layers are action-agnostic – that is, they sit across all actions, allowing you to use one integration to surface data (e.g. customer data from Tessitura) and another to power the Action (e.g. an Interactive Map with Airtable).

By constructing the Action Links architecture in layers we're able to build complex functionality once and deliver it across all of the available actions to serve a wide range of potential use cases.

Authorisation rules

With authorisation rules you can specify a set of requirements that the user must meet in order to access your Link, such as being logged in or having an account with sufficient privileges. These rules are evaluated before the action-specific content of the Link is rendered, therefore acting as an authorisation layer that can either grant or deny access.

In addition to specifying rules, you can also define what should happen if a rule fails – either redirecting the user (e.g. to a Log in or Register action), or displaying a message (e.g. to inform the user that they don't have sufficient privileges).

Authorisation rules are evaluated one after the other, in the order you configure them in the settings for your Link. For efficiency, when a failing rule is encountered, any further rules will be ignored. The 'no match' settings for the first failing rule will therefore be actioned.

Authorisation rules can increase Link load times It's important to only add authorisation rules that are necessary to evaluate whether the user should be able to access a Link. Although pre-action events are designed to be efficient (i.e. if necessary to make the same request to an integrated system to evaluate two different parameters, they will only make the request once), each parameter can require separate requests to an integrated system to get the relevant data. These requests are often made synchronously (one after the other) to avoid making any requests that aren't necessary because of an earlier failing rule.

Custom parameters

Custom parameters enable you to identify parameters to use in your authorisation rules / to surface data that are not available as one of the default parameter options.

Action Links supports the JMESPath language to enable you to write functions that target specific subsets of an available data point, and even sort or reformat the returned data. You can use the JMESPath Validator to help write your queries.

Surfacing data

In addition to to controlling whether a user should be able to access a particular Link, you can also surface data from integrated systems to use in your Actions and content.

For each integration option, select an account and check the boxes for the data points you want to surface to your Link. For security, Action Links will only be able to surface data that the user has been sufficiently authorised to access. To do this we use a process of 'incremental authorisation' where, for example, a user logging in to an account may give more access to that user's data than simply providing a customer ID and/or email address as parameters in the URL.

You can apply logic and interpolation to your content by including an expression in between double curly braces ({{ }}).

When interpolating surfaced data (see below) into your content, you can access the data by referencing the name of the field as a child of the product object. You can do this using 'dot notation', providing the name of the product to access the product object (e.g. tessitura) followed by a dot (.) followed by the name of the data point you want to access (e.g. firstName).

For example, to access a first name that you've surfaced from Tessitura, you would use {{ tessitura.firstName }} to interpolate that data into your content.

As with authorisation rules, you can use custom parameters to surface data points that are not available as one of the default parameter options. JMESPath functions can return arrays and objects, as well as singular values. When interpolating data, unless using logical expressions (e.g. #each) to iterate through the returned data, Handlebars will only accept a singular value. If your custom parameter returns an array or object and you want to interpolate its data into your content you should use the Handlebars index syntax (e.g. {{ tessitura.customParameterName.[0]) to target a specific value.

Surfacing data can increase Link load times

As with authorisation rules, surfacing data can increase the time it takes for a Link to load. You should therefore only surface parameters that you are going to use in a Link to define logic or interpolate into your content. Also note that when a Link receives a significant amount of traffic, this may increase the load on the systems you're surfacing the data from.

Interpolating data

Action Links uses the Handlebars templating syntax to enable you to apply logic and interpolate data into your content. The pre-action Layer is available across all actions, regardless of product, allowing you to surface data from one system and interpolate it as part of an action that integrates with another system. For example, you could display a logged-in user's first name from Tessitura as part of the Interactive Map action (that integrates with Airtable).

Currently only a specific selection of content fields support data interpolation, but as a minimum this includes the primary page content field of all actions.

To interpolate the data, simply use the handlebar structure {{ product.fieldName }}. When configuring your Links you'll see a list of the available parameters that can be surfaced, including those that are surfaced automatically as part of the standard delivery of that action.

Action Links also supports Handlebars' built-in helpers, enabling you to make your content conditional to the values of surfaced data (using #if), to iterate through series (or 'arrays') of content (using #each), and more.

Handlebars helpers

Action Links provides helpers that you can use to apply functions when interpolating data. Helper functions are written in the format {{helperName data arg1 arg2}}, where helperName is the name of the helper, data is the reference for a data parameter you've surfaced to your action, and arg1 arg2 represent arguments that you pass to the helper. Note that not all helpers require you to pass arguments.

Name	Details
dates	This helper makes the popular day.js library available to your Handlebars functions. To invoke a function, pass the data, the method and then any arguments you want to provide to the method. The JavaScript equivalent of the example below would be written: dayjs(tessitura.nextPerformanceDate).format('dddd D MMMM YYYY') Example: {{dates tessitura.nextPerformanceDate 'format' 'dddd D MMMM YYYY'}}
toSentence	Converts an array of string values into a sentence format. For example, passing the array ["a", "b", "c"] would return a, b, and c. Example: {{toSentence tessitura.interestNames}}
or	Enables you to return the first truthy value in an array. For example, passing the array [false, null, 123] would return 123. Example {{or tessitura.constituentId form.constituentId}}

Errors in your Handlebar functions can cause your Links to not load

Be cautious when using Handlebar helpers or complex custom queries to surface data or authorise users – syntax errors or mishandling data can cause your Links to not render correctly. If you're experiencing an error when trying to load your Links, first check that your Handlebars functions aren't the source.

Allowed URL parameters

URL parameters enable you to pass data to your forms and integrations, such as a user's account id or email address. Because URL parameters are able to automatically override any default value set for a form field with a matching name, it's necessary to define which URL parameters you want to allow for this purpose, to avoid users unexpectedly overriding these values.

Find out more about using URL parameters with forms

Be careful when using URL parameters in your content

Other than in very specific circumstances, you should avoid interpolating values into your content that can be overwritten with URL parameters. If a user is able to specify a URL parameter and this is displayed in the content, scammers may be able to use this to exploit your users.