Slack Flux Asset

Introduction

Slack is a cloud-based team communtication platform, primarily offered as a business-to-business service, with its userbase being predominantly team-based businesses.

SlackMQTT allows reciprocal communication, displaying and sending MQTT messages through Slack channels. This asset allows an easy integration between the Broker and the Slack Workspace, offering useful functionalities to manage your data directly from slack. Its versatility allows this asset to be highly personalized, designed to match your business requirements and needs, all from a familiar interface.

Features and Benefits

Seamless Communication: Enables seamless integration between Slack workspaces and MQTT clients, streamlining the exchange of data across platforms;
Real-Time Monitoring: Facilitates real-time data exchange between Slack and the broker, through Slack messages;
Easy Integration: Simplifies the integration of Slack with your IoT projects, making it possible to receive data from various IoT devices;
Reciprocal Communication: Also allows users to send messages to the broker directly through Slack workspaces.

Prerequisites

Before you install and configure the asset, make sure you have the following prerequisites:

Basic understanding of the MQTT Protocol;
Basic understanding of SlackApi App management;
Access to an MQTT broker compatible with your setup;
MQTT Client software (such as MQTT Explorer or similar);
Access to a Slack Workplace.

SlackApi App

To be able to use this asset, you need to have a SlackApi App in your slack workplace. Follow these steps to get your Slack App ready for this asset:

Go to Slack Api and navigate to Your Apps;
Create a new app from scratch, assigning a name and the desired workplace;
Go to Socket Mode and enable it, saving the app-level token as the AppLevelToken for the asset configuration;
Go to OAuth & Permissions and, under Bot Token Scopes, add the following:
- channels:history
- channels:read
- chat:write
- chat:write.public
- commands
- groups:history
- im:history
- im:write
- mpim:history
Go to Event Subscriptions, enable it and subscibe to these bot events:
- message.channels
- message.groups
- message.im
- message.mpim
Install the app in your workplace and add it to the desired channels inside the workplace;
Go to OAuth & Permissions and save the Bot User OAuth Token as the ApiKey for the asset configuration;
The SlackApp is now ready to integrate with the asset!

Asset Instalation

Using Coreflux HUB

Please refer to the general docs for asset installation through the Coreflux HUB.

Using Coreflux HUBLESS

Asset management and control are conducted using the MQTT protocol. Commands (payload) are sent to the $/Coreflux/Command topic. The results of these commands are published to $/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

Connect to the Coreflux MQTT Broker using your preferred client;
Login using your Coreflux Account:
```
-L myname@mydomain.com password
```
Check for available assets:
```
-l
```
Install the asset:
```
-I coreflux_slackmqtt
```
If there were no issues during the installation, you shoulf receive a message on the $/Coreflux/Command/Output:

Your coreflux_slackmqtt was installed with the version <version> with the <asset_guid>. Let the magic begin!

Asset Configuration

Before using the asset, it must be properly configured.
This configuration process entails adjusting various parameters that affect its functionality, the setup of the device, and how they interact with each other.
This involves specifying the device's IP address, selecting which symbols to read from the device, among other settings.

The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, Slack Parameters and Tags.
The instructions bellow serve as a configuration guide, for each section. By the end, you should have a comprehensive example configuration that can be tailored to your specific needs.

⚠ : If a parameter is not included in the asset's configuration and it is not required, a default value will be applied. Incorrect configuration may cause the asset to not work as intended.

ℹ : This configuration is presented using a hubless setup as an example. The key takeaway is the understanding of the parameters and their significance. If you are configuring the asset via Coreflux Hub, the same parameters and configurations apply.

MQTT Parameters

The MQTTParameters in the JSON configuration define how to connect to a MQTT Broker, specifying the communications details.

The Address and Port indicate the broker's network location (in this case, 127.0.0.1 on port 1883), which is where the data will be sent to or received from.
The parameters also detail authentication methods and use of TLS for secure communication.

This setup determines the pathway for the data exchange between the device and the MQTT broker, facilitating the monitoring or control of device operations

Parameter	Description	Required	Example	Default Value
Port	Port number on which the MQTT broker is running.	Yes	`1883`	`1883`
Address	IP address or hostname of the MQTT broker.	Yes	`"iot.coreflux.cloud"`	`"127.0.0.1"`
IsAnonymous	Indicates if the connection is anonymous (no username/password required).	No	`true`	`true`
Username	Username for authentication, if not anonymous.	No	`""` (empty string)	`""` (empty string)
Password	Password for authentication, if not anonymous.	No	`""` (empty string)	`""` (empty string)
WithTLS	Specifies whether TLS encryption is enabled for secure communication.	No	`true`	`false`
ClientId	Used to uniquely to identify the client to the MQTT broker.	Yes	`Client1`	`Random.Name.Generator`

Example:

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    }
}

Slack Parameters

Slack in the JSON configuration outlines the setup for the connection between the asset and the SlackApi. This parameter requires the API key, the Bot User OAuth Token, and the App Level Token available in your app, under the slack api website, after login.

Parameter	Description	Required	Example	Default Value
ApiKey	Bot User OAuth Token	Yes	`"xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ"`	`""`
AppLevelToken	App Level Token	Yes	`"xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD"`	`""`

Example:

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "Slack":{
        "ApiKey" : "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ",
        "AppLevelToken" : "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD"
    }
}

⚠ : It is recommended to keep these tokens hidden.

Tags

