Post-action operations

Explore the options for performing operations in Tessitura in response to interactions with your Links.

This content of this article have recently been moved This article is about the post-action functionality available for Tessitura. This functionality was previously specific to the 'Form Builder' action for Tessitura (now the Action Links 'Custom Form' action) but has been updated so that it can be used with all actions and integrations.

There are currently two different actions that your Action Links can take in response to an action event:

• Trigger a Local Procedure

• Create a CSI

A single form can trigger different actions based on how a user responds to the form, e.g. triggering different local procedures based on a user's response to a specific question. For each conditional action, in addition to specifying the details of the action itself, you can also set the conditions that must apply for the action to be performed, and customise the success messaging that will be displayed to the user (note that for the Local Procedure action you will have the option to vary the success messaging based on the response from your Procedure).

Submit actions will be evaluated in the order they appear in the Action Links console; the first submit action that fulfils the conditions you specify will be executed, and all other submit actions will be ignored. If none of the given actions fulfil their conditions when a user submits your form, an error message will be displayed. To avoid this, we recommend you always include a final submit action without conditions so that you can customise the error message that's displayed to your users.

Field	Details
Action label	Set a label for this submit action so that it's easier to identify the different actions when minimised. This label will not be visible to your users, it's only for internal use.
Submit action	Choose what should happen when a user submits the form, either triggering a Local Procedure, creating a CSI, redirecting the user, or displaying a message.
Success message	A message to display to the user after the relevant submit action has been completed. When triggering a Local Procedure, you can specify different success messages to display depending on the response from your Local Procedure (see below).
Conditions	Add conditions to denote whether this submit action should be performed. For each condition, specify the name of a field in your form, an operator, and if applicable, a value that should be compared against the value the user has provided. The submit action will only be executed if all of the conditions provided for it are met.

If a user is not logged in – Local Procedures and CSIs

Action Links provides the option to look up or create a Constituent for a user if they're not logged in when submitting the form. This enables you to:

• Work with a Constituent in your Local Procedure, without having to look up the user's email address or create a new Constituent record in the Local Procedure – Action Links will pass the Constituent ID to your Procedure as a parameter value

• Accept form submissions from users who don't have a record in Tessitura, by creating a new Constituent on the fly before appending a CSI

When triggering a Local Procedure, a value will always be passed to the procedure using the parameter name constituentId. If the Constituent ID for the user is not known, the value of constituentId will be 0.

If Require the user to log in is not checked and you choose to trigger a Local Procedure or create a CSI, you will be asked to choose an Action if user not logged in:

• No action (Local Procedure only) This will not attempt to look up the user or create a new Constituent, instead the constituentId parameter will have a value of 0.

• Search for Constituent email, else create new Constituent This will use the user's email address to search Tessitura Constituents and set the constituentId parameter to the ID of the first Constituent returned. If no Constituents are returned, it will create a new Constituent and set the parameter.

• Create new Constituent This will always attempt to create a new Constituent, regardless of whether a Constituent already exists for the user. Use this option if you want to have more granular control over how a Constituent is identified, by using your own merge procedures.

Email field required if searching for or creating a new Constituent

If you choose an action if user not logged in of 'search for Constituent email...' or 'create new Constituent', you must include a required field in your form with name email – the value of this field will be used to look up the user's Constituent, or will be used as the Electronic Address value if a new Constituent needs to be created.

If you choose to search for or create a new Constituent, you will need to provide the following:

Field	Details
Constituent Type ID	The ID of the Constituent Type to use if a new Constituent needs to be created. For Individuals, this is usually 1.
Electronic Address Type ID	The ID of the Electronic Address Type to use if a new Constituent needs to be created. For a primary email address, this is usually 1.
Electronic Address Allow Marketing status	If a new Constituent needs to be created, how to set the Allow Marketing value on the Electronic Address. This is a legacy feature in Tessitura and has been replaced by more granular Contact Permissions and Interests. The default value is false.
Source ID	If a new Constituent needs to be created, the ID for the Original Source to use.

Trigger a Local Procedure

Using forms to trigger Local Procedures can unlock all kinds of potential use cases. Some examples could include:

• Automating previously manual processes, e.g. enabling teachers to create an affiliation between their individual Constituent and organisation's Constituent records, or enabling customers to update their Gift Aid status

• Collecting additional data about customers, e.g. from patrons who weren't the primary booker for an event

• Internal tools, e.g. scanning against a guest list to update a special activity/constituent's attendance status

