Overview

NEON enables you to set up automatic Triggers which get fired when certain POSTS in the Loyalty API are completed.

It's possible to define more than one trigger for an event. They will then get executed in order.

It's also possible to apply logic (runIfExpression) to control if a trigger should execute or not, for example, only send the welcome email for new Members. Triggers also have Dimension Filters, to allow different triggers to fire based on the passed-in Dimension values.

If a trigger fails the whole transaction (including the initial operation that caused the trigger to fire) get rolled back and an error is returned.

Triggers are part of NEON's Automation solution.

Note, triggers can have a severe impact on performance, especially if they are based on conditional execution scripts.

Note, triggers are fired also for bulk operations.

Entities which support Triggers

The following Entities and endpoints support triggers:

Entities	POST Endpoint	Notes
COMPETITION	/competitions/{id}/entries	When someone enters a competition
CUSTOM	/custom/{id}/events	When a Custom event is posted
FORM	/forms/{id}/members	When a Form is posted
FUNNEL	/funnels/{id}/steps	When a Member is added to a Funnel
GAME	/games/{id}/plays	When a Game score is recorded
OFFER	/offers/{id}/actions/unlock, /lock and /claim	When an Offer is unlocked or claimed
ORDER	/orderset/{id}/orders	When an Order is created
PAYMENT	/orderset/{id}/payments	When a Payment is recorded
RATING		When Rating is submitted
SURVEY	/surveys/{id}/members	When a Survey is submitted
VOTE	/votes/{id}/members	When a Vote is submitted
WALLET	/wallets/{id}/transactions	When a Wallet transaction is added

Trigger Tasks

The following Trigger Tasks can be executed

Task Type
ACTIVITY_LOG	Logs an Activity to the Activity Log. Note, this is such a common task that it's sometimes an option within the Entity Configuration
COMPETITION_ENTRY	Add an Entry to a Competition. If the Member already has Entered then the trigger is simply ignored
CUSTOM_POST	Fire a Custom Event, which in itself probably has triggers attached.
FUNNEL	Add the Member to a Funnel or move them forward in the Funnel
JOURNEY_START	Start a Journey. If the Member is is already part of the Journey then this trigger is simply ignored
LIST_SET	Sets (adds, updates or clears) a List
MESSAGE_SEND	Sends a Message, such as an Email
OFFER_ACCESS	Lock or Unlocks a Personal Offer (not applicable for General Offers)
OFFER_CLAIM	Claims an Unlocked Offer
SHEET_SET	Adds or updates a Sheet row
SQL	Executes a custom SQL statement. Note, be careful with this, since it may have severe impact on performance, cause deadlocks, or have undesired side effects such as updating information for the wrong Member.
WALLET_TRANS	Adds a transaction to a Wallet

Trigger Configuration

Triggers are part of the Entities' config structure, looking as follows:

{
  // Entity attributes...
  "config": {
    // Config attributes...

    "triggers": [ // List of triggers to be executed
      {
        "taskType": "MESSAGE", // The type of trigger. Mandatory.
        "entity": "@MyWelcomeMessage", // The Entity that will be triggered. Mandatory
        "runIfExpression": "_isNew", // An optional test for conditional execution
        "data": {
          // Optional attributes to send to the entity. They vary depending on the type of Trigger (taskType)
        }
      },
      {
        "taskType": "LIST_SET",
        "entity": "@ActiveMembers", // A Tag List
        "data": {
          "value": true
        }
      }
    ]
  }
}

Trigger Flow

The Entity in the POST URL gets executed and is successful
All triggers are then processed in order
First the DimensionFilter is checked to see if the trigger should be run or not
Then the DimensionFilter for the target Entity is checked
If there is a runIfExpression it's checked next
If any of the above checks fails, the trigger is simply ignored, otherwise it gets fired

Note that whilst triggers are executed in order, for bulk operations the platform may decide to execute Members in any order and perhaps run a trigger for all affected Members before moving to the next trigger.

A note about runIfExpressions: They may slow down execution substantially, and if the expression fails then the whole transaction is rolled back with an error.

Trigger Output

Some triggers may return a response which gets passed back through the REST API. This is to inform the calling application. An example of this is when claiming a Code offer, in which case the assigned digital code gets returned. See details for each trigger below.

The API response with Trigger output looks like this

{
  // The standard Loyalty API Post response...
  "content": { },

  "triggerOutput": { // Only present for Entities that have triggers
    "gifts": {
      // Any gifts, such as digital codes
    },
    "unlockedOffers": {
      // Any offers which have been unlocked
    },
    "instantWins": {
      // Any Winnings
    }
  }
}

Note, bulk operations don't return trigger responses.

Passing parameters to Triggers

The "data" attribute in the trigger configuration is used to pass the relevant information to the trigger. Each trigger type have their own parameter requirements, listed below.

The data attributes can either be hard coded, or be calculated through scripting. If scripting, the attribute value must start with the equal sign (=).

For example:

{
	"taskType": "LIST_SET",
  "entity": "@Profile", // A Data List
	"data": {
		"field1": "ABC", // Set field1 to the hardcoded value 'ABC'
    "field2": "=isNew", // A script which returns true if the Member has just been created
    "field3": "=CURRENT_TIMESTAMP", // Field3 is a Datetime field, which gets set to the current time
    "field4": 12, // Hardcoded integer
    "field5": "=5+7", // A script which evaluates to the integer value 12
    
    // Advanced formula, checks if a data structure passed in to the endpoint
    //   has a boolean set to use an alternative email. If so, pick the alternativeEmail
    //   from the myDataList Data List, otherwise use the email stored on the Member
    "field6": "=IN.data.useAlternativeEmail ? myDataList.alternativeEmail : ME.email"

		// Many Entitities take an optional "data" Json attribute which allows you to store additional information
    // To populate the data attribute, specify each attribute prefixed by 'data.'. This will be converted into a Json "data": { } structure
    "data.extra1": true,
    "data.extra2": "=ME.phone"
	}
}

Trigger Details

This section describes each individual trigger.

The ACTIVITY_LOG Trigger

Logs a new Activity to the Activity table.

Entity Reference: Can be any published Entity. If not specified, it defaults to the Entity for which the trigger is defined.

Data attributes:

Data attribute	Data Type	Description
activity	String(20), Mandatory	The Activity name, normally a verb (clicked, entered etc)
specifics	String(50), Optional	An optional additional activity key, such as the unique code
data.*	list of optional key-value pairs	Any optional additional key-value pairs to store together with the Activity.

This trigger does not return a response, and shouldn't throw any errors.

The COMPETITION Trigger

Enters a Competition or Instant Win.

Entity Reference: The Competition to enter.

Data attributes:

Data attribute	Data Type	Description
data.*	list of optional key-value pairs	Any optional additional key-value pairs to store together with the Activity.