Triggers, Steps, and Variables

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 a formula. For example, a JS Script step might build a JSON payload that you can refer to in a later step as ${steps.stepName}. Within a formula'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 section provides configuration information about each formula component.

JSON Example

You can build a formula with an API request to the POST /formulas endpoint. Your formula JSON includes the triggers, steps and variables that make up your formula. The configuration object contains your variables, while the triggers and steps objects contain their relevant information. See the sample file below:

{
  "name": "Formula Name",
  "description": "Formula Description.",
  "configuration": [{
      "name": "instanceName",
      "type": "elementInstance",
      "key": "instanceName"
    },
    {
      "name": "instanceName2",
      "type": "elementInstance",
      "key": "instanceName2"
    }{
      "name": "valueName",
      "type": "value",
      "key": "valueName"
    }
  ],
  "triggers": [{
    "type": "event",
    "properties": {
      "elementInstanceId": "${instanceName}"
    },
    "onSuccess": ["step1"]
  }],
  "steps": [{
      "name": "step1",
      "type": "filter",
      "properties": {
        "body": "done(trigger.event.eventType === 'UPDATED' && trigger.event.objectType === 'Contact');"
      },
      "onSuccess": [ "step2" ]
    },
    {
      "name": "step2",
      "type": "script",
      "properties": {
        "body": "done({\n  \"subject\": \"CRM Event Occurred\",\n  \"to\": \"recipient@cloud-elements.com\",\n  \"from\": \"sender@cloud-elements.com\",\n  \"message\": `${trigger.event.objectType} with ID ${trigger.event.objectId} was ${trigger.event.eventType}`\n});"
      },
      "onSuccess": ["step3"]
    },
    {
      "name": "step3",
      "type": "elementRequest",
      "properties": {
        "method": "POST",
        "elementInstanceId": "${instanceName2}",
        "api": "/messages",
        "body": "${steps.step2}"
      }
    }
  ]
}

Triggers

Triggers are the actions that kick off a formula. Triggers can be one of the following types:

• Event
• Element Request
• Scheduled
• Manual

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 a formula instance, refers to an element instance that is configured to use webhooks or polling to listen for events.

To set up an Event trigger:

• Specify the type as event.
• For elementInstanceId include the Element Instance Variable 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.

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

• CRM to Messages
• Add New Contact Created in One System to Another

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

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 a formula instance, refers to an element instance.

To set up an Element Request trigger:

• Specify the type as elementRequest.
• In properties:
  • For elementInstanceId, include the Element Instance Variable 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

Triggered at times specified by a Cron job. We recommend that you review the many reference pages for Cron jobs online.

In general, the Cron format consists of:

Examples

• Run each minute

      0 0/1 * 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 ? *
  

To set up a Schedule trigger:

• Specify the type as scheduled.
• For cron enter a cron string.

{
    "triggers": [{
        "type": "scheduled",
        "properties": {
            "cron": "0 0 12 ? * MON *"
        },
        "onSuccess": ["step1"]
    }]
}

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

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.

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

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

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

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

Step Types

You can choose from several different types of steps to make up your formula. You can refer to any step with the ${steps.stepName syntax}. Because you refer to the step by name, each step name must be unique within each formula. However, you can reuse a step name in a different formula.

You can use the following types of steps in your formulas:

• ActiveMQ Request
• Element API Request
• HTTP Request
• JS Filter
• JS Script
• Loop Over Variable
• Platform API Request
• Retry Formula on Failure
• Stream
• Sub-Formula

ActiveMQ Request

The ActiveMQ Request (amqpRequest) step type uses the AMQP protocol to post a message to an MQ server such as RabbitMQ.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "amqpRequest",
  "properties": {
    "exchange": "MQ server exchange",
    "body": "${steps.transform-event.response}",
    "queue": "queue",
    "url": "amqp://user:pass@host:10000/vhost"
    },
  "onSuccess": ["nextStepName"]
  }]
}

When you set up an ActiveMQ Request step, include the following information:

ActiveMQ Request Step Scope

ActiveMQ Request steps add the step execution values 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.

{
  "myAmqStep": {
    "request": {
        "body": "{\"message\":\"This is a test message.\"}",
        "url": "amqp://otqaqsml:tPpXwTl7-iMtezRmyJmD-y2U_XbroYpW@jaguar.rmq.cloudamqp.com/otqaqsml",
        "exchange": "main",
        "queue": "myqueue"
    }
  }
}

Example references to ActiveMQ Request scope:

• ${steps.myAmqStep.request}
• ${steps.myAmqStep.request.body}

