QBit Slack
Slack for a QQQ system. Users connect their own Slack accounts, and organization admins install the
app for their own workspace. The qbit registers a core messaging provider (slack) and a delivery
destination, so any process, scheduled job, report or export can send to a Slack DM or channel through
core alone. Every message is authorized as its owning user at send time, so the qbit is safe for
deployments with many tenants. Delivery uses a durable outbox with Slack rate-limit handling, and
classified PHI and PII never reach Slack.
Design: docs/DESIGN.md.
Requirements
- Java 21
- QQQ 4.1 (currently built against 4.1.0-RC.7)
- A Slack app created from docs/slack-app-manifest.yaml
Install
new SlackQBitProducer()
.withQBitConfig(new SlackQBitConfig()
.withBackendName("rdbms")
.withSchedulerName("scheduler"))
.produce(qInstance);
Tables, permissions and configuration
See docs/DESIGN.md, sections 3 to 14. The tables are prefixed slack_ and the
permissions slack.. Secrets are environment-variable names only: SLACK_CLIENT_ID,
SLACK_CLIENT_SECRET, SLACK_SIGNING_SECRET and SLACK_TOKEN_KEY.
Setup and starter data
No Liquibase changelog or host include is needed: the qbit seeds its own data at startup. The three
built-in templates (notification, digest, delivery) are inserted by SlackTemplates.seed()
when the host starts and on each readiness run. It is insert-only by name, so edits survive.
Everything else is host or runtime data, and every table explains itself when empty (help bundle
help/qbit-slack.yaml):
- An administrator runs "Install for my organization" (Connections). This creates the workspace.
- Each user runs "Connect Slack" so messages go out as them.
- Register the channels and user groups processes post to (Registered Channels, User Groups), then run "Check channels". It records the Slack name, private, bot is member, archived, purpose and checked time. Readiness refreshes them on a schedule.
- Review the built-in Templates.
Messages, Attempts and Interactions are logs and start empty.
Adopting in another app
Send with core SendMessageAction and the provider name slack, or deliver output to the slack
destination. Don't import this qbit's internal packages; com.kingsrook.qbits.slack.api is the only
public surface.
In-app help
The producer registers help/qbit-slack.yaml
with QQQ's help bundle registry. Hosts with help content enabled sync it at startup;
registration is harmless without a helpContent table. Live references use the host's current labels.
To override text, register a separate bundle with layer: HOST and the same entry keys
(and roles) using HelpBundles.register(qInstance, "help/your-host.yaml").
HOST entries take precedence over QBIT entries; user edits are preserved by core sync.
SlackTablesGuardrailTest.everyTableHasEmptyStateHelp runs HelpBundleAssertions over
Slack's produced metadata to check coverage, keys, summaries and live references during verify.
Build
./mvnw verify