How to create triggers using Connector Builder

A trigger is a powerful tool that automatically launches a workflow when a defined event happens. This enables you to automate complex business processes without having to manually run the workflow every time. 

There are two types of triggers:

1. Polling triggers

2. Webhook triggers

Let’s understand how to create them.

Polling Triggers

Polling triggers check for changes periodically, at regular intervals (e.g., every 5 minutes), in the destination app. This type of triggers may not send data to Built.io Flow in real-time. All the polling triggers are marked with 'Clock' sign in the triggers list.

To create a polling trigger, follow the steps given below:

Step 1: Navigate to your app directory and enter ‘flow create trigger {trigger_name}’ command.

You will be prompted to specify the version of the trigger. Make sure to append ‘v’ before the version number. (e.g., v1). Once you have entered the version number, hit ‘Enter’. 

Step 2: You will be prompted to specify if the trigger you want to create is a polling trigger. Enter ‘y’.

This will create a minimal template for the polling trigger under the specified version in your app directory.

You can create custom polling triggers using Connector Builder by following the structure given below:

module.exports =
{
 name: "sample_trigger",
 input:
 {
   type: 'object',
   title: 'Sample Trigger',
   description: "Short description",
   properties:
   {
     event:
     {
       type: 'string',
       enum: ['sample_trigger']
     }
   }
 },
  output:
 {
   "sample_trigger":
   {
     type: 'object',
     properties: {}      
   }
 },
   mock_input: {}, // add sample input data that will be used for testing
  execute:  function(input, options, output)
 {
   // will be called every 5 minutes
   // your code here
 },
  activate: function(input, options, output)
 {
   // This function will be called whenever the user activates the trigger/workflow. 
  // This function is useful in scenarios where you save cursor to figure out newly added/changed data in the
  // 3rd party services. You can update your cursor so that trigger won't fetch data of the period 
  // during which the trigger was deactivated.
 },
  validate:  function(input, options, output)
 {
   // This function will be called when the trigger is created. 
   // This function validates all inputs provided by the user and sends an error if any of the details (including auth) are incorrect. In case of an error, trigger server won't create the trigger.
 }
  mock_data: {}, // add sample output data that will be used for testing
}

The trigger structure has six main blocks:

1. input: Includes the definition of the trigger form input fields

2. output: Includes the definition of the output keys the trigger will return

3. mock_data: Includes the sample data to be used at the time of testing the trigger before deployment

4. execute: Includes the program logic that will run every five minutes in an active workflow

5. activate: Includes the program logic that is executed when a trigger/workflow is activated

6. validate: Includes the validations that are run when a user attempts to create a trigger

Let’s look at an example to understand more about these blocks.

Example

Let’s assume that you wish to create a trigger for a ‘Push’ event on Github. In the following steps, we will learn how to create this trigger with the help of Built.io Flow conventions. 

Request module: This is a Node.js module that lets you make simple HTTP calls to the third-party applications. You can use 'GET', 'POST', 'PUT', 'DELETE', and 'PATCH' method in the request module to perform specific operations. You need to define this module at the start of the code with the help of the require() function. We will learn more about this module in the latter section of this document.

1. input

This block includes the definition of the input fields displayed in the trigger configuration window in Built.io Flow UI.

Convention for input JSON schema

input:
 {
   type: 'object',
   title: 'Sample Trigger',
   description: "Short description",
   properties:
   {
     //input field definition
     event:
     {
       type: 'string',
       enum: ['sample_trigger']
     }
   }
 },

Let us understand more about this JSON schema:

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. title (required): Provide a title for the object.

3. description: Enter a short description about the trigger.

4. properties: The ‘properties’ object is used to define the fields of your trigger configuration window. It contains the definitions for:

  4. 1. Input fields to be displayed in the trigger configuration window

  4. 2. Event name to be displayed in the trigger service drop down lis

