Slack BSAR
Create a Slack channel for every SAR CoreEvent placed on a CloudTAK Board or created in a TAK Server Channel
Flow
This is an Outgoing task with an Incoming Webhook that receives Slack interactions. The TRIGGER environment picks
what starts the Slack flow:
- Board Placement - subscribe to
board:event:*,event:update&event:delete. When a CoreEvent is placed on the configured Board, and its type is one of the configured SAR types, a channel is opened. Moving the Event on the Board revives an archived channel and removing it from the Board archives the channel, keeping the mapping so a re-placed Event gets the same channel back. - Channel Event - subscribe to
event:*. When a CoreEvent is created in the configured TAK Server Channel, and its type is one of the configured SAR types, a channel is opened. Deleting the CoreEvent archives the channel, and updating a CoreEvent whose channel was archived revives it. The Layer’s Connection must also be a member of the Channel for the Event to be delivered to the Layer.
In both modes the channel is named <prefix>-<date>-<event name>, the configured users and User Group members are
invited, and the Event details are posted as a pinned Block Kit card with a stripe coloured by the Event priority. The
pinned message is rewritten with the current details
whenever the CoreEvent is updated, and the channel is archived when the CoreEvent is deleted. An updated CoreEvent that
qualifies for the trigger but has no channel - because the opening message was missed or failed, or Slack no longer
knows the channel - has one opened then, so an incident is never left without a channel.
The URL of the created channel is then appended to the links of the CoreEvent, and the links of the CoreEvent are
mirrored as bookmarks of the channel - kept up to date whenever the CoreEvent is updated. Bookmarks are added and
retitled but never removed.
Created channels are tracked in the Layer’s ephemeral store by CoreEvent ID so an Event never gets a second channel.
Interactive Controls
When SLACK_SIGNING_SECRET is set the pinned card carries controls acted on by the Layer through its Webhook URL, which
is set as the Interactivity Request URL of the Slack App - see Slack Installation:
- Assign Me - assigns the pressing Slack user to the CoreEvent by their Slack display name, unless already assigned
- Close Incident / Reopen Incident - ends the CoreEvent now, after a confirmation, or clears its end. A closed Event shows a Closed status and a grey stripe
- Priority - a selector that sets the priority of the CoreEvent
Every interaction is verified against the Signing Secret of the App over the raw request body, acted on with the
permissions of the Layer, and reported back to the channel as a line naming the Slack user. The resulting event:update
then rewrites the pinned card with the new state. The Webhook invocation is on by default and has no settings of its
own - everything is configured on the Outgoing side. Without the secret the card carries no controls and the Webhook
rejects every request.
If SLACK_ANNOUNCE names a main channel, an incident card is posted there whenever a channel is opened or reopened - so a
team watching one channel learns of every new incident. The card carries a stripe coloured by the Event priority, the
Event details, the first 200 characters of the remarks, a button into the incident channel and a button to the CoreEvent
in CloudTAK - the pinned card in the incident channel carries the remarks in full. The card is kept current with the
Event alongside the pinned card, so once the CoreEvent is ended it is headed Closed Incident with a Closed status and
a grey stripe, and a reopened incident posts a fresh card that is tracked from then on.
| Permission | Required | Description |
|---|---|---|
event:read, event:update |
No | Append the Slack channel URL to the links of the CoreEvent, and close, reopen or reprioritise it from the pinned card |
assignment:read, assignment:create |
No | Assign the Slack user pressing Assign Me to the CoreEvent |
| Environment | Description |
|---|---|
SLACK_TOKEN |
Slack User OAuth Token (xoxp-) with channels:write, channels:read, groups:write, groups:read, chat:write, pins:read, pins:write, bookmarks:read, bookmarks:write, usergroups:read & users:read user scopes - see Slack Installation. Channels are created & messages posted as the User that installed the App. A Bot User OAuth Token (xoxb-) with the equivalent bot scopes (channels:manage in place of channels:write) also works |
SLACK_SIGNING_SECRET |
Optional Signing Secret of the Slack App (Basic Information => App Credentials) - enables the Interactive Controls of the pinned card |
SLACK_PRIVATE |
Create private channels instead of public ones |
SLACK_PREFIX |
Prefix of created channel names |
SLACK_INVITE |
Slack User IDs invited to every created channel |
SLACK_USERGROUP |
Optional Slack User Group, by @handle or name, whose members are invited to every created channel - User Groups are a paid Slack feature |
SLACK_ANNOUNCE |
Optional main channel, by ID or #name, where an incident card linking to the incident channel is posted whenever one is opened or reopened and rewritten as the Event changes or closes - the token User must be a member of it |
TRIGGER |
Board Placement with the ID of the CoreEvent Board to watch, or Channel Event with the TAK Server Channel ID to watch |
SAR_TYPES |
MIL-STD-2525E Symbol IDs considered SAR - every Event is accepted if empty |
Slack Installation
The ETL authenticates as the User that installs the App via a User OAuth Token. Channels are created & messages posted as that User, who is automatically a member of every channel they create - so the App has no Bot User.
- Create the CloudTAK Layer first and copy its Webhook URL from the Incoming configuration - Webhooks Delivery is
on by default - into the
request_urlof the manifest below. Leave theinteractivityblock out to skip the Interactive Controls - Navigate to Slack App Management and select the workspace you want to install the integration into
- Select Build in the top right corner
- From the Your Apps page click the green Create New App button & select From a manifest
- Select the workspace, then paste the following manifest into the JSON tab
{ "display_information": { "name": "CloudTAK BSAR", "description": "Create a Slack channel for every SAR CoreEvent placed on a CloudTAK Board or created in a TAK Server Channel", "background_color": "#1f2937" }, "oauth_config": { "scopes": { "user": [ "channels:read", "channels:write", "groups:read", "groups:write", "chat:write", "pins:read", "pins:write", "bookmarks:read", "bookmarks:write", "usergroups:read", "users:read" ] } }, "settings": { "interactivity": { "is_enabled": true, "request_url": "https://webhooks.example.com/<layer uuid>" }, "org_deploy_enabled": false, "socket_mode_enabled": false, "token_rotation_enabled": false }}- Review the App summary and then select Create & Install - install it as the User the channels should be created by
- Click Go To App Settings, select OAuth & Permissions on the left, and copy the User OAuth Token
(
xoxp-) into theSLACK_TOKENfield of the CloudTAK Layer - For the Interactive Controls, select Basic Information and copy the Signing Secret under App Credentials
into the
SLACK_SIGNING_SECRETfield of the Layer - cards pinned from then on carry the controls
Development
DFPC provided Lambda ETLs are currently all written in NodeJS through the use of a AWS Lambda optimized Docker container. Documentation for the Dockerfile can be found in the AWS Help Center
npm installAdd a .env file in the root directory that gives the ETL script the necessary variables to communicate with a local ETL server.
When the ETL is deployed the ETL_API and ETL_LAYER variables will be provided by the Lambda Environment
{ "ETL_API": "http://localhost:5001", "ETL_LAYER": "19"}To run the task, ensure the local CloudTAK server is running and then run with typescript runtime or build to JS and run natively with node
ts-node task.tsnpm run buildcp .env dist/node dist/task.jsDeployment
Deployment into the CloudTAK environment for configuration is done via automatic releases to the DFPC AWS environment.
Github actions will build and push docker releases on every version tag which can then be automatically configured via the CloudTAK API.
Builds are performed by the cloudtak-etl script provided by @tak-ps/etl.
It requires a capabilities.json document alongside the Dockerfile which describes the task (name, description,
compute requirements, permissions & invocation types) and is validated and embedded in the OCI Image Manifest as a
com.cloudtak.capabilities annotation so CloudTAK can read it directly from ECR before the task is ever deployed.
Update capabilities.json whenever the task’s requirements change.
To build & push manually:
export AWS_REGION='us-east-1'export AWS_ACCOUNT_ID='123456789012'export Environment='prod' # Optional - defaults to prod
npx cloudtak-etlNon-DFPC users will need to setup their own docker => ECS build system via something like Github Actions or AWS Codebuild.