Classification labels and publish approval

TL;DR

1. The labels

The library shows the label under each diagram's name as a mark and a word, and the list can be narrowed to one label. Every member, readers included, sees the labels.

Which label a new diagram gets

A publish can name its label (classification on publish_diagram and on POST /v1/diagrams/publish). Left out, the diagram takes the default of the deepest folder on its path that has one, and otherwise the organisation's default, Internal unless an owner or admin chose another. An agent's auto-publish takes the folder default the same way.

A member may choose a label at or above that default. A label below it is for the owner and admins, and is refused with 403 orgs.forbidden for anyone else.

Changing a label

Change a label from the row's menu in the library, or with Change beside the label on the diagram's page. The API is PATCH /orgs/{org}/diagrams/{id}/classification.

A lock does not stop a label change. Each change is recorded as orgs.diagram.classify with the label before and after.

Labels and public links

The label in the files

The stored picture carries the label in one empty metadata element, <metadata data-classification="confidential"/>, beside its id. It is never drawn on the picture. A public link's copy keeps it. A PNG or PDF exported from the diagram's page is named with the label at the end, such as card-vault-confidential.png.

2. Publish approval

Set it on the Settings tab, under Approval. The owner and admins choose.

What is held

Only the owner and admins make organisation keys from the Keys tab, and they publish directly, so a key does too by default. An agent connection is its member, so it is held whenever that member would be. An organisation key never makes a public link.

The Approvals queue

Approvers have an Approvals section under Governance, with the number waiting beside its name. Each request shows:

Approve shows a new diagram to the library, puts a new version in place (the one before is kept as a previous version), or makes the public link with every check of a share run again. Reject deletes a new diagram, drops a new version, or makes no link. Either takes an optional comment of up to 500 characters. The publisher is emailed the outcome with the comment. Nobody decides what they asked for themselves.

A legal hold refuses a rejection of a new diagram, as it refuses every delete. An approval still goes ahead.

Below the queue, the requests decided or ended in the last 30 days are listed with their outcome.

Expiry

A request nobody decides ends 30 days after it was made. The daily sweep ends it as a rejection does and records orgs.diagram.approval_expire, with "Approval policy" as the actor. An organisation on legal hold keeps its held diagrams until the hold ends.

Approval and secret scanning

Secret scanning runs first. Under Block, a publish with a finding is refused and never reaches the queue. Under Warn it is held like any other, and the queue shows how many findings it has.

3. What an agent sees

A held publish is an answer, never an error:

Held for approval by your organisation: the diagram is stored in the Acme Team library, but only you and its approvers can see it until an approver approves it. (warning W601)Stored in the private library of "Acme Team", waiting for approval: https://app.plotwork.dev/orgs/acme-team/diagrams/5d1d7c8e-3f0a-4f6e-9a55-0d7c9b1f2a10

The structured answer carries approval (state, requestId, kind, expiresAt, message, code) and a W601 warning. An auto-publish that was held carries the same warning among the drawing's warnings, and autoPublished.approval. The agent should tell the person and not publish again.

4. What the audit log records

None holds a folder's path or a diagram's source. On Enterprise they are sent to your SIEM like every other event.

See also