4.1 Defining trigger input fields

  To define a trigger input field, you will need to create an object for the input field with the following keys:

   - type (mandatory): The type of the input field. Supported input field types are ‘String’, ‘Object’, ‘Array’, ‘Boolean’, and ‘Any'

   - title (mandatory): The display name for the input field

   - minLength (optional): Used to mark the input field as mandatory. The value for this field should always be set to ‘1'

   - propertyOrder (optional): Used to specify the sequence of the input field in the trigger configuration window

   - lookup (optional): Used to mark the input field as a lookup field. The lookup input field has two keys:

                  1. id: Enter the id of the lookup field. This id should be same as the lookup_id specified in the lookup module.

                 2. dependencies: An array that defines the input field dependencies for the lookup field.

      Know more about lookups here.

  4.2 Defining Trigger event name

    To define a trigger event name, you will need to create an object with following keys:

  - type (mandatory): The data type of the event name.

  - enum (mandatory): An array that defines the name of the event to be displayed in the trigger service drop down list.

For our sample trigger, we need to define the following input field, as per the conventions mentioned above:
  - Repo (mandatory lookup field)

2. output

This block lets you define the output parameters that will be returned by the trigger and can be used by the subsequent actions.

Convention for output JSON schema

 output:
 {
   "sample_trigger":
   {
     type: 'object',
     properties: 
    {
     //output key definition  
    }      
   }
 },

Let us understand more about this JSON schema:

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. properties (properties): The ‘properties’ object is used to define the output fields returned by your trigger, which can be used in the subsequent actions.

2.1 Defining trigger output parameters
To define a trigger output field, you will need to create an object for the output field with the following keys:
  - type: The type of the output field. Supported input field types are: ‘String’, ‘Number’, ‘Boolean’, and ‘Any’
  - title: Enter the name of the output field.
  - displayTitle: Enter the display title to be shown in the trigger configuration window in Built.io Flow UI.

For our sample trigger we need following output fields:
  - repository, which is an object that contains ‘uuid’, ‘type’, ‘name’, and ‘full_name’ keys.

3. mock_input

This block lets you add a sample input data that can be used to test your trigger before your deploy it.

Convention for mock_input mock_input: {},

In our sample trigger, we need to provide the ‘Repository Name’ as an input for the trigger.

4. execute

This block lets you  write the entire trigger logic that will be executed inside the Built.io Flow engine, every five minutes. The function defined in this block will have three function parameters: 'input', ‘options’, 'output'.

Convention for execute block

execute: function(input, options, output)
 {
   // will be called every 5 minutes
   // your code here
 },

1. input: This parameter will fetch and handle the input data provided by user in the trigger form.

2. options: This parameter will reset the cursor to a new timestamp using the ‘setMeta’ method.

3. output: This parameter will inform the Built.io Flow engine that the trigger execution is completed.

Request module: It helps you to make HTTP calls to third-party applications. In order to do that, you need to provide values for the following keys:

- url: Provide the URL to which you wish to make HTTP request.

- headers: Pass the required values to create authorization/connection.

- method: Specify the HTTP method to be used to make an API call.

Error handler: Specify error handler function 'function (err,response,body)' for your trigger. If the trigger throws an error, it should return 'output(err)', and if the trigger is executed successfully, it should return 'output(body)'.

You can learn more about request module here.

The execution block for our sample trigger is given below:

5. activate

This block is called whenever the trigger or the workflow with which the trigger is associated is activated by the user. In a scenario where the trigger/workflow was deactivated and then activated again, it lets you update your cursor so that the trigger doesn’t fetch the data for the period during which it was deactivated. This is done using the ‘setMeta’ method.

Convention for activate block

activate: function(input, options, output)
 {
   // This function will be called whenever user activates the trigger/workflow. 
  // This function is useful in scenarios where you save cursor to figure out newly added/changed data in the 3rd party services. 
  //You can update your cursor so that trigger won't fetch data of the period during which the trigger was deactivated.
 },

The activate block for sample trigger is given below:

6. validate

This block contains the validation logic for the inputs (including auth) provided by the user in the trigger form and is called at the time of trigger creation. If any errors are encountered, an error will be displayed to the user and the trigger will not be created.

Convention for the validate block

 validate: function(input, options, output)
 {
   // This function will be called when the trigger is created. 
   // This functions validates all inputs provided by the user and sends an error if any of the details (including auth) are incorrect. 
   //In case of an error, trigger server won't create the trigger.
 },

The validate block for sample trigger is given below:

7. mock_data

This block contains the mock trigger output data which can be used to simulate how the trigger would work in real time and is used while testing the trigger before deploying it.

