Skip to main content

Build Your First Integration

Overview​

This tutorial will walk you through some basic concepts of integration development. You will:

  • Fetch data from an API
  • Learn how data flows between steps of an integration
  • Use a loop to iterate over the records you fetch
  • Use logical branches to determine what to do with each record
  • Send certain records to another system (this example uses Slack)

Integration overview​

The integration you build here will fetch data (a list of to-do tasks) from an API, loops over the list, determine which tasks are marked "incomplete", and notify you via Slack of any "incomplete" tasks. We'll use a placeholder API to stand in for the to-do list "API" - https://my-json-server.typicode.com/prismatic-io/placeholder-data/todo.

You'll design this integration to be configurable, so the same integration can be deployed to multiple customers with unique API endpoints and Slack credentails and channel names.

Let's build!​

You're encouraged you to follow along with the video above, or steps below. If you'd like to import a completed integration, you can download this integration's YAML definition here.

As you build, you'll pull data from this API endpoint: https://my-json-server.typicode.com/prismatic-io/placeholder-data/todo

You will need to create a Slack app and have access to a Slack workspace, which you can do for free at https://slack.com/. Be sure to assign your Slack app the chat:write, chat:write.public, and channels:read scopes. Docs for creating a Slack app can be found here.

Create a new integration​

From the integrations page, click the New Integration button. Select Quickstart to create a new integration from scratch. Then, give your integration a name like "My First Integration."

Fetch data from an API​

Next, add a new step to your integration by clicking the + button below your trigger. Search for the HTTP endpoint and add a GET Request step.

Configure your GET Request step to fetch data from the to-do API endpoint - https://my-json-server.typicode.com/prismatic-io/placeholder-data/todo.

Finally, click the green Run button on the bottom of your screen to test your integration so far. If you select the Get Request step in your test runner drawer at the bottom of your screen, you will be able to expand the results section in the Output tab on the right to see the data that was fetched from the API.

Loop over the records​

Now that we're fetching an list of to-do tasks, we need to loop over each task to determine which ones are incomplete. To do this, we'll add a Loop step to our integration. Add another step under your GET Request step, this time searching for the Loop component and its Loop Over Items action.

Configure your loop step to loop over the results property of the previous step. You can do that by clicking Configure Reference in the loop step's configuration panel, and selecting the results property of the Get Request step.

Run a test of your integration again. This time, you'll see that the loop step has a currentItem property in its output that contains the data for the current item that is being looped over. We'll use this property in the next step to determine if the current item is incomplete.

Identify complete items​

Now that we're looping over each item, we need to determine if the current item is complete or not. completed is a boolean property on each item that indicates whether or not the item is complete.

Add a step within your loop - select the Branch component, Branch on Expression action. Configure the branch step to have a condition called Is Complete?. Select the loop step's currentItems.completed property as the Field input, and under Operator select is true.

Now, steps that have completed: true will follow the Is Complete? branch, while steps that have completed: false will follow the Else branch.

Send incomplete items to Slack​

Next, we want to send a message to Slack for each incomplete item. Within the Else branch, add a Slack component, Post Message step.

Up until now, steps we've added have not required additional connection configuration or credentials. This step will take additional setup. Make sure that you have created a Slack OAuth app and have access to a Slack workspace (see docs).

Click the Configuration Wizard button on the top of your screen and edit your Slack Connection config variable. Enter your Client ID, Client Secret, and Signing Secret from the Slack app you created.

Configure your test runner to use your test Slack workspace by clicking Test Configuration on the bottom of the screen, and select Test-instance configuration - that will open up a configuration wizard for your test instance.

Now, configure the Slack step to send a message to a channel in your Slack workspace. For now, hard-code a channel name like general in the Channel Name input - we'll make that dynamic in a moment. Your Message input can be a template, concatenating a string like Incomplete task: with the currentItem.task property.

Finally, run a test of your integration. You should see messages in your Slack workspace for each incomplete task.

Make the integration configurable​

Now that we have a working integration, let's make it configurable so that we can deploy it to multiple customers. We'll make the Slack channel name configurable, as well as the API endpoint we're fetching data from.

First, we'll make the Slack channel name configurable. Click the Configuration Wizard button on the top of your screen and crate a second Config Page. Name it something like "Slack Configuration". Then, add a new Config Variable. Name it Slack Channel and choose Picklist as its Data Type.

We want our config variable to be a picklist of all the channels in our customer's Slack workspace. We'll use a data source to make the dropdown menu dynamic. Select the Slack component's Select Channel data source, as shown here:

Next, add an additional String config variable called API Endpoint, and give it a default value of

Finally, we need to update our integration to use these new config variables. Update the HTTP step to use the API Endpoint config variable as the URL to fetch data from. Then, update the Slack step to use the Slack Channel config variable as the channel name to send messages to.

Run a test of your integration again and verify that it still works as expected.

Next steps​

Congratulations! You created your first integration! Here are a few things you should try next:

  • Send your message to a different system, like Microsoft Teams.
  • Swap out the HTTP GET action for a different data source component (perhaps pull from an SFTP server)?
  • Write your message out to a file in Dropbox or Amazon S3 instead of Slack.