How to create lookups using Connector Builder
A lookup field is a read-only field that fetches the list of your resources from an external app, based on the authorization selected. This eliminates the need to manually enter the unique IDs associated with your third-party account resources while configuring an action or trigger.
You can create lookups using Connector Builder by following the structure given below:
module.exports =
{
'name':'sample_lookup',
'label': 'label',
'execute': function (input, options, output)
{
// your code goes here
}
}
We will understand more about this structure with the help of an example.
Example
We will continue with the sample trigger example used in ‘How to create triggers using Connector Builder’. As per the example, we had defined a lookup field called ‘Repo Name’ in the trigger input form. In this example, we will learn how to define a lookup field in a trigger/action form.
Defining a lookup field in trigger/action form
You can define an input field as a lookup field, inside the properties object of the trigger/action input schema.
Convention for defining lookup field
{
type: 'object',
title: 'trigger/action_name'
description: "Short description",
properties:
{
field_name:{
type: 'string',
title: 'Display title for the input field',
minlength: 1,
lookup:{
id: 'lookup_id as specified in the lookup module'
dependencies: []
}
}
},
1. id: Enter the ID of the lookup field as specified in the lookup module. We will know more about the lookup module in a latter section.
2. dependencies: Enter an array containing the input field names on which the lookup depends.
In our sample trigger example, the trigger form looks like this:
Since the ‘Repository Name’ lookup field doesn’t depend on any other fields, the lookup definition will be:
Once you have defined the lookup field, you can add it to your actions and triggers. There are two ways to do so:
1. Using inbuilt commands
2. Creating lookup modules manually
Adding lookup using inbuilt commands
Built.io Flow provides inbuilt commands to add lookups in triggers and actions. To do so, follow the steps given below:
Step 1: Navigate to your app directory and enter the ‘flow attach lookup’ command.
Step 2: Select the lookup you want to use in your action or trigger from the list of lookup fields that appear.
Step 3: Next, specify whether you want to use the selected lookup to an action.
Step 4: Specify whether you want to use the selected lookup to a trigger.
Step 5: Select the action for which you want to enable lookup from the list of actions.
Step 6: Select the action field to which you want to add the specified lookup from the list of fields.
Step 7: Specify whether the selected lookup has any field dependencies.
Step 8: Select the field dependencies required for the selected lookup.
Step 9: Repeat steps 5 to 8 for adding lookup to a trigger.
Once this is done, lookup will be enabled for the specified field of the selected action and/or trigger.
Deleting lookup from action or trigger
You can remove the attached lookup from an action or trigger using the inbuilt command provided by Built.io Flow.
To do so, follow the steps given below:
Step 1: Navigate to your app directory, and enter the ‘flow detach lookup’ command.
Step 2: Specify whether you want to remove lookup from an action.
Step 3: Specify whether you want to remove lookup from a trigger.
Step 4: From the list of actions, select the action for which you want to disable lookup.
Step 5: Select the action field from which you want detach the lookup from the list of action fields.
Step 6: Select the trigger you want to delete the lookup from.
Step 7: Select the trigger field from which you want to detach the lookup from the list of trigger fields.
Once this is done, the lookup will be removed from the specified action and/or trigger.
Creating lookup modules manually
In this method, you need to create a lookup module in order to populate records in the defined lookup field in the input form. We'l continue with the previous example in which we have already defined a lookup field.
Convention to create a lookup module
module.exports =
{
'name': 'provide a lookup_id for the lookup module',
'label': 'label',
'execute': function (input, options, output)
{
// your code goes here
}
Lets understand more about this structure.
1. name: Provide a unique lookup_id you want to associate with the lookup module. Make sure you use the same lookup_id in the ‘id’ field while defining the lookup field in trigger/action input form.
2. execute: This block contains the entire logic to access and fetch the account resources of the currently logged-in user.
Request module: It helps you make HTTP calls to external applications. In order to do that, you need to provide values for the following keys:
- url: Provide the URL to which you want to make HTTP request to fetch the required account resources.
- headers: Pass the required values to create an authorization or connection.
- method: Specify the HTTP method to be used to make an API request.
- auth: Pass the user’s authentication credentials (username, password) required to access the user account.
Error handler: Specify error handler function 'function (err,response,body)' for your lookup. If the lookup throws an error, it should return 'output(err)'. If the trigger is executed successfully, it should return 'output(body)'.
You can learn more about request module here.
The execution block for our lookup module is given below:
Once you have created the lookup module for your defined lookup field, it will return an array of objects on execution.
Lookup module output
When you execute the lookup module, it returns an array of objects containing the details about the fetched records. Each of these record objects contain two important keys:
1. id: Returns the unique ID associated with the fetched record
2. value: Returns the display title associated with the fetched record.
You can use these keys in your execute block to populate your lookup input fields, as shown in the image below:
Once you have created your lookup module, you can test your trigger/action to see if its working as expected.
Enabling pagination for lookup module
When a lookup module is executed, it brings an array of objects (as key-value pairs) in the response. Without pagination, your lookup module can fetch only 10 objects from the response. Built.io Flow allows you to add pagination logic to your lookup module so that you can fetch the subsequent objects in batch of 10, from the response. To do this, you need to change the way the response is sent in your execute function callback.
Let’s understand this with the help of an example:
Let’s say you want to add pagination to the lookup module we just created. To do this, you will need to modify your execute block, as shown below:
var request = require('request');
module.exports = {
'name':'repo_list',
'execute': function (input, options, output){
const MAX_RESULTS = 10;
request({
url: "https://api.github.com/users/" + input.auth.username + "/repos",
method: 'GET',
headers: {
"content-type": "application/json",
"User-Agent": input.auth.username
},
auth: {
username: input.auth.username,
password: input.auth.password
}
qs: { limit: 10, skip: MAX_RESULTS * input.page_id }
},function(err, resp, body){
if(err){
output(err, null)
}
if(resp.statusCode !== 200){
output(body, null);
} else {
var body = JSON.parse(body);
var data = {};
var arr = [];
body.forEach(function(el){
arr.push({ id: el.name, value: el.full_name })
})
// to achieve pagination pass next_page: true in output response
// send the response to callback
const lookupResult = {
results: arr,
next_page: true
};
output(null, lookupResult)
}
})
}
}
This will add pagination to your ‘repo_list’ lookup module.
