Skip to main content

Step 2: Creating Your First Integration

What you will accomplish#

In this section you will assemble an integration that pulls down a list of ToDo tasks from your software's API, and then generates and posts a notification to Slack indicating how many of the tasks are marked "complete".

JSON Placeholder will stand in as "your system's API". You will use a bit of JavaScript code to generate a message indicating how many "ToDo" items are marked complete. Then, you will send that message as a notification to a Slack channel.

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.
  3. [Optional] Install the Prismatic CLI tool if you'd like to follow this tutorial from the command line instead of the web app.

Create an integration#

You can create an integration via the web app or through the Prismatic CLI tool. If this is your first time using Prismatic, we recommend using the web app to get a visual understanding of how integrations are assembled.

  1. Create a new integration. Click Integrations from the left-hand sidebar, and then click + Integration in the upper-right.

  2. Edit the integration's name. This will drop you into the integration designer. Edit the integration name and set it to My First Integration, and add an optional longer description by clicking the description button next to the integration name.

  3. Configure the integration trigger. Integrations can be triggered by a webhook or on a schedule. Click the Integration Trigger and select a schedule of your choice in the step config pane.

  4. Set Config Variables. This integration should be configurable for each of your customers who might have different setups. Click the Config Variables button to set up some config variables for this integration.

    Add two config variables:

    1. Call one Slack Webhook URL, and enter a Slack webhook URL as the default value of the form https://hooks.slack.com/services/my/slack/endpoint
    2. Call another Todo API URL and give it a default value of https://jsonplaceholder.typicode.com/todos

    You will use both of these config variables in the steps of your integration in a moment.

  5. Add your first step. Add an HTTP - GET Request action by clicking the

    button and searching for the HTTP component.

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

    Click the URL field in the left-hand side of your screen and open the Config Variables tab. Select the Todo API URL config variable that you created in the previous step.

    The Response Type field should be kept its default json value.

    At this point you can click Save & Run Test to save your integration so far and verify that your integration pulls down data from the ToDo API successfully.

  6. Add your second step. Add another action by clicking the

    icon below the action you just added. This time choose the Code component, Code Block action.

    In this step you will add a bit of custom JavaScript code that takes the results from the first step, counts the number of completed tasks, and returns a string reading X of your Y tasks are marked complete.

    Open the code editor on the left-hand pane and replace the default code with this code block:

    module.exports = async (context, stepResults) => {  var todoItems = stepResults.getRequest.results;  var totalItemCount = todoItems.length;  var completedItemCount = todoItems.filter((x) => x.completed).length;  return {    data: `${completedItemCount} of your ${totalItemCount} tasks are marked complete.`,  };};

    Once again click Save & Run Test to run a test of the integration thus far. You should see the output of the Code Block step read 90 of your 200 tasks are marked complete.

  7. Post the message to Slack. Now, add a Slack component, Slack Message action to send the message that the previous action generated to a Slack channel. Once again tap the

    under the Code Block step.

    Open the Webhook URL input field and select the Config Variable tab, and then select the config variable you recently created.

    In the Message input field box choose a Reference and select the previous Code Block step's results.

Test the integration#

Now it's time to test your integration to verify it works properly. Like creating the integration, you can do this via the web app, or in your terminal.

On the top-right portion of the integration designer tap the Save & Run Test button. 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.

When the test is complete, a message should be posted to the Slack channel you previously configured.

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.

Next Steps#

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

  • Toy around with Code Block action, to alter the Slack message you're generating
  • 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.