How to Create and Configure an HTTP Connector Function

Learn how to navigate the Connector Function modal and creation process.

Overview

Connector Functions are a feature for structuring how Tulip applications interact with external servers and services. If a Connector is the general connection between Tulip and the external server, connector functions are specific requests for services or information. In this article we’ll walk you through how to create and configure a connector function to access specific pieces of data or information from an external service.

For information on the basics of APIs, review this article on How to Use an API.

Set Up

Before creating a connector function, you’ll need to create an HTTP connector to create a connection between your apps and the service you’d like to communicate with. You’ll create your connector functions within this connector, and each connector function within a connector will share its parent connector’s configuration. To create an HTTP Connector, follow the steps in this article: How to Configure a Connector.

Once you’ve created a Connector, it’s time to create connector functions. Connector functions are the individual operations that your connector goes through to pull data from the API server you’re connecting to.

Create a Connector Function

From the Connectors page, select the Connector you want to work with by clicking on its name.

This page shows a list of functions associated with the connector. To create a new connector function, click + Create Function.

To keep things short, in this article we’ll assume that you already know the different parts of the Connector Function Editor.

Here’s the process we’ll use to set up a connector function:

1. Select the API Call type
2. Write the API URL
3. Set the inputs
4. Define the parameters for the data returned
5. Set the outputs using Dot Notation

Call Type and URL

The first two items to configure for any HTTP connector function are the API call type (GET, POST, PUT, etc.) and the endpoint URL. Select from the list of call types by using the drop down, and enter the endpoint path in the field following the base URL. Consult the API documentation for the service you’d like to connect to for a list of endpoint and configuration details.

In this article, we’ll be using the Document360 API as an example, which is the service that hosts Tulip’s Knowledge Base. The function we’re setting up returns an article along with their associated properties based on the article’s ID.

Let’s name our function, set the call type (GET), and type in the URL for the call:

Obtain the call type and URL from endpoint documentation of your system. These two actions determine your REST request. For a detailed outline of what a REST request is, see Anatomy of a REST Request.

Clicking Test runs the function and returns information in the Test Results section of the editor. By selecting Body under Test Results, you can view the full, unfiltered result of your request. Great, we have data!

Inputs

The way our connector function is currently configured, we can only get one specific article ID.

Our goal with this function is to configure it such that it returns information on any article we’re interested in. To do this, we’ll need to edit our function to allow us to pass a value for any given article ID.

We can edit our connector function to take any value by configuring Inputs. Inputs allow you to take values from your applications and pass them into connector functions.

Inputs are configured in two parts: 1.) creating an input in the input pane, 2.) specifying where that input will be used in the connector function.

First, add a field to the input pane. You can edit an input’s data type by clicking on the icon next to the Input name. Ensure that the type you select matches the type of the source you’ll use in your applications. The field next to the input name can be used for testing values you’d like to pass into your connector function, and can simulate inputs from your applications.

Next, we’ll need to specify where that input will be used in our connector function. Inputs can be accessed throughout a connector function, including in the endpoint URL, query parameters, and within JSON extractors in outputs. Please consult the API documentation for any service you’d like to use for more information on how a particular function needs to be configured.

For our example, we can access a particular article by specifying it at the end of the endpoint path, or in place of “{articleId}”.

Using inputs, we can dynamically pass a value into this URL, and thus use this connector function to get information on any article we desire.

We add inputs to the endpoint path by putting a dollar sign ($) before and after the parameter (in this case, “ID”). The string between the dollar sign is case sensitive, and must be an exact match to the name of your input. If we return to our example, let’s change the URL so the ID is aligned with our input. The text between the dollar signs turns into a block, indicating a property, like so:

Now we can set the ID as input values rather than hardcoding the value directly into the endpoint URL.

To add more inputs, click the + in the top right corner of the inputs box.

Parameters

Query Parameters are Key-Value pairs that appear after the ? in the Endpoint or under Query Parameters when creating a Connector Function.

Now that we’ve set up our inputs, you can create some parameters to modify the Test Results and make sure you’re only getting the information that you want. Find the keys and values for these parameters in the API documentation of the server you’re connecting to.

With Key-Value pairs, one of the components is a “Key” and the other is the “Value”; both are added to the end of your form link URL. Think of them like tokens in an email to personalize someone’s name. Using Key-Value pairs allows you to pass in information to a form.

The key indicates a variable name.

The value indicates a property value.

In this example, we want to set a parameter that ensures the article returned is published on the Knowledge Base site. Entering the information given in the API documentation, the parameter looks like the following:

These query and request parameters are optional fields to fill in, but they give specificity to the Test Results should you need it.

Outputs

Outputs are the part of the connector function that shows what information is directly returning. They are structured in Dot Notation, so pay close attention to the format of the Test Results to verify that your notation is following an accurate path. Outputs map to variables in apps, so make sure you name them something identifiable and unique.

Note that you can change the type of output to lists by using the List Toggle; this option nests variable outputs within objects and universally maps the dot notation path for all the nested outputs in an object list.

To view whether or not your outputs are correctly mapped, click the outputs tab in the Test Results pane and note the results that are returning.

If the outputs match the results, then congratulations! You’ve successfully created a working connector function and are ready to use it in applications. Check out Using HTTP Connectors in Apps for next steps.

If you’re having issues with your connector function not working properly, see our Troubleshooting Guide for information on what might be going wrong.

Take the HTTP Connectors University course for a walkthrough on building connectors.

Further Reading

• How to Format HTTP Connector Outputs

Did you find what you were looking for?

You can also head to community.tulip.co to post your question or see if others have faced a similar question!