Formula Triggers

Formulas are comprised of: 

  • triggers that kick off formulas,
  • steps that the trigger executes, and 
  • variables used to define inputs to the formula instance

The triggers, steps, and variables build up context that you can refer to as you build an element. For example, a JS Script step might build a JSON payload that you can refer to in a later step as ${steps.stepName}. Within an element's context, you can refer to steps as as ${steps.stepName}, variables as ${config.variableName}, triggers as ${trigger.triggerComponent} (such as ${trigger.args} or ${trigger.event}), and formula metadata as ${info.metadataName}. Make sure that the dollar sign is outside of the curly brackets (${steps.stepname} not $steps.stepName) and that you don't take any shortcuts like ${stepName}.

This article provides configuration information triggers which can be one of the following types:

Event Event

You can set up triggers that listen for an event to happen on an element instance. To set up this trigger, you must use an Element Instance Variable that, when specified in an element instance, refers to a formula instance that is configured to use webhooks or polling to listen for events.

Event Trigger Setup

To set up an Event trigger, you must specify an Element Instance Variable. 

Set up a trigger in the UI

After you click to add an Event trigger, click Alt Text on the Edit event: "trigger" pane.

Edit Event trigger

Find or create a variable to represent the element instance that will kick off an element instance when an event occurs.

Set up a trigger with JSON

  • Specify the type as event.
  • For elementInstanceId include the Element Instance Variable (in the format ${config.variableName})that triggers the formula.
{
  "triggers": [
    {
      "type": "event",
      "properties": {
      "elementInstanceId": "${config.crmElement}"
    },
  "onSuccess": ["step1"]
    }
  ]
}

If an Event trigger's Element Instance is set up for polling instead of webhooks, then each object that is found while polling triggers a separate formula execution. For example, if the poller finds five changes, five different formula executions kick off.

Event Trigger Formula Examples

To see event triggers in action, see the following examples:

Event Trigger Scope

Event triggers add step execution values like those described in the example JSON below to the formula context. The formula context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your formula.

{
  "eventId": 11211123,
  "instanceId": 231232132,
  "type": "event",
  "event": {
    "date": "2016-06-01T04:09:10Z",
    "elementKey": "sfdc",
    "eventType": "UPDATED",
    "objectId": "n005i000003sgTd0AAE",
    "objectType": "Contact"
  }
}

Example references to Event trigger scope:

  • ${trigger.event.objectType}
  • ${trigger.event.eventType}

Element Request Element Request

Triggered any time a specific API call is made to a given Element Instance. To set up this trigger, you must use an Element Instance Variable that, when specified in an element instance, refers to a formula instance.

Set up a trigger in the UI

After you click to add an element Request trigger, click  on the Edit formula Request: "trigger" pane. Element request trigger setup

  1. Find or create a variable to represent the element instance that will kick off an element instance when an event occurs.
  2. In Method enter the API method of the API call, such as GET, POST, PUT, PATCH, or DELETE.
  3. In API enter the endpoint, such as hubs/crm/contacts.

Set up a trigger with JSON

  • Specify the type as elementRequest.
  • In properties:
    • For elementInstanceId, include the Element Instance Variable (in the format ${config.variableName}) that triggers the formula.
    • For method, specify a valid API verb. The API method of the API call, such as GET, POST, PUT, PATCH, or DELETE.
    • For api enter the endpoint, such as hubs/crm/contacts
{
   "triggers":[
      {
         "type":"elementRequest",
         "properties":{
            "method":"POST",
            "elementInstanceId":"${config.crmInstance}",
            "api":"/contacts"
         },
         "onSuccess":[
            "step1"
         ]
      }
   ]
}

Scheduled Scheduled

Triggered at times specified by a CRON job. We recommend that you review the many reference pages for CRON jobs online, such as Crontab Guru.

Note: The minimum scheduled frequency is 15 minutes.

In general, the CRON format consists of:

Minute
0-59
Hour
0-23
Day of Month
1-31
Month of Year
1-12
Day of Week
1-7
Monday-Sunday
Year
1900-3000
******

Example Cron Strings

  • Run every 15 minutes

        0 0/15 * 1/1 * ? *
    


  • Run every Monday at noon

    0 0 12 ? * MON *
    


  • 8.00 PM every weekday (Mon-Fri):

        0 0 8 ? * MON,TUE,WED,THU,FRI *
    


  • Midnight on 1st, 10th & 15th of month

    0 0 0 1,10,15 1/1 ? *
    


Set up a trigger in the UI

After you click to add a Scheduled trigger, enter the CRON values that represent the time the event should execute. 

  1. Open your formula's trigger from within the formula template and select Add Trigger.

  2. Select Add Schedule Trigger.

  3. From Create scheduled trigger settings, select a desired interval and click Save.
    Note: By default, the Allow concurrent formula executions option is unchecked to avoid any concurrent conflicts. To avoid issues with incomplete jobs, leave the option unchecked; this will allow scheduled jobs to initiate only after the previous job is completed without being duplicated, regardless of the scheduled intervals.

Set up a trigger with JSON

  • Specify the type as scheduled.
  • For properties.cron enter a CRON string. 
{
    "triggers": [{
        "type": "scheduled",
        "properties": {
            "cron": "0 0 12 ? * MON *"
        },
        "onSuccess": ["step1"]
    }]
}

Scheduled Formula Examples

To see a Scheduled trigger in action, see Bulk Transfer CRM Data.

Manual Manual

Triggered via a manual API call to POST /formulas/instances/:id/executions. Manual triggers do not require any specific configuration. You can use formulas triggered manually as synchronous API calls. See Formula as a Resource for setup instructions.

Additionally, you can cancel a trigger via PATCH /formulas/instances/executions/{executionId}, or by selecting the execution on the Executions tab and clicking Stop Execution; see our Formulas Platform API Reference for more information.

To set up a Manual trigger in JSON specify the type as manual.

{
   "triggers":[
      {
         "type":"manual",
         "properties":{

         },
         "onSuccess":[
            "step1"
         ]
      }
   ]
}

To see a Manual trigger in action, see Bulk CRM Transfer Data