Configuration Standards & Best Practices¶

This document defines the mandatory standards, recommended patterns, and architectural rules that all Send Workbench configuration work must follow. Each standard is tagged with a severity indicating the consequence of non-compliance.

Severity	Meaning
🔴 Critical	Platform will not function correctly or data integrity is at risk
🟠 High	Significant operational risk, security exposure, or likely production incident
🟡 Medium	Poor maintainability, hidden cost to the team, or likely to cause issues at scale
🟢 Low	Style, consistency, or future-proofing concern

1. Repository Structure¶

1.1 Understanding the Repository You Work In¶

When you begin configuring a new client, DevOps will provide you with access to a repository that has been provisioned from the base repository. Your job as a configurator is to adapt that base configuration to the specific client and business types being set up — this means removing files that do not apply and building out the configuration that does.

DevOps Responsibility

Repository creation, naming, and initial provisioning are handled by DevOps. If a repository has not been set up for your client yet, raise a request with DevOps before beginning any configuration work.

1.2 Directory Structure¶

The base repository follows a standard directory layout. All configuration work must be done within this layout. Do not rename, reorganise, or add top-level directories.

config/
  {clientname}/
    applicationconfig/
      be_config.json
    business-class/
    actions/
      {business-class-code}/
    pipelines/
    rating/
      config/
        {business-class-code}/
      files/
        {business-class-code}/
    document-templates/
    dua/                      # DUA clients only
dynamodb/
  dev/
    data.json
  sit/
    data.json
  uat/
    data.json
  prod/
    data.json

DynamoDB files are part of your configuration work

The dynamodb/ directory and its data.json files per environment are part of the config repository and should be edited directly — treat them like any other file in the repo. For any non-local environment, raise a Deploy DynamoDB Changes request in the Send Partner Portal. DynamoDB changes require a service restart — this is handled as part of the portal request.

🔴 Critical — Services resolve all config paths at runtime using the customerImplementationDir value set in DynamoDB. Any deviation from the standard directory layout will cause services to fail silently or load the wrong configuration.

1.3 Confirm customerImplementationDir With DevOps Before First Deployment¶

The customerImplementationDir field in DynamoDB must exactly match the directory name used inside config/. Set this value in dynamodb/{env}/data.json and verify it is correct before raising a deployment ticket.

{
  "customerImplementationDir": "hartford"
}

If this value is wrong or missing, raise it with DevOps immediately — do not attempt to work around it in the config files.

🔴 Critical — A mismatch causes services to fall back to a default config silently, which has caused production incidents on other clients.

2. The Two Configuration Domains¶

2.1 Know What Goes Where¶

Configuration is split across two domains. Putting config in the wrong domain is one of the most common mistakes a configurator can make.

Config Type	Domain	Where it lives
Business rules, actions, pipelines, forms, documents, feature switches, `be_config.json`, `ui_config.json`	Business Config	Files in the Git repository under `config/` — deployed via the Send Partner Portal (Client Build & Deploy for Dev; Create/Deploy Client Microservice Version for SIT/UAT)
Environment URLs, credentials, queue names, environment-specific routing	Environment Config	`dynamodb/{env}/data.json` only — deployed via Deploy DynamoDB Changes request in the Partner Portal

The content separation is clear from the repository structure: everything under config/ is business config; dynamodb/{env}/data.json is the environment profile. be_config.json sits in config/ — it is not part of the environment profile.

🔴 Critical — Never put environment-specific values (URLs, credentials, queue ARNs) into S3 config files. They cannot be rotated per environment and will cause environment bleed.

2.2 Feature Switches Belong in be_config.json, Not in Actions¶

Feature switches live in the featureSwitches field of be_config.json (S3 business config). Note that featureSwitches is stored as a JSON-encoded string, so switches are toggled inside the embedded JSON, for example:

"featureSwitches": "{\"DUA\": true, \"PAS\": true}"

Feature switches must not be replicated or overridden inside action or pipeline files.

🟠 High — Duplicating feature switch logic in actions creates divergence and makes future platform upgrades unpredictable.

2.3 homePartyId Must Be the Client's Real DUNS Number¶

The homePartyId field in be_config.json must be set to the client's real 9-digit D&B DUNS number in all non-local environments. The placeholder value is acceptable in local dev only.

"homePartyId": "urn:duns:108383579"

🟠 High — An incorrect homePartyId will cause party matching, sanctions, and Lloyd's bureau submissions to operate against the wrong entity.

3. Business Type Configuration¶

3.1 Configure Only the Business Types the Client Actually Writes¶

The base repository contains configuration covering all possible business types. You must remove all files that do not apply to the client before the first deployment.