Element API Request

The Element API Request (elementRequest) step makes an API call to a specific Element Instance.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "elementRequest",
  "properties": {
    "elementInstanceId": "${config.elementVariable}",
    "method": "POST",
    "api": "/messages",
    "headers": "Header content",
    "query": "query string",
    "path": "path string",
    "body": "Body content",
    "acceptableStatusCodes": "200,201",
    "retry": "true",
    "retryAttempts": "5",
    "retryDelay": "401",
    "retryStatusCodes": "500,501"
    },
  "onSuccess": ["nextStepName"]
  }]
}

To see an Element API Request step in action see:

• CRM to Messages
• Add New Contact Created in One System to Another
• Bulk Transfer CRM Data

When you set up an Element API Request step, include the following information:

Element API Request Step Scope

Element API Request steps add the step execution values 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.

{
  "myElementRequestStep": {
    "request": {
        "query": "{}",
        "body": "{\"Name\":\"New Account Name\"}",
        "method": "POST",
        "path": "{}",
        "uri": "/elements/api-v2/hubs/crm/accounts",
        "headers": "{\"authorization\":\"Element /ABC=, User DEF=, Organization GHI\",\"content-length\":\"14\",\"host\":\"jjwyse.ngrok.io\",\"content-type\":\"application/json}"
    },
    "response": {
      "code": "200",
      "headers": "{\"Set-Cookie\": \"CESESSIONID=2CA15552EE56EAF65BF1102F6CACEACC;Path=/elements/;HttpOnly\"}",
      "body": "{\"Id\": \"001tx3WcAAI\", \"Name\": \"New Account Name\"}"
    }
  }
}

Example references to Element API Request scope:

• ${steps.myElementRequestStep.request}
• ${steps.myElementRequestStep.request.body}
• ${steps.myElementRequestStep.response.code}

HTTP Request

The HTTP Request (httpRequest) step make an HTTP/S call to any URL/endpoint.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "httpRequest",
  "properties": {
    "method": "POST",
    "url": "https://mycoolapp.com/api",
    "headers": "Header content",
    "query": "query string",
    "path": "path string",
    "body": "Body content",
    "acceptableStatusCodes": "200,201",
    "retry": "true",
    "retryAttempts": "5",
    "retryDelay": "401",
    "retryStatusCodes": "500,501"
    },
  "onSuccess": ["nextStepName"]
  }]
}

When you set up an HTTP Request step, include the following information:

HTTP Request Step Scope

HTTP Request steps add the step execution values 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.

{
  "myHTTPRequestStep": {
    "request": {
        "query": "{}",
        "body": "{\"Name\":\"New Account Name\"}",
        "method": "POST",
        "url": "https://api.myservice.com:443/myresource",
        "path": "{}",
        "headers": "{\"authorization\":\"mysessionid\",\"content-type\":\"application/json}"
    },
    "response": {
      "code": "200",
      "headers": "{\"Set-Cookie\": \"CESESSIONID=2CA15552EE56EAF65BF1102F6CACEACC;Path=/elements/;HttpOnly\"}",
      "body": "{\"id\": \"237648\", \"name\": \"My New Resource Name\"}"
    }
  }
}

Example references to HTTP Request scope:

• ${steps.myHTTPRequestStep.request}
• ${steps.myHTTPRequestStep.request.body}
• ${steps.myHTTPRequestStep.response.code}

JS Filter

Use the JS Filter (true/false) (filter) step to write custom Javascript that must return true or false. As with all steps, you must include a name. See Javascript in Formulas for more information about working with Javascript in formulas.

Use JS Filter steps to specify only certain event types, field values, or other information. You can also use filters to split formulas into different paths.

• If a filter returns true, the formula executes the left, or OnSuccess , step.
• If a filter returns false, the formula executes the tight, or OnFailure , step.

{
        "name": "stepName",
        "onFailure": [],
        "type": "filter",
        "properties": {
            "body": "Javacript, for example: let status = trigger.args.status;\n\nif (status && status === \"COMPLETED\") {\n  done(true);\n} else {\n  done(false);\n}"
        },
        "onSuccess": ["nextStepName"]
}

To see a JS Filter step in action see:

• Add New Contact Created in One System to Another
• Bulk Transfer CRM Data

JS Filter Step Scope

JS Filter steps pass a boolean into the JS done callback function. That boolean is made available under the key titled continue, as shown in the examples below.

{
  "myFilterStep": {
    "continue": "true"
  }
}

{
  "myFilterStep": {
    "continue": "false"
  }
}

JS Script

