Slack Integration

How to integrate Slack with Connectware, including creating incoming webhooks, posting machine alarms with a severity filter, and posting production milestones as Block Kit messages.

This guide describes how to post shop floor notifications from Connectware to Slack channels. You configure a service commissioning file that posts machine alarms and production milestones to Slack through incoming webhooks. A complete example file is available at the end of this guide.

Objectives

• Creating a Slack app with an incoming webhook per channel.

• Posting machine alarms as text messages, filtered by severity.

• Posting production milestones as structured Block Kit messages.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• A Slack workspace and permission to create Slack apps in it. Workspace owners can restrict who is allowed to install apps.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).

Connectware and Slack Integration

Slack receives messages from external systems through incoming webhooks: unique URLs of the form https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX that accept a JSON payload per HTTP POST request. The minimal payload is {"text": "Hello, world."}. Connectware sends these requests through the HTTP/REST connector.

Each webhook posts to exactly one channel, the one you select when you create it. To post to several channels, create one webhook per channel and one Connectware endpoint per webhook. This guide uses two channels: one for machine alarms and one for production milestones.

Slack rate limits incoming webhooks to one message per second per webhook, with short bursts allowed. Requests beyond the limit return HTTP status 429. Post curated notifications that people should read, not raw sensor streams. The filter rule in this guide keeps low-severity alarms out of the channel.

The MQTT topics in this guide follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). The mappings subscribe with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration. The topic levels appear in the Slack message, so the reader knows which machine raised the notification.

Creating a Slack App with an Incoming Webhook

1. Open the Slack app management page and create a new app from scratch in your workspace.

2. In the app settings, select Incoming Webhooks and switch on Activate Incoming Webhooks.

3. Click Add New Webhook to Workspace, select the channel for machine alarms, and authorize the app.

4. Copy the webhook URL from the Webhook URLs for Your Workspace table.

5. Repeat the last two steps for the production milestones channel. Each webhook posts to one channel only.

Slack Connection Properties

The webhook URL splits into two parts: the host hooks.slack.com, which is the same for every webhook, and the path starting with /services/, which identifies the app and the channel. We add the paths as parameters to the service commissioning file, so you can set them when you install the service. For the webhook URL https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX, the path is /services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

• alarmsWebhookPath: The path of the webhook URL for the machine alarms channel.

• milestonesWebhookPath: The path of the webhook URL for the production milestones channel.

• minimumSeverity: The lowest alarm severity that is posted to Slack. Defaults to 3.

• topicRoot: The root of the MQTT topic hierarchy. Defaults to enterprise.

The webhook path is a credential. Anyone who knows the full webhook URL can post messages to the channel, no further authentication is involved. Do not share webhook URLs and do not commit them to public version control. Slack actively searches for leaked webhook URLs and revokes them.

parameters:
  alarmsWebhookPath:
    description: Webhook path for the machine alarms channel, without the host
    type: string

  milestonesWebhookPath:
    description: Webhook path for the production milestones channel, without the host
    type: string

  minimumSeverity:
    description: Lowest alarm severity that is posted to Slack
    type: number
    default: 3

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

Slack Connection

All webhooks share the host hooks.slack.com, so one Cybus::Connection resource serves both channels. The channel-specific webhook paths go into the endpoints.

resources:
  slackConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: hooks.slack.com
        port: 443

Posting Machine Alarms

We define a write endpoint with the webhook path of the alarms channel and a mapping that feeds it from the MQTT topic hierarchy. Two rules process each alarm:

• The filter rule drops alarms with a severity below the minimumSeverity parameter, so the channel only shows alarms that people should react to.

• The transform rule builds the Slack payload. The HTTP/REST connector expects the request body in the body property of the message (see Publishing Data to REST Servers). The named wildcards of the topic make the equipment hierarchy levels available in $context.vars, so the machine identity ends up in the message without the machine having to send it.

alarmsEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref slackConnection
    write:
      path: !ref alarmsWebhookPath

alarmsMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/alarms'
        publish:
          endpoint: !ref alarmsEndpoint
        rules:
          - filter:
              expression: !sub 'severity >= ${minimumSeverity}'
          - transform:
              expression: |
                {
                  "body": {
                    "text": "Alarm " & code & " on "
                      & $context.vars.site & "/" & $context.vars.line & "/" & $context.vars.cell
                      & ": " & message & " (severity " & $string(severity) & ")"
                  }
                }

A machine publishes its alarms as a JSON object, for example to enterprise/hamburg/assembly/line-1/press-01/alarms:

{ "code": "E-4711", "message": "Hydraulic pressure low", "severity": 4 }

This posts the message Alarm E-4711 on hamburg/line-1/press-01: Hydraulic pressure low (severity 4) to the alarms channel. An alarm with a severity of 2 is dropped by the filter and never reaches Slack. The text field supports Slack's mrkdwn formatting, for example *bold* for bold text.

