Confluence app
The Plotwork app for Confluence Cloud shows a diagram from your organisation's private library on a Confluence page. Only people who can read the page see it. The diagram has no public link, and no reader's browser ever holds your Plotwork key.
- Confluence
TL;DR
| Question | Answer |
|---|---|
| What does it add? | A Plotwork diagram macro, and a Plotwork page in Confluence settings. |
| Who sets it up? | A Confluence site admin, once, with an organisation API key. |
| Who sees a diagram? | Everyone who can read the page it is on. Confluence decides that, as it does for the rest of the page. |
| Where is the key kept? | In the app's encrypted Forge storage. It is never shown again, and admins see only its last four characters. |
| Who fetches the diagram? | The app's backend, on Atlassian's servers, with the key. The reader's browser receives a cleaned picture and nothing else. |
| Does Plotwork store anything for the app? | No. Each view fetches the diagram, and neither the app nor Plotwork keeps a copy. |
| Light or dark? | Each macro matches Confluence by default, or stays light or dark. |
| Which hosts does it call? | api.plotwork.dev, or api-preview.plotwork.dev when connected to preview. No other. |
1. Connect your organisation
You need to be a Confluence site admin, and an owner or admin of the Plotwork organisation.
- In Plotwork, open your organisation, then Keys, and make an organisation key. A key that can read the library is enough.
- In Confluence, open Settings, then Apps, then Plotwork.
- Enter the organisation's slug (the
acmeinapp.plotwork.dev/orgs/acme) and paste the key. - Choose Connect. The app tries the key against your library first, so a wrong key or slug is said at once and nothing is stored.
The page then shows the organisation, the last four characters of the key, and when it was connected. Test the connection tries the key again and says how many diagrams the library holds.
2. Show a diagram on a page
- In Plotwork, open the diagram in your organisation's library and copy the page's address, such as
https://app.plotwork.dev/orgs/acme/diagrams/2f6b1c1e-8c1d-4d3e-9a7b-5c2e1f0a9b8c. - In a Confluence page, type
/Plotwork diagramand insert the macro. - Paste the address. The preview shows the diagram as the page will.
- Choose the colours and, if you like, a caption, then Save.
| Setting | What it does |
|---|---|
| Diagram address | The diagram's portal address. It must be in the connected organisation. |
| Colours | Match Confluence follows each reader's Confluence theme. Light and Dark stay fixed. A diagram drawn in one scheme only keeps that scheme. |
| Caption | Optional text under the diagram, up to 200 characters. |
Under the diagram, Open in Plotwork opens it in the portal for people who are members of the organisation.
3. Let editors choose from the library
By default, editors paste an address. On the Plotwork settings page, Let page editors choose from the library adds a searchable list of the library to the macro's settings. It shows each diagram's name and folder to anyone who can edit a page, so leave it off if names should not be seen that widely. Readers of a page never see the list.
4. Who can do what
| Person | Can |
|---|---|
| A reader of the page | See the diagram the macro saved. They cannot ask the app for any other diagram. |
| An editor of the page | Paste an address and preview it; choose from the library when the admin allows it. |
| A Confluence site admin | Connect, test, turn library browsing on or off, and disconnect. |
| An owner of the Plotwork organisation | Revoke the key in Plotwork at any time. Every macro then stops showing diagrams. |
The app checks each of these on every call, with Confluence's own answer for the person asking.
5. Messages and what to do
| The macro says | Why | What to do |
|---|---|---|
| Plotwork is not connected | No admin has connected the app, or it was disconnected. | A site admin connects it in Settings, Apps, Plotwork. |
| The Plotwork key was refused | The key was revoked, expired, or deleted. | A site admin connects again with a current organisation key. |
| This diagram is not in the connected library | The diagram was deleted, or it belongs to another organisation or environment. | Edit the macro and choose another diagram. |
| Your Plotwork plan does not include Confluence | The organisation's plan does not include the app. | An owner changes the plan in Plotwork. |
| You cannot open this here | Previewing and browsing are for editors of the page. | Ask an editor of the page. |
| Plotwork is busy, or had a problem | A short limit or an error at Plotwork. | Reload the page in a minute. |
| Plotwork could not be reached | The call from Atlassian to Plotwork failed. | Reload the page; a site admin can test the connection. |
6. How it keeps diagrams private
| Part | How |
|---|---|
| The key | Stored with Forge's setSecret, encrypted at rest. No function of the app returns it. |
| The fetch | The app's backend calls the Plotwork API with the key. The macro in the reader's browser calls only the app. |
| The picture | Cleaned of scripts, links, outside addresses, and embedded pages, then shown as an image, which runs no code. |
| The diagram named | Read from the macro's saved settings, never from what the browser sends. |
| Outside hosts | The manifest allows only the Plotwork API. Confluence refuses any other call the app could make. |
| Storage | The app keeps the organisation's slug, the key, and the browse setting. No diagram. |
To disconnect, open Settings, Apps, Plotwork and choose Disconnect. The app forgets the key, and every macro on the site shows Plotwork is not connected until someone connects again. Revoking the key in Plotwork has the same effect from the other side.
See also
| Page | Why |
|---|---|
| Organisations | The library, organisation keys, and roles |
| Slack, email, Confluence, and Notion | Paste a diagram into a public page without the app |
| Hosted diagrams | Public links, for pages that do not need access control |
| Privacy policy | What Plotwork stores, and what it does not |