Business Type	Files to Keep	Files to Remove
Open Market only	`open_market_submission_config.json`, `actions/open-market/`	All MGA, DEC, bordereau, DUA files
MGA / Binding Authority	`master_submission_config.json`, `dec_submission_config.json`, `actions/master/`, `actions/dec/`	Open market and DUA files
DUA	Open market config + `dua/` directory, `actions/dua/`	MGA-specific files

Refer to the New Client Setup Guide for the exact file deletion list per business type.

🟠 High — Orphaned files from the base repository are picked up by the platform in some contexts and cause unexpected UI options and workflow paths to appear for users.

3.2 DUA Configuration Requires Both be_config.json and a dua/ Directory¶

Enabling DUA requires changes in two places. Both must be present:

be_config.json must contain featureSwitches.DUA: true (inside the JSON-encoded featureSwitches string) and a duaConfig block with at least duaImplementationDir set. The business class must also have MASTER in its enabledPlacingTypes.
A DUA implementation directory (typically dua/) must exist at the root of the client config holding the relevant DUA configuration.

Missing either half will result in DUA appearing enabled in the UI but the underlying pipeline failing.

🔴 Critical

3.3 DUA-CH is a Reserved Business Class¶

The DUA-CH business class type code is a platform-reserved coverholder class used exclusively for DUA submission processing. It must not be added to Open Market or MGA-only clients.

🔴 Critical — Adding DUA-CH to a non-DUA client will register incorrect coverholder options in the UI and corrupt the submission type selection.

3.4 MGA Clients Must Enable sendPasEnabled When Writing to a PAS¶

If an MGA client has a connected Policy Administration System, sendPasEnabled: true must be set in be_config.json. Without this, bind confirmation will not trigger the PAS write step.

🟠 High

4. External Integration Standards¶

4.1 All External Service Calls Must Go via the Client Microservice¶

Any integration that pulls data into or pushes data out of the Workbench to an external system (sanctions provider, email relay, rater, PAS, third-party API) must be implemented as a pipeline step that calls the client-rest microservice. Direct calls from the Workbench or from other microservices to external endpoints are not permitted.

Workbench → Pipeline → client-rest → [AWS API Gateway] → External Service

🔴 Critical — Bypassing client-rest removes the ability to add auth, retry logic, circuit breaking, and audit logging centrally. It also breaks the security boundary.

4.2 All Traffic to External Services Must Route Through AWS API Gateway¶

All inbound calls must be made via an AWS API Gateway endpoint, not directly to the client microservice's URL. This applies to any third-party REST endpoints

DevOps Responsibility

The AWS API Gateway endpoint URL for each integration is created and managed by DevOps. Raise a request with DevOps for each external service that needs to be connected, providing them with the target service URL and expected auth method. DevOps will supply you with the Gateway URL to reference in your pipeline configuration.

"endpoint": "https://{gateway-id}.execute-api.{region}.amazonaws.com/{stage}/..."

🔴 Critical — Direct external calls bypass the network egress controls, IAM policy enforcement, WAF rules, and audit trails that API Gateway provides. This is a security and compliance requirement.

4.3 OAuth2 Credentials Must Live in DynamoDB, Never in S3¶

Client IDs, client secrets, tenant IDs, and API keys for external services must be stored in DynamoDB environment config. They must never appear in S3 config files or be committed to the Git repository.

// In dynamodb/dev/data.json — use a placeholder, never the real value
"graphApiEmailConfiguration": {
  "clientId": "PLACEHOLDER",
  "clientSecret": "PLACEHOLDER",
  "tenantId": "PLACEHOLDER"
}

Never commit real credentials to Git

Add the credential fields with placeholder values in the dynamodb/{env}/data.json files in the config repository. When raising the Deploy DynamoDB Changes request in the Send Partner Portal, provide the actual credential values via a secure channel (not email, not Slack) — they will be substituted during deployment. Never commit actual credential values to Git, paste them in a Jira ticket, or share them in a PR comment.

🔴 Critical — Credentials in Git are compromised the moment they are committed, regardless of repository visibility.

4.4 Each Integration Must Be Represented as a Named Pipeline Step¶

External calls must be implemented as discrete, named pipeline steps with clear componentType values. Do not bundle multiple external calls into a single pipeline step.

Valid component types for external integrations:

Component Type	Use Case
`RECEIVE_REST`	Receive data from an external system into the platform
`SEND_AND_RECEIVE_VIA_REST`	Send data to external system and wait for a response
`SEND_REST`	Fire-and-forget notification to an external system

🟡 Medium — Bundled pipeline steps are untestable in isolation and make failure diagnosis impossible.

5. Pipeline & Action Standards¶

5.1 Every Line of Business Must Have Actions for All Applicable Lifecycle Stages¶

