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:

EntitiesPOST EndpointNotes
COMPETITION/competitions/{id}/entriesWhen someone enters a competition
CUSTOM/custom/{id}/eventsWhen a Custom event is posted
FORM/forms/{id}/membersWhen a Form is posted
FUNNEL/funnels/{id}/stepsWhen a Member is added to a Funnel
GAME/games/{id}/playsWhen a Game score is recorded
OFFER/offers/{id}/actions/unlock, /lock and /claimWhen an Offer is unlocked or claimed
ORDER/orderset/{id}/ordersWhen an Order is created
PAYMENT/orderset/{id}/paymentsWhen a Payment is recorded
RATINGWhen Rating is submitted
SURVEY/surveys/{id}/membersWhen a Survey is submitted
VOTE/votes/{id}/membersWhen a Vote is submitted
WALLET/wallets/{id}/transactionsWhen a Wallet transaction is added

Trigger Tasks

The following Trigger Tasks can be executed

Task Type
ACTIVITY_LOGLogs an Activity to the Activity Log. Note, this is such a common task that it's sometimes an option within the Entity Configuration
COMPETITION_ENTRYAdd an Entry to a Competition. If the Member already has Entered then the trigger is simply ignored
CUSTOM_POSTFire a Custom Event, which in itself probably has triggers attached.
FUNNELAdd the Member to a Funnel or move them forward in the Funnel
JOURNEY_STARTStart a Journey. If the Member is is already part of the Journey then this trigger is simply ignored
LIST_SETSets (adds, updates or clears) a List
MESSAGE_SENDSends a Message, such as an Email
OFFER_ACCESSLock or Unlocks a Personal Offer (not applicable for General Offers)
OFFER_CLAIMClaims an Unlocked Offer
SHEET_SETAdds or updates a Sheet row
SQLExecutes 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_TRANSAdds 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

  1. The Entity in the POST URL gets executed and is successful
  2. All triggers are then processed in order
  3. First the DimensionFilter is checked to see if the trigger should be run or not
  4. Then the DimensionFilter for the target Entity is checked
  5. If there is a runIfExpression it's checked next
  6. 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 attributeData TypeDescription
activityString(20), MandatoryThe Activity name, normally a verb (clicked, entered etc)
specificsString(50), OptionalAn optional additional activity key, such as the unique code
data.*list of optional key-value pairsAny 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 attributeData TypeDescription
data.*list of optional key-value pairsAny optional additional key-value pairs to store together with the Activity.