Tags are crucial components that simplify the set of actions the asset will perform in the workspace. Each Tag establishes a direct link to the topics and the channels/messages in the slack workspace to which you want the payload to go, as well as actions for said messages.
These tags configure the specifics of the slack messages and the MQTT communication, including the Action Type, to post, delete or update messages, the ChannelId of the slack workspace channel and the MessageURL of a targeted message for update actions, for example.

Parameter	Description	Required	Example	Default Value
Name	Unique Tag Identifier	Yes	`RoomTemperature`	`TagName`
Route	Specifies the direction of data flow within the system. Acceptable values are: 'ToSubscribers' (0), 'ToOther' (1).	Yes	`0`	`1`
Publish	Choose how data is sent. Acceptable values are: 'Update' (0), 'Cyclic' (1), 'Once' (2)	Yes	`0`	`2`
PublishCycle	Specifies the interval for publishing messages when 'publish' is set to 'Cyclic'. Must be a value between 1 and 86,400 seconds (24 hours).	No	`500`	`1`
MqttTopic	Unique Topic connecting with the specified Register	Yes	`"room/temp"`	`"mqtt/topic"`
MqttRetain	Defines if the message should be retained. Options are: true or false.	Yes	`true`	`false`
QualityOfService	Defines the level of delivery assurance for MQTT messages. The options are: AtMostOnce (0), AtLeastOnce(1), ExactlyOnce(1).	Yes	`2`	`2`
ActionType	Sets the action option for the tag. Options are: 'PostMessage' (0), 'DeleteMessage (1)', 'UpdateMessage (2)'.	Yes	`2`	``
ChannelId	Defines the channel where the payload will be sent to and/or message events will be registered	No	`C01234567AB`	`""`
MessageURL	URL of the message to manipulate	No	`https://slack.com/archives/C01234567AB/p1617891234567800`	`""`

Example:

href="#__codelineno-6-1">{ "MqttParameters": { "Port" : 1883, "Address" : "iot.coreflux.cloud", "IsAnonymous" : true, "UserName" : "", "Password" : "", "WithTLS" : false, "ClientId" : "ClientId1" }, "Slack":{ "ApiKey" : "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ", "AppLevelToken" : "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD" }, "Tags":[ { "Name" : "FromMqttToSlack", "Route" : 1, "Publish" : 0, "PublishCycle" : 127, "MqttTopic" : "room/temp", "MqttRetain" : true, "QualityOfService" : 0, "ActionType" : 0, "ChannelId" : "C01234567AB" }, { "Name" : "FromSlackToMqtt", "Route" : 0, "Publish" : 0, "PublishCycle" : 127, "MqttTopic" : "room/temp", "MqttRetain" : true, "QualityOfService" : 0, "ActionType" : 0, "MessageURL" : "https://slack.com/archives/C01234567AB/p1617891234567800" } ] }

⚠ : Tags for payloads from MQTT to Slack should use Route: ToOthers. From Slack to MQTT, use Route: ToSubscribers

⚠ : Don't fill both Channel Id and Message URL. Use Channel Id when posting messages. Use Message URL for the message updates.

Saving the Configuration

Asset management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : Configuration requires the user to be logged in and have an asset installed. If these requirements are not met, please refer to the installation section.

Save the configuration:

-assetConfigSave <asset_guid> <configuration>`

ℹ : The asset asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Example:

-assetConfigSave assetName {
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "Slack":{
        "ApiKey" : "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ",
        "AppLevelToken" : "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD"
    },
    "Tags":[
        {
            "Name" : "FromMqttToSlack",
            "Route" : 1,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "ActionType" : 0,
            "ChannelId" : "C01234567AB"           
        },
        {
            "Name" : "FromSlackToMqtt",
            "Route" : 0,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "MessageURL" : "https://slack.com/archives/C01234567AB/p1617891234567800"            
        }
    ]
}

2. Check if the configuration was saved (optional):

-assetConfigLoad <asset_guid>

Using the Asset

⚠ : It is important to understand that the flow of data between the broker and the device highly depends on the configuration of both the asset and the device. In case of unexpected results, please verify the configuration and/or check the logs for any possible errors.

With Coreflux HUB

Please refer the to general docs for asset installation through the Coreflux HUB.

With Coreflux HUBLESS

Asset management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $/Coreflux/Command topic. The results of these commands are published to $/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Run Asset

Run asset:

-R <asset_guid>

Stop Asset

Stop asset:

-S <asset_guid>

Logs

Logs are essential to monitor and debug your system. They provide insight into the operation of your assets and can help identify and resolve issues promptly.

With Coreflux HUB

On Coreflux HUB, the logs are displayed in the "Log" section of the asset configuration.

With MQTT Explorer

To display logs in MQTT Explorer, follow these steps:

Publish the following command to the $/Coreflux/Command topic:

-addTraceLog topic=topic/to/show/log level=Error/Information/Warning messageContains=(assetID)

2. The logs will be shown on the $/Coreflux/Log/Traces/topic/to/show/log topic.

Example1:

To display informational logs, use:

-addTraceLog topic=log/inf level=Information

Note : This will display the Logs "Information" of all the assets

Example2:

To display error logs, from a specific asset, use:

-addTraceLog topic=log/slack/err level=Error messageContains=assetID

Note : This will display the Logs "Error" of a specific asset

Note: To display all three types of logs (Error, Information, and Warning), you will need to repeat this process three times, one for each log level. three times, one for each log level.