Build Procedure Templates

Procedure templates enable you to build a single template for a procedure that you can reuse with different adapters and values. After you build a procedure template, you can then create a procedure instance where you replace the variables with actual instances and values. This approach helps you build efficient and reusable procedures.

Build a Procedure Template

Procedure templates include a trigger that kicks off the procedure, steps that execute as a result of the trigger, and variables to represent input required to run an instance of the procedure. You can build procedures that use triggers that kick off when something happens to an adapter instance, you can schedule triggers, or you can manually kick off a trigger. See Procedure Triggers for more information about each component.

As you build a procedure, you also build context consisting of triggers, variables, steps, and values created by steps. You can refer to that context in later steps in the procedure. Consider each part as a building block that has a name and information that you can refer to. For example, in a procedure that sends an email notification for a new contact, you build the body of the email in one step. In a later step when you actually send the message, refer to the step where you built the body.

Note: Use these steps to get started building a procedure template. Consider using some of the example procedures to get a deeper understanding of how to build a procedure template.

Create a Procedure Template in the UI

  1. Open the Procedures page.
  2. Click Build New Procedure Template.

    Build New Formula

  3. Click Build New Procedure.

    Build New Formula button

  4. Enter a name for your procedure, and then click Create.

    Sugar Integrate provides you a list of triggers. For details about each trigger, see Procedure Triggers.

    Procedure Builder triggers

  5. Select your trigger.

    Note: If you need to change a trigger in a procedure template, you can delete it and start over. Deleting a trigger also deletes all following steps, so do so with caution.
    • Choose Event for a procedure triggered by an event configured on an adapter instance.
    • Choose Adapter Request for a procedure triggered when a specific request is made to an adapter instance.
    • Choose Scheduled for a procedure to occur at a specific time or regular interval.
    • Chose Manual to trigger the procedure with an API call to POST /formulas/instances/:id/executions.
  6. Complete the trigger properties, which vary based on the selected trigger.
  7. Click Save.

    Sugar Integrate shows the first trigger node in the procedure visualization.

    Viz Trigger

  8. Add any variables that you will need to run the procedure instance.
    1. Click Variables.

      Event Variables

    2. Select the type of variable, and then enter a name.

      Takes note of the Procedure Step Variable Name, which is how you will refer to the variable throughout the procedure.

    3. Click Save.
  9. Add your first step. In the procedure visualization, click Add a Step.

  10. Select the type of step that you want to add.

  11. Complete the step properties, and then click Save. For details on each step, see an Adapter Instance Variable.

    Note: Click Add From Existing to find a step to copy.

    Sugar Integrate shows the first trigger node and the step that you just created in the procedure visualization. The path from the trigger to the step defaults to On Success, but you can add failure steps later.

    Trigger

  12. To add another step, click the step, and then select one of the following:

    • Insert Above adds a new step prior to the current step with an On Success path connecting the two.
    • Add On Success adds a step for the procedure to continue to if the current step succeeds.
    • Add On Failure adds a step for the procedure to continue to if the current step fails.
  13. Continue adding steps until you complete the procedure template.

  14. Add a description by clicking Edit. See Add a Description to a Procedure Template.

  15. After you complete the procedure, test it.

Note: Sugar Integrate saves your procedure template in the background as you add each component.

Build a Procedure Template via API

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

{  
  "name":"Procedure Name",
  "description":"Procedure 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}"
      }
    }
  ]
}

Test Procedure Templates

You can test a procedure template as you build it. When you test a procedure template, you can either use an existing procedure instance or build a new procedure instance.

Tip: If you plan to use the procedure instance that you build while testing procedures only for testing, consider appending the name test to it.

To test a procedure template:

  1. At the top of the procedure visualization, click Setup Test. Setup Test
  2. Click Select Instance.
  3. Either choose an existing procedure instance (and skip down to the Select Trigger step) or click Add New Instance.
    1. Enter a name for the new procedure instance.
    2. For each variable, click the variable and add an adapter instance or enter a value.
    3. Click Create Instance.
    4. Select the instance that you just built.
  4. Click Select Trigger.
  5. Provide trigger information, depending on the type of trigger.

Create Variables

You can create two types of variables: Adapter Instance variables — replaced by adapter instances in the procedure instance — and Value variables — replaced by values entered in the procedure instance. When you create a variable, note the Procedure Step Variable Name which is how you refer to the variable in the procedure context. See Procedure Variables for more about variables in the procedure context.

To create a procedure variable:

  1. Open the procedure template. On the Procedures page, hover over the procedure card, and then click Open.
  2. Click Variables. Event Variables
  3. Select the type of variable to create.
  4. Enter a name for the variable. You can include spaces, but we remove the spaces to create the Procedure Step Variable Name (identified as key in the JSON), which is how you refer to the variable in the procedure context.
  5. Click Save.

Edit and Delete Variables

You can edit the name of a variable or remove a variable from a procedure template.

