How Do I Setup the Integration to be Used in a Workflow Integration Step?

What is the Integration Step?

In a workflow you and your app administrators have the option of using an Integration Step that will enable you and your app administrators to send information from Build to an external system. The Integration Step allows you to select from a list of pre-configured integrations if any were created during implementation. See more information in this guide about adding an Integration Step to a workflow.

The purpose of this guide is to walk a developer through creating this type of integration on the backend.

How do I configure the integration?

The following information includes instructions and recommendations to consider when configuring an integration for the workflow integration step. Refer to the How to Create an API Integration guide for more information on how to create an integration. 

• Type of Integration: Select Send Data.
• HTTP Method: Select PUT or POST. Typically POST is selected here. In order for the integration to work, you will need to set up an HTTP server that would be able to respond to this call.
• Integration URL: Input the URL to where the service will be called. Refer to the source's documentation for the source's url. 
• API Key: Setup any authentication you need.
• Headers: If you need additional headers, you can configure them here.

Once the configuration is setup in Build, you will need to have a server running that will respond to these requests. When an end user puts that integration, in their workflow and when a form submission gets to the integration step in workflow, it will call that service you set up here with the form submission data.

Note: You can see what the incoming data will look like by using the WF Simulator. By clicking on the View JSON (Advanced) button in the Workflow Simulator on an integration step, you will be able to view the JSON and write your service based on what is there.

What happens when my service is called?

When Build hits the integration step in a workflow, it will send all of the data in an http request that you've configured in System API Integrations. The HTTP request will contain the Authorization header you've configured as well as the document data in the request body in JSON format. In addition to this, it will include a header X-Response-URL which will be explained in a bit.

When you respond, you must respond with a 200 response code (or anything in the 200-299 range) within 5 seconds if it was successful. Responding with any error status code will result in an error inthe workflow, and it will need to be retried or skipped by an app administrator.

If your integration needs to take more than 5 seconds, there is an option for you to call back into Build at a later time. If that is the case, you must respond to the integration request with a 202 status code within 5 seconds. Then when your process is complete, make an HTTP POST request to the url provided on the X-Response-URL header. If you would like to provide a status code other than 200, you can set the X-Status-Code header with the value of the status code you would like to convey to Build.