Clause Library¶

The clause library is an admin feature that allows privileged users to manage document clauses (standard forms, subjectivities) without requiring a code deployment. It must be explicitly enabled per client implementation.

Enabling the clause library¶

Step 1: In applicationconfig/ui_config.json, enable the feature flag:

{
  "features": {
    "clauseLibrary": true
  }
}

Step 2: Add the DOC_ADMIN application role in role/{environment}/{environment}-roles.json:

{
  "mappedName": "SEND_DOC_ADMIN_DEV",
  "name": "DOC_ADMIN",
  "description": "Document Admin"
}

Users with this role can access the clause library admin interface to create, edit, and version clauses.

Clause configuration files¶

Two files per business class and placing type:

Config file — defines when a set of clauses applies:

document-clause/config/{bc}/{placing-type}.json

Field	Description
`businessClassTypeCode`	The LOB this clause config applies to
`placingType`	`OPEN_MARKET`, `MASTER`, `DEC`, etc.
`riskTypes`	Array: `NEW`, `MTA`, `RENEWAL`
`documentGenerationLevel`	`POLICY_GROUP` or `RISK`
`clausesFile`	Filename pointing to the clauses definition file

Clauses file — individual clause definitions:

document-clause/files/{bc}/clauses.json

Field	Description
`code`	Unique client-defined identifier (e.g. `C01`, `S01`)
`title`	Short display label
`description`	Full clause wording
`category`	`FORM` (standard clause), `SUBJECTIVITY`, or `OTHER` (raw HTML)
`selected`	`true` if the clause is pre-applied by default
`required`	`true` if the clause is mandatory and cannot be removed
`validFrom` / `validTo`	ISO 8601 date range. Clause only available when risk inception date falls within this range.
`subCategory`	Links to a `doc_clause_sub_category` business constant for filtering in templates.
`clientSpecificSearchCriteria`	Optional. Custom conditions requiring client microservice Java development.

Example clause definition¶

[
  {
    "code": "C001",
    "title": "War and Terrorism Exclusion",
    "description": "This policy excludes all losses arising from acts of war or terrorism as defined herein.",
    "category": "FORM",
    "selected": false,
    "required": false,
    "validFrom": "2024-01-01T00:00:00Z",
    "validTo": "2099-12-31T23:59:59Z"
  },
  {
    "code": "S001",
    "title": "Survey Required",
    "description": "Coverage is conditional upon completion of a satisfactory survey within 90 days of inception.",
    "category": "SUBJECTIVITY",
    "selected": true,
    "required": false,
    "validFrom": "2024-01-01T00:00:00Z",
    "validTo": "2099-12-31T23:59:59Z"
  }
]

Clause categories¶

Category	Behaviour in templates
`FORM`	Standard clause/form. Referenced via `{{#forms_and_subjectivities.FORM}}`
`SUBJECTIVITY`	Condition attached to the risk. Referenced via `{{#forms_and_subjectivities.SUBJECTIVITY}}`
`OTHER`	Raw HTML content. Referenced via `{{{formattedHtmlString}}}` (triple braces to avoid escaping)

Initial load and fail-safe¶

Set documentClauseConfiguration.initialLoadOnly: true in be_config.json to load clauses once from the repository. After the initial load, a flag file is written to S3 at:

s3://agateway.{env}.documents/{client}/document-clause-loader/initial_load_{bc}_completed.txt

Once this file exists, clauses are not reloaded even if initialLoadOnly is reset to false. From this point, clauses are managed through the admin UI. To force a reload, delete the flag file from S3.

Tip

Use initialLoadOnly: true for initial setup, then hand management over to the DOC_ADMIN user. This avoids accidental overwriting of clause changes made through the admin UI during a subsequent deployment.

Sub-categories¶

Sub-categories allow clauses to be grouped for filtered display in templates. Define sub-category codes in business-constants/doc_clause_sub_category.json and reference them on clause items using the subCategory field. In templates, use filterLoop to render only clauses with a matching sub-category.