Introduction
While everyone is ‘waiting in vain’ for the delivery of Project Toscana organizations have start using Slack as a modern way to send messages within departments.
For an example a operation team is using an instructions quality book build on XPages and it would be great to get notified in your Slack channel when new instructions come in or have been updated. Or you want to highlight a specific instruction just to create extra attention to it (e.g. an increasing number of incoming incidents).
Be creative with use-cases 🙂
Slack integration points
Incoming Webhooks are a simple way to post messages from external sources into Slack. They make use of normal HTTP requests with a JSON payload, which includes the message and a few other optional details described later.
JSON, HTTP request… this sounds doable with XPages! So what are the steps you must take?
Setup your integration
Go to http://yourteam.slack.com/apps/build/custom-integration and click on Incoming Webhooks, then select a channel or user you want to post your messages to.
Setup your message
You have two options for sending data to the Webhook URL above:
- Send a JSON string as the
payloadparameter in a POST request - Send a JSON string as the body of a POST request
Simple message
For a simple message, your JSON payload could contain a text property at minimum. This is the text that will be posted to the channel e.g.:
payload={"text": "This is a line of text in a channel.\nAnd this is another line of text."}
You can decorate your message with text formatting. You will find descriptions in the custom integration page on Slack.
Message attachments
To display a richly-formatted message attachment in Slack, you can use the same JSON payload as above, but add in an attachments array. Each element of this array is a hash containing the following parameters:
{
"fallback": "Required text summary of the attachment that is shown by clients that understand attachments but choose not to show them.",
"text": "Optional text that should appear within the attachment",
"pretext": "Optional text that should appear above the formatted data",
"color": "#36a64f", // Can either be one of 'good', 'warning', 'danger', or any hex color code
// Fields are displayed in a table on the message
"fields": [
{
"title": "Required Field Title", // The title may not contain markup and will be escaped for you
"value": "Text value of the field. May contain standard message markup and must be escaped as normal. May be multi-line.",
"short": false // Optional flag indicating whether the `value` is short enough to be displayed side-by-side with other values
}
]
}
Send the message
With a simple post request you send the message in JavaScript:
function postMessageToSlack(url){
webhook_url = url;
payload= JSONStr;
var xmlhttp = new XMLHttpRequest();
xmlhttp.open('POST', webhook_url, false);
xmlhttp.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xmlhttp.send(payload);
}
XSnippet
This whole approach I have added as an XSnippet on OpenNTF:
https://openntf.org/XSnippets.nsf/snippet.xsp?id=slack-integration
You can customize it to your needs. Basically I have a script block and a button on a custom control. Via the Property Definition tab you can set the desired values. In my example I am sending a message to a Slack channel about a picture / document in my Bildr application (shameless plug).
Here is how the message could look like:
Since my XPages app is running on a local development machine it is of no use to send sampel thumbnails of the page, but I could. This also refers to the user icon, which could be the icon of the application.
So grab the snippet and start integrating your XPages with Slack (untill Toscana arrives) !
FYI: I am not aware of any restrictions on the number of message you may send to Slack. Please let me know if you have details on this.
Add 20 years of experience to your workforce
You can 20 years of experience within IBM Notes and Web development to your workforce by hiring me.
Interested? Read my curriculum vitae on LinkedIn: http://www.linkedin.com/in/patrickkwinten and get in contact.
I am happy to work WITH you !
Kwintessential Notes 