Convention for mock_data

 mock_data: {},

Once you have written the complete code for your trigger, you can proceed to create an authentication for your trigger using the ‘flow auth’ command. Click here to know how to create authentications using the Connector Builder.

Once you have deployed your custom app, you can start using the triggers  associated with the app by navigating to ‘Canvas > Start button > Trigger Services > {app_name}’.

Webhook Triggers

Webhook triggers keep checking for updates in the destination app continuously. It sends data to Built.io Flow in real-time, which enables your workflow to run as soon as the specified event occurs in an external app or service. This kind of trigger is called a webhook trigger.

To create webhook trigger, follow the steps given below:

Step 1: Navigate to your app directory and enter ‘flow create trigger {trigger_name}’ command.

You will be prompted to specify the version of the trigger. Make sure to append ‘v’ before the version number. (e.g., v1). Once you have entered the version number, hit ‘Enter’. 

Step 2: You will be prompted to specify if the trigger you want to create is a polling trigger. Enter ‘n’. This will create a minimal template for the webhook trigger under the specified version in your app directory.

The webhook trigger structure provided in the minimal template is given below:

module.exports = {
name: "Sample_trigger",
label: "Sample Trigger",
  input: 
{
    type: 'object',
    title: 'Sample Trigger',
    description: "Short description",
    properties: {
      event: {
        type: 'string',
        enum: ['sample_trigger']
      }
    }
  },
  output: 
    {
    "sample_trigger": {
      type: 'object',
      properties: {
      }
    }
  },
  mock_data: {}, // output of trigger data
  mock_input: {},
  execute: function (input, options, output) {
    // will be invoked when the event is triggered
    // to access auth info use input.auth , eg: input.auth.username
    // and to return output use output callback like this output(null, [{ mykey : 'key',   
       value : 'My Val'}])
    // output should be an array of objects or an empty array.
    // your code goes here
    output(null, []);
  },
  register: function (input, output) {
    // function will be used for registering webhook with services additional key
    // 'webhook' along with input data will be available here so you can access the  
       input.webhook
    // for registering the webhook
    output('failed');
  },
  unregister: function (input, options, output) {
    // will be invoked when user deletes the trigger for unregistering the webhook
    // webhook id will be available in input.webhookId
    // your code goes here
    output(null, true);
  },
  activate: function (input, options, output) {
    // this function will be called whenever user activate or reactivates flow
    // to access auth info use input.auth , eg: input.auth.username
    // you can use this function to reset your cursor or timestamp
    // your code goes here
    output(null, true);
  }
}

The webhook trigger structure has six main blocks:

1. input: Includes the definition of the trigger form input fields

2. output: Includes the definition of the output keys the trigger will return

3. mock_input: Includes the sample trigger input data that can be used at the time of testing the trigger before deployment

4. mock_data: Includes the sample trigger output data to be used at the time of testing the trigger before deployment

5. execute: Includes the program logic that will run each time the associated event is triggered.

6. register: Register the webhook with the web service.

7. unregister: Unregisters the webhook from the web service, when the associated trigger is deleted by the user.

8. activate: Includes the program logic that is executed when a trigger/workflow is activated

Let’s look at an example to understand more about these blocks.

Example

Let’s assume that you want to create a webhook trigger for a ‘New Item’ event in Wunderlist. In the following steps, we will learn how to create this trigger with the help of Built.io Flow conventions.

Request module: This is a Node.js module that lets you make simple HTTP calls to the third-party applications. You can use the 'GET', 'POST', 'PUT', 'DELETE', and 'PATCH' methods in the request module to perform specific operations. You need to define this module at the start of the code with the help of the require() function. We will learn more about this module in the latter section of this document.

1. input

This block includes the definition of the input fields displayed in the trigger configuration window in Built.io Flow UI.

Convention for input JSON schema

input: {
    type: 'object',
    title: 'trigger_title',
    description: "Short description",
    properties: {
      event: {
        type: 'string',
        enum: ['event_name']
      },
      input_field: {
        type: 'string',
        title: 'input_field_title,
        minLength: 1
        description: "Short description"
      }
    }
  },

Let us understand more about this JSON schema:

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. title (required): Provide a title for the object.

3. description: Enter a short description about the trigger.