Use the JS Script (script) step to write custom Javascript that must pass a valid JSON object to the done callback. As with all steps, you must include a name. See Javascript in Formulas for more information about working with Javascript in formulas.

{
    "steps": [{
        "name": "stepName",
        "onFailure": [],
        "type": "script",
        "properties": {
            "body": "Javacript, for example: done({\n  \"subject\": \"CRM Event Occurred\",\n  \"to\": \"recipient@gmail.com\",\n  \"from\": \"sender@cloud-elements.com\",\n  \"message\": `${trigger.event.objectType} with ID ${trigger.event.objectId} was ${trigger.event.eventType}`\n});"
        },
        "onSuccess": ["nextStepName"]
    }]
}

To see a JS Script step in action see:

• CRM to Messages
• Bulk Transfer CRM Data

JS Script Step Scope

JS Script steps add whatever object is passed to the JS done callback 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.

done({
  foo: 'bar',
  object: {
    someKey: 'someValue'
  }
});

Example references to JS Script scope:

• ${steps.myScriptStep.foo}
• ${steps.myScriptStep.object}
• ${steps.myScriptStep.object.someKey}

Loop Over Variable

Use the Loop Over Variable (loop) step to loop over a list of objects from a previous step or trigger. Set onSuccess to the first step in the loop. When you have reached the last step in the loop set the onSuccess field to the loop step, this will restart the loop for the next object. If you need to continue on after the loop is completed, set onFailure to the next step to execute after the loop is completed. For a loop step, onFailure is executed when the loop has been executed for all objects in the list.

{
    "steps": [{
        "name": "stepName",
        "onFailure": [],
        "type": "loop",
        "properties": {
            "list": "steps.step1.body"
        },
        "onSuccess": ["nextStepName"]
    }]
}

When you set up a Loop Over Variable step, include the following information:

Loop Over Variable Step Scope

Loop Over Variable steps make available the current object being processed and the index to each step executed inside of that loop. For example, if we have a loop step named looper, any steps that are run inside of that loop would have access to looper.index and looper.entry.

Example references to Loop scope:

• ${steps.myLoopStep.entry.id}
• ${steps.myLoopStep.index}

Platform API Request

The Platform API Request (request) step makes an API call to one of our platform APIs.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "request",
  "properties": {
    "elementInstanceId": "${config.elementVariable}",
    "method": "POST",
    "api": "/instances",
    "headers": "Header content",
    "query": "query string",
    "path": "path string",
    "body": "Body content",
    "acceptableStatusCodes": "200,201",
    "retry": "true",
    "retryAttempts": "5",
    "retryDelay": "401",
    "retryStatusCodes": "500,501"
    },
  "onSuccess": ["nextStepName"]
  }]
}

When you set up a Platform API Request step, include the following information:

Platform API Request Step Scope

Platform API Request steps add the step execution values 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.

{
  "myPlatformStep": {
    "request": {
        "query": "{}",
        "body": "{\"Name\":\"New Account Name\"}",
        "method": "POST",
        "path": "{}",
        "uri": "/elements/api-v2/hubs/crm/accounts",
        "headers": "{\"authorization\":\"Element /ABC=, User DEF=, Organization GHI\",\"content-length\":\"14\",\"host\":\"jjwyse.ngrok.io\",\"content-type\":\"application/json}"
    },
    "response": {
      "code": "200",
      "headers": "{\"Set-Cookie\": \"CESESSIONID=2CA15552EE56EAF65BF1102F6CACEACC;Path=/elements/;HttpOnly\"}",
      "body": "{\"Id\": \"001tx3WcAAI\", \"Name\": \"New Account Name\"}"
    }
  }
}

Example references to Platform API Request scope:

• ${steps.myPlatformStep.request}
• ${steps.myPlatformStep.request.body}
• ${steps.myPlatformStep.response.code}

Retry Formula on Failure

Retry Formula on Failure (retryFormulaExecution) retries a formula instance execution with the same input data. You can configure the number of retry attempts, with a maximum of 7 attempts. The retry time is set based upon an exponential backoff in minutes. The equation used for the exponential backoff is round(e^x) where x is the retry attempt number.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "retryFormulaExecution",
  "properties": {
    "retryAttempts": "5"
    },
  "onSuccess": ["nextStepName"]
  }]
}

When you set up a Retry Formula on Failure step, include the following information:

Retry Formula on Failure Step Scope

Retry Formula on Failure steps truncate the formula execution and schedule a retry execution for a later time based upon the retry attempt number. The result of this equation is used to schedule a retry in minutes. The step execution response value for this step is a string as shown in the example below.