Field	Details
Procedure ID	The ID for the procedure that you want to trigger from TR_LOCAL_PROCEDURE.
Procedure name	The name of the procedure that you want to trigger, from the same record as the ID in TR_LOCAL_PROCEDURE
Procedure parameters	Define the parameters that you want to pass to your Procedure. Tessitura Stored Procedures will only run successfully if all of the parameters that are passed to them are referenced in the Procedure (passing parameters that aren't referenced, or not passing a referenced parameter will result in the Procedure failing to execute). Add each of the parameters that you want to pass to the Procedure, specifying the name that you'll use to reference it (e.g. specify schoolName if you want to reference it with @schoolName in your Procedure), and the path to the value for that parameter (e.g. School Name, or if it's nested in data from a third-party such as Algolia, use dot notation, e.g. School.School Name).
Conditional success messages	When triggering a Local Procedure, you can customise the success message that should display to the user based on the data that's returned by your Local Procedure. Local procedures always return a series (or 'array') of records, even if only returning a single record. When adding conditions for a success message, the value will be compared against the value of the first record for the column with the name you specify to determine whether a success message should be displayed. As with submit actions, we recommend that you include a success message without any conditions to avoid a scenario in which no success message is displayed. You can use markdown and HTML in your success messages, and can also interpolate data into the content, including from your the response from your Procedure (see below).

Interpolating data into your success message

One of the most powerful features of Action Links is the ability to interpolate data into your content, and this can also be used for your Form Builder success messaging. You can interpolate data either from parameters you've surfaced through the Pre-Action Layer for your Link (e.g. using {{ tessitura.firstName }}), or from the data you return from your procedure (by referencing the procedureResponse object).

Stored Procedures in Tessitura always return a series (or 'array') of table entries. With our powerful data interpolation functionality you can either display fields from a specific record that your Procedure returns, or use logical expressions to display data from multiple records. To do this:

Single record: You can reference a specific record using the 'index' value (the number of the record in the series) of that record. Most programming languages (including Handlebars, which we use below the hood) use 0 to reference the first entry in a series, followed by 1, 2, 3 and so on. So, for example, to reference a 'first_name' field on the first record in the response from a Stored Procedure you would use {{ procedureResponse.[0].first_name }}.

Data from multiple records: To display the data from multiple records you need to iterate through each of them. You can use the #each helper to do this, in combination with {{ this }} to reference an entry in your array. Here's an example where we display the first and last name for each record returned by our Procedure:

{{#each procedureResponse}}
  {{this.firstName}} {{this.lastName}}
{{/each}}

Service Pack update may overwrite Local Procedure records

It's possible for Tessitura Service Pack updates to overwrite the records in TR_LOCAL_PROCEDURES. If your Stored Procedure is no longer executing as expected when submitting a form, check the Local Procedure record hasn't been removed.

Use hidden fields to add extra validation

Include hidden fields in your form to add an additional validation layer to your Local Procedures. For example, let's say you sent an email to patrons asking them to update their Gift Aid status; you include the URL for your Action Link in the email, and populate hidden fields for constituent ID and email address by including them as parameters in the URL. These hidden field values will be passed to your Local Procedure where you can validate that the email address belongs to the Constituent you're updating, and in doing so verify that the URL hasn't been tampered with.

Local procedure responses – how we keep your data secure

It's possible that your local procedures will return data that you don't want your users to see – maybe you're returning a user's complete Constituent record, or a series of Constituents that the user doesn't necessarily have permission to view.

To ensure that your Tessitura data remains secure, we proxy the response from your Local Procedures, determining which success message to display based on the conditions you set, rather than returning the data directly to the user's browser.

Create a CSI

This submit action enables you to collect data from customers and attach it to their Constituent record by adding a Customer Service Issue (CSI). Users don't even need to log in – Action Links can look up or create a new Constituent record for you (see options above).

The Notes field of the CSIs added to Constituents will include the values of all of the fields in the form, in the format:

fieldName: This is the value
anotherFieldName: This is the value
yetAnotherFieldName: This is the value

In the future we hope to enable you to customise the format of the data added to the Notes field. If you'd be interested in this feature, let us know so we can move it's development up the roadmap.

When configuring this submit action, you'll need to provide the following settings for the CSIs to be added to Constituents:

Field	Details
CSI activity type ID	The Activity Type ID for the CSI that will be added to the Constituent.
CSI contact type ID	The Contact Type ID for the CSI that will be added to the Constituent.
CSI Has Reminder	Whether to flag the CSI as having reminders, the default is false.