Technical docs
This page fcouses on how the app works, and is meant for developers wanting to collaborate. If any term is unclear, see the Glossary.
If you want to know how to use the app, then go to Getting started instead.
Interacting with Slack
This is a step-by-step diagram of what happens when a user interacts with the app from Slack.
sequenceDiagram
autonumber
participant U as User
participant S as Slack
participant A as The Arqivist
participant C as Confluence
U->>S: Interaction<br>(shortcut or slash)
Note left of U: user is waiting
S->>+A: Call matching endpoint
A->>S: Respond 200 immediately
Note over S,A: start contingency checks<br>(depends on endpoint)
break license is not valid
A-)U: inform user the license expired
end
break message is not in a thread
A-)U: Inform user that shortcuts only work in threads
end
A-)S: GET channel.info
break channel is private
A-)U: Ask user to invite the bot
end
A-)S: GET conversation.members
opt bot is not member of channel
A-)S: POST conversations.join
end
A-)C: CQL query for channel_id
opt thread or channel is already in Confluence
A-)U: Ask user if it's ok to overwrite existing page
end
Note over S,A: end contingency checks
A-)U: Show modal confirming action/requesting more info
Note left of U: sees modal
A--)S: GET conversation.history (`ch`)
U->>S: Confirm
Note left of U: user is waiting
S->>A: Call view_submission endpoint
loop For reply in `ch`
A->>S: GET user.info
end
A->>C: Create page
A->>-U: Feedback
Note left of U: user sees feedback, end
There are two ways to use the bot in Slack:
- Via a message shortcut
- Via the
/arqive
slash command
The message shortcut is present in the "More actions" or "three dots" button of each message. At the moment this method is only used for archiving message threads, because it's not possible to use slash commands within a thread.
Users can add arbitrary text to a slash commands, which makes them more flexible.
/arqive help
shows a message explaining how to use the bot, which actions are available, etc./arqive
prompts the archival of the current channel once/arqive [schedule]
prompts the continuous archival of the current channel (WIP)
Each of them will target a different endpoint in the app, namely /slack/shortcut
and /slack/slash
.
Regardless of the endpoint, or use-case, some conditions must be met in order for the bot to work properly.
We call these contingencies
internally, and they are checked on each request:
- is the origin of the request a message thread? (used for the shorcut)
- is the channel private?
- is The Arqivist a member of the channel?
- is the current
target
already in Confluence?
If all conditions are met, the user will see a modal for final confirmation of their action. Otherwise, they will receive a modal informing them that something is wrong, and they must take some action e.g. invite The Arqivist into the channel manually.