Dev Guide: Build a Mule integration with a Slack slash command (Part 3)

reusable apis developer how to

Picking up from the second part of this series, this blog post will wrap up building an end-to-end API solution. For the first post, you abstracted source systems with APIs to add flexibility, ease of consumption, and increase adoption and integration possibilities.

In the second post, you built process APIs, which were based on logical integration use cases from the source systems we have.

api-led connectivity layers

In this final part of the series, you’ll consume the two process APIs in a new experience API that can perform DevOps processes from Slack via a slash command. We’ll use all of the material learned from the 1st and 2nd issues of this series to build this solution.

Tools

  • Anypoint Studio
    • Desktop IDE for creating flows, connectors, and more
  • Postman
    • An amazing HTTP request tool for all devs
  • Slack
    • Real-time communication chat tool
  • Ngrok
    • Tunnel to a port on your local machine with a public address

Designing and Building an Experience API

This API – as all APIs – has two considerations to keep in mind when designing:

  1. What is the end service requesting and/or providing?
  2. What are the payload requirements for the process APIs we’re going to be calling—data ingressed and egressed?

To begin writing your DevOps API spec, you want to ingress a URL encoded payload from a Slack slash command and, on success, respond back to Slack with a JSON that includes the responses from your Broadcast and Incidents APIs.

With that in mind, you can start building a RAML definition.

Building Your Experience API Specs

The Slack documentation states that a slash command request will include a uri-encoded POST request that has the following example structure:

Since you know what your responses from the broadcast and incidents API will look like, you can create the following DevOps API specification. Go ahead and import this into Anypoint Studio and start working on building the “DevOps.getstarted” application.

Note: If the API specifications weren’t built, an individual/team member would have a long and arduous process of trying to understand the previous APIs before being able to build on top of them. Even with code comments, critical pieces of information go missing.

After the application project is created, the first step is always to update the HTTP listener. Use the values you want for your service.

Persisting Objects in a Flow with Flow Variables

When new modules are added to a flow, they can alter/replace the payload variable. In a scenario where we want to persist an object temporarily within a flow, we can use flow vars.

This is different from a session variable in that it’s only scoped to within the flow. To set one, we’re going to use the DataWeave Transformer and set the Output to Flow Var with the name “slash.”

experience api mulesoft 2

The “text” parameter coming from the slash command includes all the parameters that follow the command. You’ll need to split this string into the individual parameters to provide value. You will also need to set the MIME type to a Java Object:

If the DevOps team only wants to resolve an incident instead of resolving and broadcasting, you will need to route accordingly. An “if statement” is what a choice router is for flows. It can perform a conditional evaluation and route according to whether or not these conditions are met.Conditional Routing with a Choice Router

For this example, we’re going to consume two process APIs, so we need to include a scatter-gather as one of the paths for our choice router to take.

Place elements in your flow so you can configure your choice router:

mulesoft flows

Clicking your choice router will open up the configuration where you can enter the condition to choose the scatter-gather route:

Challenge: Create choices for just a resolve route for your experience API. Use the Flow Ref module where appropriate in your post:/slack flow and create Sub Flows to reuse configuration and code.

Reusing a Connector from Anypoint Exchange

Looking at your Incident API’s /resolve endpoint that we’ll be calling and the payload from Slack, we’re missing an email of the request. In order to fill that gap, import the Anypoint Connector for Slack from Exchange. This will enable you to make calls to Slack’s API without writing any code.

From the Mule Palette, search for “Slack”  → click Search Exchange for ‘Slack’ and install. After restarting Anypoint Studio, place the connector into your flow:

mulesoft devops

Get a Public URL using Ngrok

Ngrok is a must-have tool for testing public requests to your application before deploying. To start up an HTTP tunnel to port 8081 (or any tunnel your DevOps app is using), run the following command in terminal/command prompt:

Configuring a Slack Connector

