Procedure Step Types

You can choose from several different types of steps to make up your procedure. 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 procedure. However, you can reuse a step name in a different procedure.

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

ActiveMQ Request ActiveMQ Request

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

ActiveMQ procedure step
{  
  "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:

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
URL
url
Specifies the AMQP URL endpoint of the MQ Server. The structure of the URL is specified in RabbitMQ URI Specification.
Y
Queue
queue
Indicates the name of the queue of the MQ server to which the message should be posted.
Y
Message
body
The JSON payload to post to the server.
Y
Exchange
exchange
The name of the MQ server exchange to which the message should be posted.
N

ActiveMQ Request Step Scope

ActiveMQ Request steps add the step execution values described in the example JSON below to the procedure context. The procedure context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your procedure.

{
  "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}

Adapter API Request Adapter API Request

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

Adapter API Request
  {  
  "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 Adapter API Request step in action see:

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

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
Adapter Instance Variable
elementInstanceId
Specifies the adapter instance that receives the API call.
Y
Method
method
The API method of the API call, such as GET, POST, PUT, PATCH, or DELETE.
Y
API
api
The endpoint, such as hubs/crm/contacts.
Y
Headers
headers
The headers to pass along as part of the API request. You rarely need to add anything to the headers, but you can use this parameter to pass common header information such as content types.
N
Query
query
Any query parameters, such as a CEQL query or pagination, to pass as part of the API request.
N
Path
path
Support earlier procedures where path defined variables, such as an {ID} variable in an endpoint. In the latest version, the path parameter is unnecessary.
N
Body
body
Specifies the JSON body to send with the related request. Construct the JSON body in another step and refer to it in the body parameter. For example, ${steps.previousStep.body}.
N
Acceptable Codes
acceptableStatusCodes
A comma-separated list (200,201) of codes, range (200-205), or both (200-205,208) returned in the response that indicates success.
N
Retry on Failure
retry
Indicates that we should retry a configurable number of times if the request fails.
N
Max Retry Attempts
retryAttempts
The maximum number of times to retry the request.
N
Retry Delay
retryDelay
The time in milliseconds to wait between retries.
N
Retry Status Codes
retryStatusCodes
A comma-separated list (500,502) of codes, range (400-415), or both (400-415,500,502) returned in the response that indicates that we should retry the request.
N

Adapter API Request Step Scope

Adapter API Request steps add the step execution values described in the example JSON below to the procedure context. The procedure context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your procedure.

 {
  "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 Adapter API Request scope:

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

HTTP Request HTTP Request

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

HTTP Request
 {  
  "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:

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
Method
method
The API method of the API call, such as GET, POST, PUT, PATCH, or DELETE.
Y
HTTP/S URL
url
The full URL of the request.
Y
Headers
headers
The headers to pass along as part of the API request. You rarely need to add anything to the headers, but you can use this parameter to pass common header information such as content types.
N
Query
query
Any query parameters, such as a CEQL query or pagination, to pass as part of the API request.
N
Path
path
Support earlier procedures where path defined variables, such as an {ID} variable in an endpoint. In the latest version, the path parameter is unnecessary.
N
Body
body
Specifies the JSON body to send with the related request. Construct the JSON body in another step and refer to it in the body parameter. For example, ${steps.previousStep.body}.
N
Acceptable Codes
acceptableStatusCodes
A comma-separated list (200,201) of codes, range (200-205), or both (200-205,208) returned in the response that indicates success.
N
Retry on Failure
retry
Indicates that we should retry a configurable number of times if the request fails.
N
Max Retry Attempts
retryAttempts
The maximum number of times to retry the request.
N
Retry Delay
retryDelay
The time in milliseconds to wait between retries.
N
Retry Status Codes
retryStatusCodes
A comma-separated list (500,502) of codes, range (400-415), or both (400-415,500,502) returned in the response that indicates that we should retry the request.
N

HTTP Request Step Scope

HTTP Request steps add the step execution values described in the example JSON below to the procedure context. The procedure context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your procedure.

 {
  "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 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 Procedures for more information about working with Javascript in procedures. 

JS Filter
 {  
  "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"
  ]
}

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

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

To see a JS Filter step in action see:

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 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 Procedures for more information about working with Javascript in procedures.

JS script
 {  
  "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"
      ]
    }
  ]
}

 Use JS Script steps to build objects to use in request steps for query parameters or the request body.

Note: If you use console.log in a JS Script step, the output is added to the body of the step. If you reference the script step in another step as just ${steps.stepName}, the console.log output is added to the step context and can cause errors. Prevent this by declaring what to include in the step body by adding it to done. For example, done({body.variableName}).

To see a JS Script step in action see:

JS Script Step Scope

JS Script steps add whatever object is passed to the JS done callback to the procedure context. The procedure context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your procedure.

 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 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.steps1.body}"
      },
      "onSuccess":[  
        "nextStepName"
      ]
    }
  ]
}

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

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
List
list
A reference to a previous step that provides a list of items to loop through.
Y

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 Alt Text

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