4. properties: The ‘properties’ object is used to define the fields of your trigger configuration window. It contains the definitions for:

  4. 1. Input fields to be displayed in the trigger configuration window

  4. 2. Event name to be displayed in the trigger service dropdown list

4. 1 Defining trigger input fields

  To define a trigger input field, you will need to create an object for the input field with the following keys:

    - type (mandatory): The type of the input field. Supported input field types are ‘String’, ‘Object’, ‘Array’, ‘Boolean’, and ‘Any'.

    - title (mandatory): The display name for the input field

    - minLength (optional): Used to mark the input field as mandatory. The value for this field should always be set to ‘1'.

    - propertyOrder (optional): Used to specify the sequence of the input field in the trigger configuration window

    - lookup (optional): Used to mark the input field as a lookup field. The lookup input field has two keys:    

                   1. id: Enter the id of the lookup field. This id should be the same as the lookup_id specified in the lookup module.

                  2. dependencies: An array that defines the input field dependencies for the lookup field.

    Know more about lookups.

4.2  Defining Trigger event name

   output:
       {
          "sample_trigger":
          { 
            type: 'object',
            properties: 
          {
            //output key definition  
         }      
      }
 },
    

In our sample trigger, we need to provide the mock input as an input for the trigger.

4. mock_data

This block contains the mock trigger output data which can be used to simulate how the trigger would work in real-time and is used while testing the trigger before deploying it.

Convention for mock_data

In our sample trigger, we need to provide the mock output as the output for the trigger.

Once you have written the complete code for your trigger, you can proceed to create an authentication for your trigger using the ‘flow auth’ command. Read more on how to create authentications using the Connector Builder.

Once you have deployed your custom app, you can start using the triggers associated with the app by navigating to ‘Canvas > Start button > Trigger Services > {app_name}’.

5. execute

This block lets you  write the entire trigger logic that will be executed inside the Built.io Flow engine, whenever the trigger event occurs. The function defined in this block will have three function parameters: 'input', ‘options’, 'output'.

Conventions for the execute block

 execute: function (input, options, output) 
{
    // will be invoked when the event is triggered
    // to access auth info use input.auth , eg: input.auth.username
    // and to return output use output callback like this output(null, [{ mykey : 'key', value : 'My Val'}])
    // output should be an array of objects or an empty array.
    // your code goes here
    output(null, []);
  },

1. input: This parameter will fetch and handle the input data provided by user in the trigger form.

2. payload: This parameter will contain the payload sent by the web service application. 

3. output: This parameter will inform the Built.io Flow engine that the trigger execution is completed.

Request module: It helps you to make HTTP calls to third-party applications. In order to do that, you need to provide values for the following keys:

- url: Provide the URL to which you wish to make HTTP requests.

- headers: Pass the required values to create authorization/connection.

- method: Specify the HTTP method to be used to make an API request.

Error handler: Specify error handler function 'function (err,response,body)' for your trigger. If the trigger throws an error, it should return 'output(err)', and if the trigger is executed successfully, it should return 'output(body)'.

You can learn more about the request module.

The execution block for our sample trigger is given below:

6. register

This block is called when the user saves the webhook trigger through Built.io Flow UI. It registers the webhook URL with the associated web application and starts listening for the webhook trigger event.

Convention for register block

 register: function (input, output) {
    // function will be used for registering webhook with services additional key
    // 'webhook' along with input data will be available here so you can access the  
       input.webhook
    // for registering the webhook
    output('failed');
  },

The register block for sample trigger is given below:

7. unregister

This block is called when the user deletes the webhook trigger. This block unregisters the trigger from the web application.

Conventions for the unregister block

The register block for a sample trigger is given below:

8. activate

This block is called whenever the trigger or the workflow with which the trigger is associated is activated by the user. In a scenario where the trigger/workflow is deactivated and then activated again, it lets you update your cursor so that the trigger doesn’t fetch the data for the period during which it was deactivated. This is done using the ‘setMeta’ method. 

Conventions for the activate block

 
activate: function (input, options, output) 
{
    // this function will be called whenever user activate or reactivates flow
    // to access auth info use input.auth , eg: input.auth.username
    // you can use this function to reset your cursor or timestamp

    // your code goes here
 output(null, true);
  }

The activate block for sample trigger is given below: