The CRMS module in the hub

What this is about

A project in the hub can have one CRMS module. It holds what the project decides about reports once, before the system even exists: whether final documents are kept, for how long, whether they are sealed, which formats exist, who writes templates and who approves them. A final document is a report that CRMS stores as evidence. More on this in What a final document is.

You edit the module in the CRMS portal, a user interface in the hub. The hub opens it from the project. The portal does not manage the templates or documents of a running installation. It only edits the model.

A project has at most one CRMS module. If it has two, the export of the project stops. Every protected CDMS module of the project uses this one CRMS module.

From the hub into the build

1

Hub
holds the CRMS module with its fields, its approval stages and the runtime it is placed in
2

Hub→Build
exports the module as crms.yaml, next to cias.yaml
3

Build
reads crms.yaml and derives the placement
4

Build
module in no runtime, or in the runtime of a public CDMS module → the build stops and names what to model
5

Build
puts the CRMS dependencies into the pom.xml, depending on the placement and the chosen formats
6

Build
writes crms-configuration.yaml on every build when CRMS is embedded

Result: The application imports the file at start. An environment variable overrides every value from it.

The placement: where the module runs

There is no field for “embedded or separate service”. The build derives it from which runtime the CRMS module is placed in. In the hub, a runtime is a process that modules run in.

What a protected CDMS module makes of the placement

embeddedseparate serviceruntime with CRMS onlynot placedno CRMS module

When: The CRMS module is in the same runtime as the CDMS module.

CRMS runs in the process of the application. The pom.xml gets crms-spring-boot-starter, crms-document, crms-storage-s3, crms-rest and the format modules of the chosen formats. The configuration gets codamai.crms.placement: local and imports crms-configuration.yaml.

Result: Templates, rendering, final documents and their evidence run in the application. Under /crms the routes are also available to the other CDMS modules of the project.

When: The CRMS module is in another runtime, as a CRMS service of its own or embedded in another CDMS module of the project.

The CDMS module is a client. The pom.xml gets crms-spring-boot-starter and crms-client, the configuration codamai.crms.placement: remote. The address comes from CODAMAI_CRMS_CLIENT_URL.

Result: The CDMS module renders nothing itself. It calls the CRMS service with the caller's token.

When: The CRMS module is in a runtime without a CDMS module.

This becomes a standalone CRMS service. The hub offers its project scaffold as a ZIP download. For an embedded or unplaced module, the hub refuses the download.

Result: A Maven project that reads the CRMS module from the hub on every build.

When: The CRMS module is not in any runtime yet.

While modeling, this is a valid state. A build of a protected CDMS module then stops: it does not know whether CRMS is embedded or a service.

Result: Build refused, with the hint to place the CRMS module in a runtime.

When: The project has no CRMS module.

The build adds nothing from CRMS.

Result: The application has no CRMS.

CRMS needs CIAS. CRMS asks CIAS for the tenant and passes the caller’s token on. A public CDMS module (authentication: NONE) has neither, so it never gets a CRMS part. If the CRMS module is placed in the runtime of a public CDMS module, the build refuses.

The fields

Every field is optional. “Empty” means: the field is not written, and the column “CRMS default” applies.

Field	What it sets	Variable	CRMS default
`documentRevisions`	whether final documents are stored. Off: a `FINAL` render is refused	`CODAMAI_CRMS_DOCUMENT_REVISIONS`	`true`
`documentRetention`	how long a final document is kept, as an ISO-8601 period, e.g. `P10Y`	`CODAMAI_CRMS_DOCUMENT_RETENTION`	none, required while documents are stored
`documentStorePayload`	whether the data of a final document is stored with it, encrypted	`CODAMAI_CRMS_DOCUMENT_STORE_PAYLOAD`	`true`
`auditReads`	whether every read of a final document also goes into the journal, not only the writes	`CODAMAI_CRMS_AUDIT_READS`	`false`
`sealMode`	the seal of PDF documents: `INTERNAL` or `NONE`	`CODAMAI_CRMS_SEAL_MODE`	`internal`
`formats`	which formats are built and offered: `PDF`, `DOCX`, `XLSX`, `ODS`, `CSV`	none, see below	every format
`pdfProfile`	the PDF profile when a request names none: `NONE`, `PDF_A_3A`, `PDF_UA`, `PDF_A_3A_UA`	`CODAMAI_CRMS_PDF_PROFILE`	`PDF_A_3A`
`templateScopes`	which template scopes exist: `USER`, `TENANT`, `SYSTEM`	`CODAMAI_CRMS_TEMPLATE_SCOPES`	all three
`templateReasonRequired`	whether submit, roll back and retire need a reason. On rejection it is always required	`CODAMAI_CRMS_TEMPLATE_REASON_REQUIRED`	`true`
`templateRoleUser`	the role that writes a user’s own templates	`CODAMAI_CRMS_TEMPLATE_ROLES_USER`	`crms-template-personal`
`templateRoleTenant`	the role that writes a tenant’s templates	`CODAMAI_CRMS_TEMPLATE_ROLES_TENANT`	`crms-template-author`
`documentRoleRead`	the role that reads final documents	`CODAMAI_CRMS_REST_DOCUMENT_ROLES_READ`	`crms-document-reader`
`documentRoleHold`	the role that places and releases a hold against erasure (legal hold)	`CODAMAI_CRMS_REST_DOCUMENT_ROLES_HOLD`	`crms-document-custodian`
`documentRoleErase`	the role that erases a document	`CODAMAI_CRMS_REST_DOCUMENT_ROLES_ERASE`	`crms-document-eraser`
`approvalStages`	the approval stages per scope, see below	none	no stage: published directly

A scope says who a template belongs to: the platform (SYSTEM), a tenant (TENANT) or a user (USER). See Structure of a template. The roles are client roles in CIAS, see Roles in CRMS.

Two more fields are in the model: approvalReauthenticate and approvalTenantDefined. The build does not read them. They change neither the configuration nor the environment.

What the file contains

The build writes every field that is set as ${VARIABLE:value}. This is the Spring notation for “take the variable, otherwise this value”. The reports of the hub, for example, store no documents, do not seal and allow system templates only. Their build writes:

# Generated on every build from the CRMS module of this project in the CodamAI hub
codamai:
  crms:
    document:
      revisions: "${CODAMAI_CRMS_DOCUMENT_REVISIONS:false}"
    seal:
      mode: "${CODAMAI_CRMS_SEAL_MODE:none}"
    template:
      scopes: "${CODAMAI_CRMS_TEMPLATE_SCOPES:SYSTEM}"

Empty fields are missing from the file. The file is not edited by hand: the next build overwrites it.

Formats decide the `pom.xml`

formats is not the default of a variable. The field decides which format modules go into the pom.xml. CRMS then offers what is installed.

Format	Module in the `pom.xml`
`PDF`	`crms-format-pdf`
`DOCX`	`crms-format-word`
`XLSX`, `ODS`, `CSV`	`crms-format-table`, once for all three
HTML	none: HTML is built into the CRMS renderer and always there
field empty	every format module

A CDMS module that only uses CRMS as a client gets no format module. It renders nothing itself.

The approval stages

An approval is the consent given before a submitted template is published. Per scope, the project can set a chain of stages. Every stage has these fields:

Field	Meaning	empty
`scope`	`USER`, `TENANT` or `SYSTEM`	required
`sortOrder`	order within the scope	goes last
`name`	what the stage is called	required
`role`	the CIAS role of the approvers	required
`minimumApprovers`	how many different people must agree	`1`
`authorExcluded`	whether the author is excluded	yes
`meaning`	what an approval states: `REVIEWED` or `APPROVED`	required

The build writes the stages in the order of sortOrder to codamai.crms.template.approval.<scope>:

codamai:
  crms:
    template:
      approval:
        tenant:
          - name: Subject review
            role: crms-template-reviewer
            meaning: REVIEWED
          - name: Approval
            role: crms-template-approver
            minimum-approvers: 2
            meaning: APPROVED

(The role names are an example.) The stages have no environment variable. An approval chain that an environment could switch off would not be one. A scope without a stage publishes a submitted template at once. How the chain runs is described in Approval.

Notes in the portal

The portal checks the module while you edit and shows notes. It only blocks saving for approval stages that the model itself refuses.

Area	Situation	What the portal says
Approval	stage without name, role or meaning, or fewer than 1 person	Error, saving blocked
Documents	`documentRetention` is not a readable period	Error
Output	unknown format	Error
Documents	`documentRevisions` off	Warning: no final documents
Approval	last stage is not `APPROVED`	Warning
Documents	retention empty, documents on	Note: value comes from the environment
Templates	`SYSTEM` admitted	Note: CIAS must name platform administrators
Approval	scope without a stage	Note: publishes directly

The CRMS module in the hub

What this is about

From the hub into the build

The placement: where the module runs

The fields

What the file contains

Formats decide the `pom.xml`

The approval stages

Notes in the portal

Pitfalls

Next

What this is about

From the hub into the build

The placement: where the module runs

The fields

What the file contains

Formats decide the pom.xml

The approval stages

Notes in the portal

Pitfalls

Next

Formats decide the `pom.xml`