Every configured business class must have action files covering the full submission lifecycle relevant to that business type. The following are mandatory unless explicitly agreed as out of scope:

Stage	Action Required
New submission	`initialPipeline` defined
Quote / rate	Step in `subStatusPipelines`
Referral (if applicable)	Referral pipeline + `statusMappings` entry
Bind	`completionPipeline` defined
MTA (mid-term adjustment)	Separate action file or MTA-specific pipeline
Renewal	Renewal pipeline or `renewalPipeline` key

🟠 High — Missing lifecycle actions cause users to reach dead ends in the UI with no forward path. MTA and renewal are the most commonly omitted.

5.2 Sanctions Check Must Be the First or Second Pipeline Step¶

For all Open Market and MGA submissions, the sanctions check must be either the first or second step in the initialPipeline. It must always run before any risk data is acted upon by an underwriter.

Recommended STP order:

auto_appetite → sanctions_check → clearance → structured_quote → referral → bind → asset_management

🔴 Critical — Running sanctions after other workflow steps is a compliance failure. Sanctions must gate all further processing.

5.3 User Authority Validation Must Be Applied at Bind¶

All bind-stage pipeline steps must include a validate_user_authority operation or equivalent displayCriteriaExpression that enforces the underwriter's bind authority limits before the completionPipeline executes.

🟠 High — Without authority validation, junior underwriters can bind risks beyond their delegated authority. This is an underwriting governance failure.

5.4 SubStatusPipelines and StatusMappings Must Be Kept in Sync¶

Every entry in subStatusPipelines must have a corresponding entry in statusMappings, and vice versa. Orphaned entries in either block cause the workflow engine to enter an unresolvable state.

🔴 Critical — A status with no mapping causes the submission to become permanently stuck with no UI path forward.

5.5 Referral Pipelines Must Always Have a Resolution Path¶

Any pipeline that moves a submission into a referral state must also define the pipeline steps that handle both the approve and decline outcomes. A referral pipeline with no resolution path leaves submissions permanently in referral state.

🟠 High

5.6 Action Files Must Not Contain Environment-Specific Values¶

Pipeline step endpoints, queue names, and service URLs defined inside action JSON files must use resolvable platform variables, not hardcoded environment strings.

// ✅ Correct — resolved at runtime from DynamoDB
"endpoint": "${clientRestBaseUrl}/referral-check"

// ❌ Wrong — hardcoded to a specific environment
"endpoint": "https://dev.hartford.send.technology/referral-check"

🔴 Critical — Hardcoded URLs will fail silently in every environment except the one they were written for.

6. Rating Integration Standards¶

6.1 O365/SharePoint Rating — Asset Field Mapping Must Match the Business Class¶

The WB_TO_O365 asset mapping file must only contain fields that exist on the configured business class. Mapping fields from an incorrect class (e.g. property fields on a Marine class) will cause the rater to populate incorrect cells, producing wrong premiums silently.

Before go-live, every field in the asset mapping file must be validated against: 1. The business class schema 2. The actual column names in the rater Excel file

🔴 Critical — Incorrect asset mappings produce wrong premiums with no error. This is a silent financial risk.

6.2 O365 Rating Requires Both a Push and Pull Configuration¶

O365 rating operates as a two-step cycle. Both halves must be configured:

WB_TO_RATER — Workbench pushes risk data to the SharePoint Excel file
RATER_TO_WB — Workbench pulls the calculated premium back from the Excel file

Configuring only one direction will result in either no data reaching the rater, or the premium never being returned to the submission.

🔴 Critical

6.3 SharePoint Site IDs Must Be Provided to DevOps Per Environment¶

SharePoint sharepointSiteId and rater file path values differ per environment. These must never be hardcoded in the rating config files in S3 — they belong in dynamodb/{env}/data.json for the relevant environment. Edit the dynamodb/ files directly with the correct values, then raise a Deploy DynamoDB Changes request in the Send Partner Portal and confirm before go-live that each environment points to the correct rater.

🟠 High — A dev site ID in production will push all live risks to a development rater, producing incorrect premiums with no error.

6.4 HyperExponential — Auth Scheme Must Match the Tenant's Setup¶

HyperExponential supports two auth schemes. The scheme configured in hxPricingConfig must match what the HX tenant is configured to accept:

Scheme	When to Use
`AZURE_AD`	HX tenant is backed by Azure Active Directory
`AUTH0`	HX tenant uses Auth0

Using the wrong scheme will result in all pricing requests being rejected with a 401, with no meaningful error returned to the underwriter.

🔴 Critical

6.5 HyperExponential — Pricing Strategy Must Reflect the Underwriting Process¶

