Today, I’m starting a new short series demonstrating how we can easily integrate multiple internal and external systems to bring data into Slack using a single Azure function.
The idea here is to define a single simple web based API using the capabilities of Azure Functions in order to provide a company standard format for pushing notifications into Slack from multiple sources.
For my part I’m going to show how to setup the Azure Function, code the integration into Slack, how to trigger the function, and then how to trigger and test that Azure function. In subsequent posts we’ll show how to trigger it from other related systems.
In this first post we will focus on setting up the Azure Function, tying it into Slack, and triggering it with some data using Postman.
Create a Slack Webhook
For information on how to create your Slack webhook and retrieve your webhook URL, look here: https://api.slack.com/incoming-webhooks
You can add a webhook to your account by logging in and going to your teams settings and creating a new custom integration.
Setup Azure Function App
The Azure Functions app is part of the app services section in Azure.
Microsoft Azure > App Services > Function app
In order to use the Azure functions you’ll need an Azure subscription, so sign into the subscription and do a search for ‘functions’ and you should see the Functions app available:
Click the function app and follow the prompts to setup your function app and tie it into your subscription. After that is complete you should see it in your App Services like the below:
Create Function
Now that your function app has been created, we need to create a new function for this exercise, so simply click + New Function:
Next, we need to select a trigger and for this one we will be using an HttpTrigger and Node.js:
Finally, we are going to name our function and choose the authentication policy, but for this one we are just going to leave the default authorization:
Add Code and Packages
Now that we have a function lets familiarize ourselves with the function editor.
[1] Function Url: This shows the URL that will trigger our function, it is important to keep this secure as we cannot access our function without this, but anyone can access our function with it.
[2] Code: This one is pretty obvious and where we will do most of our work. This is a fairly well featured section, though it’s not going to match any real IDE.
[3] Logs: Another very important section, we will use this to output the details of each run as well as determine any errors we might have while developing our script.
[4] Run: This section is great for testing simple functions, but we want to know it works properly from an external run, so we’ll be using Postman for our testing.
Moving on, we need to take care of a few administrative tasks. Our code is not only going to take and process data sent to it, not only send data back to the caller, but is also going to reach out and post data to another location before completing. To make this as easy as possible we are going to import a package that doesn’t come with node.js out of the box.
Rather than program a solution here ourselves, we are going to use an npm package called request, and the code and documentation can be found here:
https://github.com/request/request
We will just be using npm to install it though to keep it simple, but in order to do that we have to log into our function instance through a console in order to run the npm installer. Information on how to do that can be found here:
Azure Functions NodeJS Documentation
For your convenience though, here is the information:
Following the above, log into your function app instance and browse to the appropriate function folder, run npm update and then npm install request. This should pull down the appropriate modules and dependencies.
Now that we have that taken care of, we can go back to our function editor and look at our code.
[1] First thing we need to do is load the request module using a required statement. This will give us access to all the features of the required module, so we can use them in our function.
[2] Next, we build a global function to help us simplify handling of attachments that could be coming in from our systems to be pushed into Slack. By simplifying this we can call them ‘notifications’ when coming from our systems and give simple color codes for formatting.
[3] Within our notifications function we have another function to determine the color based on the type of notification.
[4] Then we iterate over the array we’ve passed in and pull out all the notifications and convert them into an attachment array.
[5] Returning that array so it’s ready to be pushed into Slack.
Finally, we need to use the module.exports function so that Azure Functions knows what code to run and export and how to respond to our incoming webhook. There is a lot more information here, but for now lets just understand that we can pass values in the body of a request to our function, and then access those values from the context or the req object that is passed into the exports function.
[1] When Azure runs the function, the first variable will always be the context, regardless of what it is named. Beyond that you can read the documentation to see what else is passed in by default, but you can always pass in your own variables as well.
[2] Here we are going to setup the payload of the message that we are going to be sending to Slack. This sets up the schema and also takes the values that came in from our request object and puts them in their appropriate place. We are really mapping our values to the required Slack values here.
[3] Now calling the request function to post the message to Slack. We are going to post this as a webhook to the URL that we received when we created the custom integration > webhook in Slack. We are sending it as JSON and the body is the message (msg) payload we defined above.
[4] This is our callback function for the request statement, this is how we will determine what happens after the post call has completed and determines what we do if it is successful or a failure. In our case we are posting to the log as well as pushing a response back to the caller of the function webhook so that our originating application gets the response as well.
[5] Finally, we are completing the context object by running the .done() function which will let Azure know we have completed the function.
Save this, and our Azure Function should be complete! Just make sure you put your webhook URL into the settings for the url variables near the top and you should be set. We can test it now, so let’s open up Postman.
Testing
Open Postman to get started, if you don’t have it already it can be downloaded from here:
Once we have it open, it will look like this:
[1] We need to set the request type to POST
[2] Then copy and paste the Function url into the url string.
[3] Switch to the body tab of the request.
[4] Make sure we are using the JSON format.
[5] Using JSON formatting, enter the parameters that we want to pass to the Azure Function. The parameters that we handle in our function code above are: channel, username, text, icon_url, icon_emoji, fallback, and notifications. Make sure and put a valid channel for YOUR team in the channel value.
[6] The notification section is where we define our array of notifications, and each notification should be an object with three values: type, title, text. We support three different types in our Azure Function code: error, warn, and info. These are then mapped in our function to the colors red, yellow, and green. The title and text fields also support markdown text formatting, if you are interested in some more advanced formatting.
Now that we have this set, click SEND. This should send the request to our Azure Function and trigger it, passing in the parameters that we sent. The first run takes a second or two to spin up the function (subsequent runs will be faster while the function is in Azures memory). You should then see your post pop up in Slack just like this:
There you have it! Now we can develop HTTP requests in this manner coming from various systems all using the same simple request formatting we just designed. We can do javascript functions, powershell, and even C#.
In the next part of this series we are going to create a simple custom task for the Cireson portal that uses our Azure Function to post Work Item information into Slack!
Tech, Finance, and Automation 