james.maesandClaude Opus 5.5
36def54b8b
Host-neutral help (deployment-specific facts removed), registered with HelpBundles, gated by HelpBundleAssertions. QQQ 4.1.0-RC.7. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
3.2 KiB
Markdown
80 lines
3.2 KiB
Markdown
# 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](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](docs/slack-app-manifest.yaml)
|
|
|
|
## Install
|
|
|
|
```java
|
|
new SlackQBitProducer()
|
|
.withQBitConfig(new SlackQBitConfig()
|
|
.withBackendName("rdbms")
|
|
.withSchedulerName("scheduler"))
|
|
.produce(qInstance);
|
|
```
|
|
|
|
## Tables, permissions and configuration
|
|
|
|
See [docs/DESIGN.md](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`):
|
|
|
|
1. An administrator runs "Install for my organization" (Connections). This creates the workspace.
|
|
2. Each user runs "Connect Slack" so messages go out as them.
|
|
3. 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.
|
|
4. 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](src/main/resources/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
|
|
|
|
```bash
|
|
./mvnw verify
|
|
```
|
|
|
|
## License
|
|
|
|
Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|