{
  "id": "53067",
  "key": "retry.error",
  "value": "Formula instance execution scheduled for retry at approximately 2016-12-05T08:52:37-07:00"
}

In this example, the step name in the formula is retry, and the value of the step execution indicates the time when the formula execution will be retried.

Stream File

Stream File (elementRequestStream) steps move a file from one Element Instance to another. Stream Files steps configure two API requests instead of just one. One request downloads the date from an element instance, and the second request uploads the data to another. Use the response body of the download request as the request body of the upload request.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "elementRequestStream",
  "properties": {
        "uploadElementInstanceId": "${config.uploadElementVariable}",
        "uploadMethod": "POST",
        "downloadQuery": "Query string",
        "uploadQuery": "Query string",
        "uploadApi": "/bulk/${config.objectname}",
        "uploadHeaders": "${steps.previousStep.uploadHeaders}",
        "uploadFormData": "${steps.previousStep.formData}",
        "downloadMethod": "GET",
        "downloadElementInstanceId": "${config.downloadElementVariable}",
        "downloadHeaders": "${steps.previousStep.downloadHeaders}",
        "uploadFormDataName": "${steps.previousStep.formParameter}",
        "downloadApi": "/bulk/${trigger.args.id}/${config.objectname}"
    },
  "onSuccess": ["nextStepName"]
  }]
}

To see a Stream File step in action see Bulk Transfer CRM Data.

When you set up a Stream File step, include the following information:

Stream File Step Scope

Stream File steps add the step execution values 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.

{
  "myStreamStep": {
    "download": {
        "request": {
              "query": "{}",
              "method": "POST",
              "uri": "/elements/api-v2/hubs/crm/accounts",
              "headers": "{\"authorization\":\"Element /ABC=, User DEF=, Organization GHI\",\"content-length\":\"14\",\"host\":\"jjwyse.ngrok.io\",\"content-type\":\"application/json}"
          },
          "response": {
              "code": "200",
              "headers": "{\"Set-Cookie\": \"CESESSIONID=2CA15552EE56EAF65BF1102F6CACEACC;Path=/elements/;HttpOnly\"}"
          }
      },
      "upload": {
          "request": {
              "query": "{}",
              "method": "POST",
              "uri": "/elements/api-v2/hubs/crm/accounts",
              "headers": "{\"authorization\":\"Element /ABC=, User DEF=, Organization GHI\",\"content-length\":\"14\",\"host\":\"jjwyse.ngrok.io\",\"content-type\":\"application/json}"
            },
            "response": {
                "code": "200",
                "headers": "{\"Set-Cookie\": \"CESESSIONID=2CA15552EE56EAF65BF1102F6CACEACC;Path=/elements/;HttpOnly\"}",
                "body": "{\"Id\": \"001tx3WcAAI\", \"Name\": \"New Account Name\"}"
            }
        }
    }
}

Example references to Stream File scope:

• ${steps.myStreamStep.download.request.query}
• ${steps.myStreamStep.upload.request.headers}
• ${steps.myStreamStep.upload.response.body}

Sub-Formula

Sub-Formula (formula) steps run another formula instance.

{
"steps": [{
  "name": "stepName",
  "onFailure": [],
  "type": "formula",
  "properties": {
        "formulaId": "11448"
    },
  "onSuccess": ["nextStepName"]
  }]
}

When you set up a Sub-Formula step, include the following information:

Sub-Formula Step Scope

Sub-Formula steps add the values produced as the result of the last step in the sub-formula. Therefore, we recommend that when you build formulas to be used by other other formulas that you add a specific step to aggregate and returns whatever data is needed in the parent's formula context.

If the sub-formula requires variables, then those variables can either be set in the parent formula instance using the same config names or passed in via the subFormulaConfigs property. All sub-formulas inherit their parent formula's configuration values. If you pass in the subFormulaConfigs these are added to the list of existing configs from the parent and the sub-formula has access to the parent's configs and those passed in with the values in subFormulaConfigs taking precedence.

The args can be accessed in the sub-formula using trigger.args. The subFormulaConfigs can be accessed in the sub-formula using config for example: ${config.crmInstanceId}.

Formula Variables

Formulas include two types of variables that you must specify when you run a formula instance:

• Element Instance Variable: A variable that is replaced by a specific element when you run a formula instance.
• Value Variable: A variable that is replaced by a configurable value when you run a formula instance.

Formula variables are limited to the formula and cannot have the same name. However, you can name variables in different formulas with the same name like "originInstance" or "destinationInstance."