Strategy	Use When
`INCEPTION_DATE`	Premium is calculated based on the risk inception date
`FIRST_QUOTE`	Premium is locked to the first quote and does not reprice on renewal

Choose the wrong strategy and HX will apply pricing models from the wrong point in time.

🟠 High

7. Security & Access Standards¶

7.1 Roles Must Be Defined Before Any User Can Access the System¶

Every client configuration must define at least one role in be_config.json. A deployment with no roles defined will result in all authenticated users having no permissions and being unable to see any submissions.

🔴 Critical

7.2 Authority Limits Must Be Defined in the Currency of the Business Class¶

User authority limits must be defined in the same currency as the business class they apply to. Defining limits in USD for a GBP-denominated book will cause limits to be applied with incorrect conversion assumptions.

🟠 High

7.3 Permissions Must Follow Least Privilege¶

Each role should be granted only the permissions required to perform its function. Roles must not be created with blanket "all" permissions unless the role is explicitly an administrator role, and that must be documented.

🟡 Medium

8. Document Generation Standards¶

8.1 Document Generation Must Be Triggered from a Pipeline Step¶

All document generation must be invoked via a pipeline step, not as a side effect of a status change. This ensures documents are generated in a predictable, auditable order and can be individually retried on failure.

🟡 Medium

8.2 Every Business Class That Binds Must Have At Least a Policy Document¶

Any business class that can reach a bound status must have a policy document template configured. Binding without a policy document template will result in a bound risk with no evidence document, which is a compliance issue.

🟠 High

8.3 Document Templates Must Not Hardcode Environment-Specific Data¶

HTML document templates must not contain hardcoded URLs, environment names, email addresses, or other environment-specific values. Use Handlebars variables sourced from the submission data or platform context.

🟡 Medium

9. Naming Conventions¶

9.1 Business Class Type Codes¶

Business class type codes must be 2–3 uppercase letters and must be unique across the client's configuration. They should reflect the Lloyd's class of business where applicable.

✅ Correct	❌ Incorrect
`ME`, `SP`, `GL`, `CF`	`Marine`, `marine_energy`, `Marine-Energy`

9.2 Action File Names¶

Action files must follow the pattern {business-class-code}-{placement-type}-actions.json in lowercase with hyphens.

me-open-market-actions.json
sp-open-market-actions.json
gl-master-actions.json

🟢 Low — Inconsistent naming makes it impossible to identify which file belongs to which class at a glance, especially across large clients.

9.3 Pipeline File Names¶

Pipeline files must be named descriptively after the function they perform, not after the status they produce.

// ✅ Correct
uw_referral.json
sanctions_check.json
bind_and_notify.json

// ❌ Incorrect
pipeline1.json
step3.json
referral_status.json

🟢 Low

10. Configuration Review Checklist¶

Use this checklist before promoting any configuration change to UAT or production.

Structure & Setup¶

[ ] Confirmed with DevOps that customerImplementationDir is set correctly for this client
[ ] All files from the base repository that do not apply to this business type have been removed
[ ] homePartyId set to the client's real DUNS number (not the placeholder value)

Config checklist¶

[ ] No credentials, URLs, or queue names present in any business config file
[ ] Environment-specific values added to dynamodb/{env}/data.json — Deploy DynamoDB Changes request raised in the Partner Portal
[ ] Feature switches live in be_config.json only — not duplicated inside action files

Actions & Pipelines¶

[ ] All lifecycle stages covered (new submission, quote, referral, bind, MTA, renewal)
[ ] Sanctions check is the first or second step in initialPipeline
[ ] validate_user_authority present on all bind operations
[ ] subStatusPipelines and statusMappings entries are in sync
[ ] All referral pipelines have both approve and decline resolution paths
[ ] No hardcoded environment URLs in any pipeline step definition

Rating¶

[ ] Asset field mapping validated against actual business class fields and rater column names
[ ] Both WB_TO_RATER and RATER_TO_WB configured for O365 rating
[ ] SharePoint site IDs set correctly in dynamodb/{env}/data.json per environment — Deploy DynamoDB Changes request raised and confirmed before go-live
[ ] HX auth scheme confirmed against tenant configuration

Security¶

[ ] At least one role defined in be_config.json
[ ] Authority limits defined in the correct currency per business class
[ ] All OAuth2 credentials added as placeholders in dynamodb/{env}/data.json — actual values provided to DevOps via secure channel, not committed to Git

Documents¶

[ ] Every business class that reaches bound status has a policy document template
[ ] Document generation triggered via pipeline steps
[ ] No hardcoded environment data in any HTML template

External Integrations¶

[ ] All external calls routed via client-rest microservice
[ ] AWS API Gateway endpoint URL obtained from DevOps for each integration
[ ] No direct calls to external service public URLs in any config file