Posting Production Milestones with Block Kit

For structured messages, Slack accepts a blocks array of Block Kit layout blocks in the webhook payload. A section block carries a text object and an optional fields array of up to ten text objects, which Slack renders as two columns of side-by-side text. Text objects with "type": "mrkdwn" use Slack's mrkdwn markup. When blocks is present, the top-level text property serves as the fallback shown in notifications.

The milestones mapping posts one section block per milestone, with the equipment hierarchy levels from $context.vars as fields:

milestonesEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref slackConnection
    write:
      path: !ref milestonesWebhookPath

milestonesMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/milestones'
        publish:
          endpoint: !ref milestonesEndpoint
        rules:
          - transform:
              expression: |
                {
                  "body": {
                    "text": "Production milestone: " & milestone,
                    "blocks": [
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "*Production milestone:* " & milestone
                        },
                        "fields": [
                          { "type": "mrkdwn", "text": "*Site*\n" & $context.vars.site },
                          { "type": "mrkdwn", "text": "*Area*\n" & $context.vars.area },
                          { "type": "mrkdwn", "text": "*Line*\n" & $context.vars.line },
                          { "type": "mrkdwn", "text": "*Cell*\n" & $context.vars.cell }
                        ]
                      }
                    ]
                  }
                }

A milestone message published to enterprise/hamburg/assembly/line-1/press-01/milestones looks like this:

{ "milestone": "Order 4711 completed" }

Verifying the Integration

1. Install the service and set the alarmsWebhookPath and milestonesWebhookPath parameters to the paths of your webhook URLs.

2. Check that the connection is in the Connected state on the service details page in the Admin UI. The host hooks.slack.com answers the connection probe without checking the webhook path, so the Connected state does not prove that the paths are valid.

3. Publish a test message with the payload { "code": "E-4711", "message": "Hydraulic pressure low", "severity": 4 } to enterprise/hamburg/assembly/line-1/press-01/alarms, for example with an MQTT client or the Admin UI. The alarm appears in the alarms channel.

4. Publish the same message with "severity": 2. The filter drops it and nothing appears in Slack.

5. Publish a test message with the payload { "milestone": "Order 4711 completed" } to enterprise/hamburg/assembly/line-1/press-01/milestones. The milestone appears in the milestones channel as a formatted message with the equipment hierarchy in two columns.

6. The result of every HTTP request is published to the /res topic of the endpoint. Use the Data Explorer to inspect it. A successful post returns the plain text body ok. If Slack rejects a request, for example because the webhook path is wrong or the webhook has been revoked, the message on the /res topic contains an error property with the HTTP status.

Service Commissioning File Example

slack-example.yml

4KB

Open

slack-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# Slack Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for posting shop floor notifications from
  Connectware to Slack channels via incoming webhooks (Example)

metadata:
  name: Slack Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  alarmsWebhookPath:
    description: Webhook path for the machine alarms channel, without the host
    type: string

  milestonesWebhookPath:
    description: Webhook path for the production milestones channel, without the host
    type: string

  minimumSeverity:
    description: Lowest alarm severity that is posted to Slack
    type: number
    default: 3

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

resources:
  # Connection to the Slack webhook host, shared by all webhooks
  slackConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: hooks.slack.com
        port: 443

  # Posts machine alarms to the alarms channel
  alarmsEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref slackConnection
      write:
        path: !ref alarmsWebhookPath

  alarmsMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/alarms'
          publish:
            endpoint: !ref alarmsEndpoint
          rules:
            # Only alarms at or above the minimum severity reach Slack
            - filter:
                expression: !sub 'severity >= ${minimumSeverity}'
            - transform:
                expression: |
                  {
                    "body": {
                      "text": "Alarm " & code & " on "
                        & $context.vars.site & "/" & $context.vars.line & "/" & $context.vars.cell
                        & ": " & message & " (severity " & $string(severity) & ")"
                    }
                  }

  # Posts production milestones to the milestones channel as Block Kit messages
  milestonesEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref slackConnection
      write:
        path: !ref milestonesWebhookPath

  milestonesMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/milestones'
          publish:
            endpoint: !ref milestonesEndpoint
          rules:
            # The top-level text is the notification fallback for the blocks
            - transform:
                expression: |
                  {
                    "body": {
                      "text": "Production milestone: " & milestone,
                      "blocks": [
                        {
                          "type": "section",
                          "text": {
                            "type": "mrkdwn",
                            "text": "*Production milestone:* " & milestone
                          },
                          "fields": [
                            { "type": "mrkdwn", "text": "*Site*\n" & $context.vars.site },
                            { "type": "mrkdwn", "text": "*Area*\n" & $context.vars.area },
                            { "type": "mrkdwn", "text": "*Line*\n" & $context.vars.line },
                            { "type": "mrkdwn", "text": "*Cell*\n" & $context.vars.cell }
                          ]
                        }
                      ]
                    }
                  }