An Overview of HTTP Connectors

This guide will help you understand the full capability of HTTP Connectors.

If you want to connect an external system like an MES or ERP to Tulip, you will need to use an HTTP connector. Tulip's HTTP Connectors can interface with most types of HTTP APIs, including REST and SOAP.

Looking for a walkthrough on building HTTP Connectors? Take the HTTP Connectors University course!

Understanding Connector Functions

Within an HTTP connector, you can write a series of Connector Functions that will run common types of HTTP requests using predefined inputs. Connector functions are the individual actions which make calls to the API. Tulip HTTP connector functions support the following methods:

• GET
• HEAD
• POST
• PUT
• PATCH
• DELETE

and modifications to the following fields:

• Hostname, Port, and Path
• Authentication (none, Basic Auth, OAuth 2)
• Request Headers
• Query Parameters
• Request Body (JSON, Form URL-Encoded, XML, or Plain Text)

The responses can then be processed and information extracted from the:

• Response Headers
• Response Body (JSON using json-query or XML using xpath)

HTTP Connectors support the following data types in outputs:

• Text
• Integer
• Float
• Boolean
• Datetime*
• Objects with all the data types above
• Arrays with all the data types above

*Datetime parsing supports:

• OData timestamps in milliseconds since Jan 1, 1970 UTC
• numbers interpreted as milliseconds since Jan 1, 1970 UTC
• ISO 8601 date strings

Creating A Connector

Click Add Connector in the top right of the Connectors page, then name the Connector and select HTTP.

Then, you will see the Environment tab. If you want to set up multiple environments, see this separate guide

Then, after selecting your Connector, choose Add Connection Details to add more details about the server you would like to query.

There are 5 options.

Refer to this guide on connector hosts.

Host: Only include the domain that you would like to query. Do not include http:// or https:// Eg. myaccount.restlet.api.netsuite.com

Port: This should be specified by the service you are querying. HTTP requests typically use port 443.

TLS: Select "Yes" if you are using HTTPS, and "No" if just "HTTP".

Click Test to see if you can successfully connect to the server, then click Save.

To duplicate or delete the Connector, go back to the Connectors page, and then click the three dots on the right side of the specific connector.

Creating a Connector Function

Click Add New Function button on the Functions tab to create a new function.

You will then see a series of options for editing your function.

First, name the function in the top left of the page.

Then, click Add Function Inputs to begin adding inputs. Example:

If you want to test your HTTP connector function, add a "Test Value" for each input.

Then, add an endpoint to the end of the URL and choose the type of HTTP request.

Select Query Parameters to begin adding key/value pairs. Use your defined Inputs in the Value field.

Add a $ before and after the Input name, for example, if the input name is "city_name", type in

$city_name$

.

Handling Responses

After you are satisfied with your inputs and outputs, select Test in the top right corner to create a sample response.

You will see a JSON or XML response in the Test Results section. Now, you can map parts of this response to Outputs and then use them in apps.

JSON extractors use the json-query syntax. To test the syntax, use this online tool.

XML extractors use XPATH syntax.

There are two ways to do this:

1. Click on properties in the body of the response to map them to outputs
2. Manually specify the path using json-query

Here's how to specify the extractors using point and click:

If you want to use json-query, add a few outputs so you can map the contents of the response to Tulip.

Next, you need to specify "extractors" next to each output to indicate the data from the body of the response that you would like to store.

Here's an example with json-query: let's say that you write a GET request that returns an Array of Objects. You want to return the value of the name property from the first object in the array.

This is what you would write in the path field:

0.name 

You can also store values from the Headers and Cookies section of the response.

Similar to the section above, you must specify a specific output in the Output section. Then, click on a part of a sample response or use json-query to access the correct property from the JSON in the HTTP response.

Here is an example where an output named "csrf_token" stores the value called "x-csrf-token" from the property in the header.

Outputs are stored as properties of an object when they are shared with an app. You must then store the object in a variable in an app. For more details, see this guide to using connector outputs with apps

Using RegEx To Modify Outputs

You can also use RegEx to refine text values from the response. To do this, add one of these functions in the Path field to pass the value through a regular expression:

:regexp()

To capture multiple substrings within the string-

:regexpGroup()

Examples:

0.name:regexp(^N)  
0.name:regexpGroup(^\w + (w+))

Using RegEx group, you may want to capture a single group within a larger string. To do this, add a comma to the end of your RegEx string and add the number of the specific group within the string.

parts[0].inputs:regexpGroup(^\w\w\s(\w\w)\s(\w\w)\s(\w\w),2)

Or, use it to select a specific item in an array that matches a rule. For example, the first object with an email value that starts with n.

.[email:regexp(^N)]

We recommend RegExr to test your RegEx. Tulip uses the JavaScript (ECMA) RegEx engine.

Handling Objects and Arrays In Outputs

Tulip supports both objects and arrays within JSON output. Here's how to use each one:

Objects

To format JSON output as an object, first create an Object in the Outputs section and then indicate the extractor.

In the example above, the object is called "singleObj". The JSON output is an array of objects, so it selects the Object at index 0.

Then, begin adding outputs that correspond to each key/value pair that you would like to store. You can add key/value pairs with the + button.

In the example above, there are two fields within the singleObj object:

1. userID, which references the userID property and is an integer
2. id, which references the id property and is an integer

In this case, the extractor does not need to start with "0." because it automatically references the object at index 0.

Here's what the JSON output looks like, for reference:

Arrays of Objects

To return an Array of objects, select List of Values within the Output section and choose Objects.

You will likely need to return the entire array at the root level in the JSON output.

To do this, enter a "." for the extractor:

Then, much like the object extractor above, begin adding individual properties that you would like to send to the app.

This would return the userId and id for every object in the array. You can check your work in the Outputs section of the test results:

Arrays of One Data Type

Let's imagine that you want to get a boolean value from every object in an Array of returned values.

To do this, create an output for an array of Booleans. Then, indicate the property that is used to store that boolean value in every Object.

In the example above, the output is called "completed", and it includes the value from every "completed" property in the array, as indicated by the extractor.

Here's what the output would look like:

Past Integrations

Tulip can integrate with a variety of software systems. Here's a few examples of systems that have been integrated into Tulip in the past:

• Epicor
• SAP
• Netsuite
• CAMstar

Further Reading

• How to Create and Configure an HTTP Connector Function
• How to Format HTTP Connector Outputs
• Using HTTP Connectors in Apps

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!