What this is about
An approval chain sets who must review a submitted revision before it renders. It consists of stages that run one after the other. Every stage names a CIAS role. Whoever has this role may approve at this stage.
A stage
| Entry | Meaning | Default |
|---|---|---|
name | what the stage is called, for people, at most 64 characters | — (required) |
role | the CIAS role that approves at this stage | — (required) |
minimum-approvers | how many different people approve before the stage is done | 1 |
author-excluded | whether the person who submitted is excluded here | true |
meaning | what an approval states here: REVIEWED (checked) or APPROVED (released) | — (required) |
The meaning is in the chain together with person and time. So every approval says explicitly whether someone only reviewed the content or released it. Rules such as 21 CFR Part 11 ask exactly that of a signature.
The way through the stages
-
UserStage 1: Subject reviewRole
report-reviewer, not the author, at least 1 person↳ no The revision stays in review, or someone rejects it -
UserStage 2: ReleaseRole
quality-lead, not the author, at least 2 people↳ no The revision stays in review, or someone rejects it - The revision is PUBLISHED, the previous one becomes SUPERSEDED
The stages run in their order. As long as stage 1 is not done, nobody can approve stage 2. Whoever has the role of stage 2 but not the one of stage 1 has to wait.
What is checked on an approval
POST /crms/revisions/{revision}/approve has no body. Who approves comes from the token.
| Revision in review? | Already approved? | Role of the current stage? | Author, and the stage excludes them? | What happens |
|---|---|---|---|---|
| no | – | – | – | 409 template-revision-not-in-review |
| yes | yes | – | – | 409 approval-already-given |
| yes | no | no | – | 403 approval-role-missing |
| yes | no | yes | yes | 403 approval-author-excluded |
| yes | no | yes | no | The approval counts. If it is the last approval needed at the last stage, the revision is published |
“Already approved” means: this person has already approved this revision once, at any stage. A person approves a revision only once, even if they have the roles of several stages. Otherwise two stages with the same person would be only one pair of eyes.
Who can see a revision at all
Only someone who can reach the revision can approve it:
- System templates: every person with the role of the stage.
- Tenant templates: people of the same tenant with the role of the stage.
- Person templates: the reviewers of this person’s tenant. They cannot see the template otherwise, but they review it.
For everyone else the revision does not exist: 404 template-not-found.
Rejecting
POST /crms/revisions/{revision}/reject with {"reason": "…"}. Whoever has the role of the current stage may reject. The reason is always required. A rejection ends the review at once, at whatever stage. What happens next is described in Life cycle.
Where the chains are defined
The chains belong to the project. You define them in the hub on the project’s CRMS module, in the area “Approval”, field approvalStages. There, every stage also has a scope (USER, TENANT or SYSTEM) and a sortOrder for the order.
On the build, the generator writes the file crms-configuration.yaml from it:
codamai:
crms:
template:
approval:
tenant:
- name: Subject review
role: report-reviewer
meaning: REVIEWED
- name: Release
role: quality-lead
minimum-approvers: 2
meaning: APPROVEDA scope missing from the file has no stages. In the example, person and system templates are therefore published at once, tenant templates go through two stages.
The chain is stored in the revision
On submit, CRMS writes the whole chain that applies at that moment into the REVISION entry. The revision runs through exactly these stages. If a new build brings another chain, it only applies to revisions submitted afterwards. So the chain of every revision can still be proven later.