Platform API Request
 {  
  "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:

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
Adapter Instance Variable
elementInstanceId
Specifies the adapter instance that receives the API call.
Y
Method
method
The API method of the API call, such as GET, POST, PUT, PATCH, or DELETE.
Y
API
api
The endpoint, such as hubs/crm/contacts.
Y
Headers
headers
The headers to pass along as part of the API request. You rarely need to add anything to the headers, but you can use this parameter to pass common header information such as content types.
N
Query
query
Any query parameters, such as a CEQL query or pagination, to pass as part of the API request.
N
Path
path
Support earlier procedures where path defined variables, such as an {ID} variable in an endpoint. In the latest version, the path parameter is unnecessary.
N
Body
body
Specifies the JSON body to send with the related request. Construct the JSON body in another step and refer to it in the body parameter. For example, ${steps.previousStep.body}.
N
Acceptable Codes
acceptableStatusCodes
A comma-separated list (200,201) of codes, range (200-205), or both (200-205,208) returned in the response that indicates success.
N
Retry on Failure
retry
Indicates that we should retry a configurable number of times if the request fails.
N
Max Retry Attempts
retryAttempts
The maximum number of times to retry the request.
N
Retry Delay
retryDelay
The time in milliseconds to wait between retries.
N
Retry Status Codes
retryStatusCodes
A comma-separated list (500,502) of codes, range (400-415), or both (400-415,500,502) returned in the response that indicates that we should retry the request.
N

Platform API Request Step Scope

Platform API Request steps add the step execution values described in the example JSON below to the procedure context. The procedure context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your procedure.

{
  "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 Procedure on Failure Retry Formula on Failure

Retry Procedure on Failure (retryFormulaExecution) retries a procedure instance execution with the same input data. You can configure the number of retry attempts with a maximum of 4 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.


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

Parameter
Description
Required
Name
name

Y
Max Retry Attempts
retryAttempts
The maximum number of times to retry the request.
N

Retry Procedure on Failure Step Scope

Retry Procedure on Failure steps truncate the procedure 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": "procedure instance execution scheduled for retry at approximately 2016-12-05T08:52:37-07:00"
}

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

Stream File Stream File

Stream File (elementRequestStream) steps move a file from one Adapter Instance to another. Stream Files steps configure two API requests instead of just one. One request downloads the date from an adapter 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. 

Stream File
 {
  "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:

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
Download/Upload Adapter Instance Variable
uploadElementInstanceId/downloadElementInstanceId
Specifies the adapter instance that receives the API call.
Y
Download/Upload Method
uploadMethod/downloadMethod
The API method of the API call, such as GET, POST, PUT, PATCH, or DELETE.
Y
Download/Upload API
uploadApi/downloadApi
The endpoint, such as hubs/crm/contacts.
Y
Download/UploadHeaders
uploadHeaders/downloadHeaders
The headers to pass along as part of the API request. You rarely need to add anything to the headers, but you can use this parameter to pass common header information such as content types.
N
Download/UploadQuery
uploadQuery/downloadQuery
Any query parameters, such as a CEQL query or pagination, to pass as part of the API request.
N
Upload Form Data
uploadFormData
Specifies the form data to send with the related request. Construct the form data in another step and refer to it in the Upload Form Data parameter. For example, ${steps.previousStep.formdata}.
N
Upload Form Parameter Name
uploadFormDataName
Specifies the name of the form parameter.
N

Stream File Step Scope

Stream File steps add the step execution values described in the example JSON below to the procedure context. The procedure context is then passed from step-to-step, allowing you to use these values in any subsequent steps in your procedure.

 {
  "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-ProcedureSub-Formula

Sub-procedure (procedure) steps run another procedure instance. 

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

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

Parameter
Description
Required
Name
name
The name of the procedure step. The name must be unique within the procedure.
Y
Sub-Procedure (ID)
formulaId
The ID of the procedure.
Y
args
Any values that should be made available to the sub procedure.
N
subFormulaConfigs
Any variables required for the sub procedure.
N

Sub-Procedure Step Scope

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

If the sub-procedure requires variables, then those variables can either be set in the parent procedure instance using the same config names or passed in via the subFormulaConfigs property. All sub-procedures inherit their parent procedure's configuration values. If you pass in the subFormulaConfigs these are added to the list of existing configs from the parent and the sub-procedure 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-procedure using trigger.args. The subFormulaConfigs can be accessed in the sub-procedure using config for example: ${config.crmInstanceId}.