Skip to main content

Step 2: Creating Your First Integration

In this section you will assemble an integration that pulls down a list of to-do tasks from your software's API, loops over the list, and notifies you via Slack of any "incomplete" tasks.

Placeholder data will stand in as "your system's API". Your integration will then loop over the list of to-do task that it pulled down, and if the task is marked completed: false it will send the to-do task as a Slack message.

Sample integration diagram in Prismatic app

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

Prerequisites#

  1. To run this integration, you will need to have a Slack account and generate a Slack webhook. Take note of the webhook you generate. It should be of the form https://hooks.slack.com/services/SOME/API/KEY.
  2. If you have not yet, please complete the previous setting up tutorial prior to this one.

Create a new integration#

Click Integrations from the left-hand sidebar, and then click + Integration in the upper-right.

Integrations page in Prismatic app

Give the integration a name of "My First Integration". You can choose to give your integration an optional description, and can categorize the integration if you wish - both fields can be left blank.

After clicking Next, select an integration trigger. An integration's trigger determines what should cause the integration to run. For this integration, select a Schedule Trigger, which allows you to run the integration on a schedule (once a day, once an hour, etc). After selecting the trigger, you'll find yourself in the integration designer.

Configure the integration trigger#

Click on the integration trigger. This will open a configuration drawer on the left side of the screen. Then, click Add a Value under Schedule. Configure the trigger to run once daily at a time of your choosing:

Integration trigger in Prismatic app

Pull down to-do data#

Your first step is responsible for fetching data from the to-do API. Add an HTTP - GET Request action by clicking the

button and searching for the HTTP component.

HTTP Component selection in Prismatic app

Select the HTTP component, and then select the Get Request action.

Get Request action selection for HTTP Component in Prismatic app

Make the URL Configurable#

Now we need to tell the step where to look for the to-do API. We should make this configurable, so one customer could look at one endpoint, and another customer could look at another endpoint.

Click the URL field in the left-hand side of your screen and open the Config Variables tab. Click +Config Variable to create a new config variable. Within the dialogue that pops up name the new config variable To-Do API Endpoint and set this as its default value:

https://my-json-server.typicode.com/prismatic-io/placeholder-data/todo

Click Accept to save this config variable and use it as input to this step.

The Response Type field should keep its default JSON value and you can leave all other input fields alone.

Configure HTTP action in Prismatic app

At this point you should test your single-step integration to verify your first step pulls to-do data from the to-do API successfully.

Click SAVE & RUN TEST button to save and run your integration. This will open the TEST RUNNER drawer. If you open up the Step Outputs tab, you should see the data retrieved from the to-do API:

Test HTTP action in Prismatic app

Loop over to-do tasks#

Add another action by clicking the

icon below the action you just added. This time choose the Loop component, Loop Over Items action.

Let the step know what items to loop over by clicking the Items input, and from within the Reference Search box that comes up, enter results.

Loop over items in Prismatic app

Click SAVE & RUN TEST again. In the Step Outputs tab, you'll now see the results of the loop step. Note that it has a currentItem value - this represents the to-do task that is currently being looped over. We'll use that value for the next step.

Test loop action in Prismatic app

Check if a to-do task is completed#

Now you need to determine if each to-do task is complete or not, so you can send incomplete tasks as Slack messages.

Within the loop, add a new step. This time select the Branch component, Branch on Expression action.

Create a branch named "Completed". Under Field open the Reference tab and select your loop step as the Reference Step. Enter currentItem.completed as the Reference Search. Under the Operator drop down, select is true to check if the current to-do item's completed value is true.

Configure branch action in Prismatic app

Post the message to Slack#

We want to send a Slack message when a task is not complete. So, add a Slack component, Slack Message From Webhook action under the Else branch.

In the Message input field choose a Reference, select the Loop Over Items as your Reference Step and enter currentItem.task for the Reference search:

Configure Slack action in Prismatic app

This will instruct the Slack component to send the current tasks's description as a Slack message.

Configure the Slack Connection#

A connection is a config variable that contains the information necessary for a step in your integration to interact with an external app or service. Connections often contain endpoints, usernames, API keys, etc. In this case, we want to configure Slack to use a specific webhook URL (the one you created above) to send messages. Note that the Connection input has already been populated with a connection config variable for you.

Open up the Config Variables drawer from the button on the right side of the screen and open the Slack Connection config variable that was created for you. Under Connection Type, change it to a Slack, Webhook URL:

Open up the connection's Webhook URL input and give it a default value of the Slack webhook URL you configured above:

Set Slack default webhook URL in Prismatic app

Test the integration#

Now it's time to test your integration to verify it works properly.

Click the Save & Run Test button once more. Then, open the Test Runner tab from the left-hand sidebar. You'll see output from your test run. By clicking through Step Outputs you can see the output that each step generated. You should see several "incomplete" to-do tasks appear in your Slack channel as the integration runs.

Test sample integration in Prismatic app

Tidy Up Your Integration#

Though it's not necessary, it's helpful to add descriptive names to each of your integration's steps so your team members know exactly what each one does. You can also add a step under the Completed branch to do something with completed to-do items if you'd like.

Sample integration diagram in Prismatic app

Publish the integration#

Now that you have a working integration, it's time to publish it so it can be deployed to customers.

Open the VERSION HISTORY tab on the left-hand side. Enter a publication message so others know what you've changed, and then click the SAVE & PUBLISH button.

Publish the integration in Prismatic app

Next Steps#

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

  • Alter the Slack message you're sending using template inputs.
  • 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.

When you are ready, move on to the next tutorial to create a customer, deploy your integration, add alerting, and more.