Next,  provide the Slack connector with an access token. In order to do so,  create a new Slack App. Go to the Slack website and enter the following details. Be sure to include the ngrok URL from the steps above as well as the path that matches your application:

Note: You’ll be updating the URL to the Slack App after deploying this Mule Application with the CloudHub URL.

mulesoft devops 5

Setting Slack token scopes

After saving, click “OAuth & Permissions” and add the following two scopes to gain API access to a user’s email for your Slack app. The default permissions for the token do not have the appropriate scope:

Let’s update the Slack connector in your Mule app to use this token to gain access. Clicking the “+” to add a new configuration for the connector and selecting Slack: Token Configuration. Paste the token into the textbox and save.

Fulfilling Slack connector requirements

Select the operation “user-info” and use the user’s ID to get the user’s e-mail.

mulesoft slack integration

Making Requests to Process APIs

With the Slack connector in place, you’re now ready to configure the HTTP connectors and set your DataWeave transformations to match the request needs.

Starting with the path that has the Slack connector, you’ll need to make the HTTP request to your Incidents API.

Going into the configuration, use the incidents API RAML specification from last time. The other flow path in your scatter-gather will be a request to the Broadcast API and require it’s RAML specification.

mulesoft broadcast api

Matching Output to RAML Spec

To fulfill your API’s response contract according to the specification, and allow each of the outbound requests to be successful, you’ll need to set the DataWeave transformations.

Setting default choice route response

Starting with the default route for your choice router, set the transformer to output a default message back to slack. This is the default for when the slash command does not have the first parameter as “resolveAndBroadcast.”

Transforming connector output

Updating the message before sending the request to the incidents API, set the DataWeave transform functions as below. Note how to use the initial Flow Variable and the payload from the Slack connector in your transformation:

Concat strings in DataWeave

The broadcast API will take a string concatenation of a parameter from the original flow var and plain text:

Finalize the app

Lastly, set the output of your endpoint. Since the Scatter-gather router outputs an array (in order of flow), you can set the transformer to:

Testing the App

You’re now ready to test your application by clicking the run command in Anypoint Studio. With the Slack slash command app installed in your workspace, run the command (replace mustache).

After the above step, you should see the following:

Status page

mulesoft experience api

Twitter

mulesoft twitter integration

PagerDuty

test api mulesoft

Looking Back

So in this final part of the series, you’ve created a very modular and reusable end-to-end solution that can be repurposed and modified for continued use––especially as business needs change. By separating the process layer logic from the experience layer, you’re able to reuse them for different front-end experiences to be created (e.g. Marketing ops).

The API specifications can be modified and given more detail as the application’s needs change. Versioning APIs and their respective specs ensures that existing applications do not break. Even adding additional system-level APIs can provide more capabilities and fulfill greater business needs without modifying existing APIs.

By building well-defined reusable abstractions, you are able to harness the true power of APIs and the inherent flexibility and reuse of existing assets. This allows you to complete integrations and projects faster and faster with each new API added to the list.

Looking Forward

Security is critical in order to deploy this end-to-end solution into a production environment. You’ll want to secure your individual APIs to prevent unauthorized access. To ensure that requests are coming from a trusted Slack instance, Slack includes validation schemes that can be incorporated into your experience API.

With built-in security and prebuilt modules, you can build a reliable & secure production ready solution with very little actual code and roll this solution to your organization.


 


We'd love to hear your opinion on this post


2 Responses to “Dev Guide: Build a Mule integration with a Slack slash command (Part 3)”

  1. Hi Rashed,

    Installing Slack Connector 3.1.0 via Exchange from within Studio, yielded the following error message in Anypoint Studio 6.41:

    Unable to read repository at jar:
    Server returned HTTP response code: 403 for URL:

    I guess this might be an AWS access issue to be solved?

    Cheers,
    Dennis Hardjo (Novisource, a MuleSoft partner Dutch company).

    • Hey Dennis,

      It’s because your session with Anypoint Platform has expired. If you close studio and start it up again, it should prompt you to login to exchange and allow you to download the jar.