Note: You cannot delete a procedure variable if an instance of the procedure exists.

To edit or delete a procedure variable:

  1. Open the procedure template. On the Procedures page, hover over the procedure card, and then click Open.
  2. Click Variables. Event Variables
  3. Click Edit Variable.
  4. Select the variable to edit or delete, and then:
    • Edit the name, and then click Save. Or,
    • Click Delete.

Review and Replay Executions

You can troubleshoot procedure by reviewing executions. Executions button

The executions appear in three columns from left to right:

  • Procedure Executions — the list of executions of the selected procedure template. We identify failed executions in red.
  • Steps —The steps in the procedure and an icon showing their success Success or failure Failure.
  • Execution Values —the request and response details associated with the selected step.
Note: To review executions, you must have a procedure instance. Otherwise, the Executions button is unavailable.

To review executions:

  1. On the Procedures page, hover over the procedure card, and then click Open.
  2. Click Executions.
  3. Click the execution to review.
  4. Click the step to review.

To replay executions:

  1. On the Procedures page, hover over the procedure card, and then click Open.
  2. Enable debugging by clicking the Debugging toggle. 
  3. Click Select Instance
  4. Either select an existing procedure instance by clicking its corresponding plus sign button, or click the Create Procedure Instance button to create a new instance and define its variables. 
  5. After selecting an instance, click Run. As the execution runs, you can click individual steps in order to see the step's execution value.

Copy a Procedure Template

You can build a procedure template based on an existing template or from a Sugar Integrate sample procedure, resulting in a copy of the template.

To build a copy of a procedure template:

  1. Click Procedures, and then on the Procedures page, click Build New Procedure. Build New Formula
  2. Click Build From Existing Procedure.Build From Existing Procedure
    • To use one of your existing procedure templates, select the template.
    • To use a Sugar Integrate procedure template, click CE Sample Procedures, and then select the procedure.
  3. Enter a name for your procedure, and then click Create.

Import and Export Procedure Templates

You can export a procedure template as a JSON file and import other templates from their JSON source file.

To import a procedure template:

  1. Click Procedures, and then on the Procedures page, click Build New Procedure. Build New Formula
  2. Click Import. Import Formula
  3. Select the JSON file to import.
  4. Optionally rename the file, and then click Create.

To export a procedure:

  1. Navigate to the Procedures page.
  2. Hover over the adapter card, and then click Export.
  3. Save the file.

Parallel Executions

To help procedure instances execute as efficiently as possible, they take advantage of multithreaded executions. That is, multiple executions of the same procedure instance can make requests at the same time. Some API providers prevent multiple requests from the same account at the same time. If this happens, you can change a procedure template or an individual procedure instance to execute one step at a time. This makes the procedure less efficient and results in an increase in the execution time.

To change a procedure from the default multithreaded execution to single threaded:

  1. Open the procedure template. On the Procedures page, hover over the procedure card, and then click Open.
  2. Click Edit. Edit formula
  3. Click Show Advanced.
  4. Switch Single Threaded Execution on.
  5. Click Save.

Alternatively, in the procedure template or procedure instance JSON, update singleThreaded to true:

{
"singleThreaded": true
}

Rename a Procedure Template

To rename a procedure template:

  1. Open the procedure template. On the Procedures page, hover over the procedure card, and then click Open.
  2. Click Edit. Edit formula
  3. Rename the procedure template.
  4. Click Save.

Add a Description to a Procedure Template

Descriptions provide more information about a procedure template. Use the information to describe the procedure template use case and anything another user might need when creating a procedure instance.

To add a description to a procedure template:

  1. Open the procedure template. On the Procedures page, hover over the procedure card, and then click Open.
  2. Click Edit. Edit formula
  3. Describe the procedure template in Description.
  4. Click Save.

Delete a Procedure Template

You can delete a procedure template if the template has no instances associated with it. If the procedure template includes instances, delete those first.

To delete a procedure template:

  1. Navigate to the Procedures page.
  2. Hover over the Procedure Template card, and then click Delete.
  3. Confirm the deletion.

Deactivate a Procedure Template

You can deactivate a procedure template to prevent any executions of procedure instances of the template.

Note: You can also deactivate a specific procedure instance. See Deactivate a Procedure Instance.

To deactivate a procedure:

  1. Open the procedure template. From the Procedures page, hover over the procedure template card, and then click Open.
  2. Click Edit. Edit formula
  3. Switch the Active slider off. Active
  4. Click Save.

Access Procedure Information

Each procedure template and procedure instance exposes information about itself through the info object.

{
  "info":{
   "formulaId":"123",
   "formulaName":"name",
   "formulaInstanceId":"123",
   "formulaInstanceName":"name",
   "formulaExecutionId":"1234"
  }
}

Procedure information contributes to the procedure context. You can access the information with info.property, such as info.formulaInstanceId or info.formulaName.