New Client Setup Guide¶

This guide walks a developer through setting up a new client implementation from scratch, using the base repository as the starting point.

It is split into two parts:

Generic Configuration — steps every implementation must complete, regardless of business type
Business Type Configuration — pick the section that applies to your implementation: Open Market, MGA, or DUA

Each business type section is written as a standalone — it assumes you are setting up only that business type. Follow the deletion lists to strip out everything from the base repository that does not apply.

Prerequisites¶

Before you begin, collect the following from your delivery lead:

Your client code — a short lowercase identifier (e.g. acme). Referred to throughout as {CLIENT}
Your client's DUNS number — the 9-digit D&B identifier. Referred to as {DUNS}
The business class(es) you are configuring and their agreed 2–3 letter type codes (e.g. PD for Property Direct)
Which business type is in scope: Open Market, MGA, or DUA

Part A — Generic Configuration¶

These steps apply to every new implementation. Complete all of them before moving to the business type section.

A1 — Clone and rename the repository¶

Request for DevOps to create a new Bitbucket repository for your new client. Once this is available follow the steps below.

A2 — Configure the trading party¶

The trading party file defines your client as the insurer on the platform. The homePartyId in be_config.json must exactly match the partyId in this file.

Rename the file:

mv config/{CLIENT}/trading-parties/demo-insurer.json \
   config/{CLIENT}/trading-parties/{CLIENT}-insurer.json

Edit config/{CLIENT}/trading-parties/{CLIENT}-insurer.json:

{
  "status": "ACTIVE",
  "activationDate": "2025-01-01",
  "partyName": "{Client Full Legal Name}",
  "partyId": "urn:duns:{DUNS}",
  "partyRole": "Insurer",
  "tradingPartyDetail": {
    "amsEndpointUrl": "https://riskwire:8443/testharness-soap-api/AcordMsGSvc_v1_43_Endpoint?wsdl",
    "contact": {
      "personName": "{Contact Name}",
      "telephone": "{Telephone}",
      "email": "{contact@client.com}"
    },
    "address": {
      "numberAndStreet": "{Address Line 1}",
      "cityName": "{City}",
      "postalCode": "{Postcode}",
      "country": "GB"
    }
  }
}

A3 — Update be_config.json¶

be_config.json controls platform behaviour and integration settings. It lives at config/{CLIENT}/applicationconfig/be_config.json.

The minimum fields to review on a new implementation are:

Field	What to set	Notes
`homePartyId`	`urn:duns:{DUNS}`	Must exactly match `partyId` in your trading party file
`baseCountry`	`GBR` (or client domicile)	ISO 3166-1 alpha-3
`assignableRoles`	Roles applicable to the client	Base repository default: `SC_FC`, `SC_FC_OPS`, `SF_OPS`, `DUA_TEAM`, `FINANCE_TEAM`, `CLAIMS_TEAM`
`featureSwitches`	Set `DUA` and `PAS` as needed	See business type sections below

Danger

If homePartyId does not exactly match partyId in the trading party file — including the urn:duns: prefix — the platform will fail to start. This is the most common cause of startup failures on a new implementation.

A4 — Update the DynamoDB environment config¶

config/{CLIENT}/dynamodb/dev/data.json is the environment config for Dev. It contains the customerImplementationDir, SQS queue names, S3 bucket names, and database endpoints that are unique to your client and environment.

A4.1 — Set customerImplementationDir

This tells every service which config folder to load. It must match the directory name from A1 exactly:

"customerImplementationDir": { "S": "{CLIENT}" }

A4.2 — Set envId

"envId": { "S": "{CLIENT}.dev" }

A4.3 — Update queue names

Replace all occurrences of senduk_dev_ with {CLIENT}_dev_, and senduk-dev with {CLIENT}-dev. Key queues:

"sqsIn":  { "S": "agateway_inbound_{CLIENT}-dev" },
"sqsOut": { "S": "agateway_outbound_{CLIENT}-dev" },
"scheduleMappingInQueue":           { "S": "{CLIENT}_dev_SCHUEDULE_COL_MAPPING_IN" },
"scheduleMappingProcessingInQueue": { "S": "{CLIENT}_dev_SCHEDULE_MAPPING_IN" }

A4.4 — Update S3 bucket names

"docBucket":       { "S": "agateway.{CLIENT}-dev.documents" },
"messageBucket":   { "S": "agateway.{CLIENT}-dev.messages" },
"payloadBucket":   { "S": "{CLIENT}-dev.payload" },
"resourcesBucket": { "S": "agateway.{CLIENT}-dev.resources" }

A4.5 — Update external gateway URL

"externalGatewayBaseUrl": { "S": "https://{CLIENT}-dev.globalriskwire.com" }

A4.6 — Update database endpoints

Your DevOps team will provide the RDS endpoint addresses for the dev environment:

"gatewayDatasourceUrl":     { "S": "jdbc:mysql://{RDS_ENDPOINT}/agateway?useSSL=false" },
"underwritingDatasourceUrl":{ "S": "jdbc:mysql://{RDS_ENDPOINT}/underwriting?useSSL=false" },
"workflowDatasourceUrl":    { "S": "jdbc:mysql://{RDS_ENDPOINT}/flowable?useSSL=false" }

Note

The S3 buckets and SQS queues must be provisioned in AWS by DevOps before deployment. The names in the config must exactly match the AWS resources.

A5 — Update pde.dev.json (local environment)¶

pde.dev.json in the repository root is the local override used when running via Docker Compose. It overrides the DynamoDB config for PDE development.

Minimum fields to update:

{
  "customerImplementationDir": "{CLIENT}",
  "homePartyId": "urn:duns:{DUNS}",
  "baseCountry": "GBR",
  "environment": "development",
  "createTradingOnStartup": true,
  "loadMinimalDataOnStartup": true
}

A6 — Remove unused business classes and their assets¶

The base repository ships with business classes for many lines of business. Delete every business class that is not part of your implementation, along with all associated config.

For each business class you are removing (identified by its type code, e.g. av for Aviation):

# Business class definition
rm config/{CLIENT}/business-class/{bc}.json

# Workflow actions
rm -rf config/{CLIENT}/actions/{bc}/

# Screen meta data
rm -rf config/{CLIENT}/screen-meta-data/config/{bc}/
rm -rf config/{CLIENT}/screen-meta-data/files/{bc}/

# Document templates
rm -rf config/{CLIENT}/document-template/config/{bc}/
rm -rf config/{CLIENT}/document-template/files/{bc}/

# Document clauses
rm -rf config/{CLIENT}/document-clause/config/{bc}/
rm -rf config/{CLIENT}/document-clause/files/{bc}/

Repeat for every unused business class. The full list that ships in the base repository is: ah, av, cf, cgo, crd, cyb, gl, me, mf, pb, pd, pt, sp, spr, tax.

A7 — Validate JSON and start locally¶

Validate all JSON files before starting Docker:

find config/{CLIENT} -name "*.json" | while read f; do
  python3 -m json.tool "$f" > /dev/null 2>&1 || echo "INVALID: $f"
done

Fix any files reported as invalid before proceeding.

Start the Docker stack:

docker-compose up -d
docker-compose logs -f riskwire-underwriting

Once the stack is running, Workbench reloads its configuration periodically — there is no manual base-data reload step required during normal operation. The Underwriting service runs on port 4858 locally per docker-compose.yml; confirm with your delivery lead if a forced reload is ever needed.

Common startup failures:

Symptom	Cause	Fix
Startup fails with `homePartyId` error	Value in `be_config.json` / `pde.dev.json` doesn't match trading party `partyId`	Ensure both values are identical including the `urn:duns:` prefix
`customerImplementationDir` not found	Config folder name doesn't match the value in `pde.dev.json`	Check the folder is named `{CLIENT}` exactly
Config reload returns 500	JSON parse error in a config file	Check the Underwriting service logs for the file path
Business class not appearing in UI	`businessClassTypeCode` in action files doesn't match `typeCode` in the business class file	Make sure the codes match exactly

A8 — Push to Dev¶

git add .
git commit -m "Initial {CLIENT} configuration"
git push origin dev

Once your changes are pushed, raise a Client Build & Deploy request in the Send Partner Portal (https://send-partner-portal.refined.site), specifying the branch to deploy.

If you have also edited dynamodb/dev/data.json, raise a Deploy DynamoDB Changes request as well. DynamoDB changes require a service restart — this is handled as part of that portal request.

Workbench picks up business config changes under config/ on its next periodic refresh after deployment.

Part B — Open Market¶

Use this section if your implementation is Open Market only. Open Market risks are placed directly in the market by the underwriter — there is no master facility, no coverholder, and no bordereau ingestion.

B1 — Files to delete¶

The following files from the base repository are not needed for an Open Market implementation. Delete them after completing Part A.

Application config — forms not needed for Open Market:

rm config/{CLIENT}/applicationconfig/master_submission_config.json
rm config/{CLIENT}/applicationconfig/dec_submission_config.json
rm config/{CLIENT}/applicationconfig/coverholder_submission_config.json

Actions — delete non-open-market action files:

# Master and MTA-master actions (no facility/master risks)
rm config/{CLIENT}/actions/pb/pb-master-actions.json
rm config/{CLIENT}/actions/pb/pb-master-mta-actions.json
rm config/{CLIENT}/actions/tax/tax-master-actions.json

# Bordereau actions (no bordereau ingestion)
rm config/{CLIENT}/actions/pb/pb-bordereaux-actions.json

# Individual dec actions (no declarations)
rm config/{CLIENT}/actions/gl/gl-individual-dec-actions.json
rm config/{CLIENT}/actions/me/me-individual-dec-actions.json

# Non-bulking lineslip actions (not applicable)
rm config/{CLIENT}/actions/gl/gl-non-bulking-lineslip-actions.json
rm config/{CLIENT}/actions/me/me-non-bulking-lineslip-action.json

# Fac RI actions (not applicable to Open Market only)
rm config/{CLIENT}/actions/cf/cf-fac-ri-actions.json
rm config/{CLIENT}/actions/gl/gl-fac-ri-actions.json
rm config/{CLIENT}/actions/pd/pd-fac-ri-actions.json

Pipelines — delete DUA, bordereau, PAS, and individual dec pipelines:

# DUA pipelines
rm -rf config/{CLIENT}/pipelines/dua/

# Individual dec pipelines
rm -rf config/{CLIENT}/pipelines/individual-dec/

# PAS pipelines (policy admin — not needed without MGA/DEC)
rm -rf config/{CLIENT}/pipelines/pas/

# Bordereau pipelines
rm config/{CLIENT}/pipelines/create_bordereau.json
rm config/{CLIENT}/pipelines/generate_bordereau_task.json
rm config/{CLIENT}/pipelines/bordereau_validation_rules.json
rm config/{CLIENT}/pipelines/generate_ils_task.json
rm config/{CLIENT}/pipelines/generate_tpa_task.json
rm config/{CLIENT}/pipelines/validate_facility_based_quote.json

DUA config — not needed for Open Market:

rm -rf config/{CLIENT}/dua/

B2 — Business class configuration¶

Create config/{CLIENT}/business-class/{BC}.json. Use OPEN_MARKET as the only placing type and set duaEnabled to false:

{
  "typeCode": "{BC}",
  "name": "{Business Class Full Name}",
  "duaEnabled": false,
  "enabledPlacingTypes": [
    {
      "placingType": "OPEN_MARKET"
    }
  ],
  "products": [
    { "productCode": "{PRODUCT_CODE}" }
  ],
  "retentions": [
    { "retentionCode": "DEDUCTIBLE" },
    { "retentionCode": "EXCESS" }
  ],
  "limitOfIndemnities": [
    { "loiCode": "LOI_LIABILITY" }
  ],
  "classConstantLists": []
}

products, retentions, and limitOfIndemnities reference codes that must exist in config/{CLIENT}/business-constants/product.json, retention.json, and limit_of_indemnity.json.

B3 — Workflow actions¶

Create config/{CLIENT}/actions/{bc}/{bc}-open-market-actions.json. Use pb-open-market-actions.json from the base repository as a reference. The minimum actions for a functional Open Market workflow are risk_details, submit_to_underwriter, quote, and bind.

Open Market also supports MTA (mid-term adjustment). If MTA is in scope, create {bc}-open-market-mta-actions.json — reference pd-open-market-mta-actions.json for a worked example.

B4 — Submission form¶

config/{CLIENT}/applicationconfig/open_market_submission_config.json defines the fields captured when an underwriter creates a new risk. Copy the base repository version as your starting point and remove fields that are not relevant to your business class.

B5 — be_config.json settings for Open Market¶

Ensure the following in config/{CLIENT}/applicationconfig/be_config.json:

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

DUA must be false. PAS can remain true — it has no effect without MGA/DEC placing types configured.

Part C — MGA (Managing General Agent)¶

Use this section if your implementation is MGA only. An MGA implementation introduces a Master risk (the facility or binder) and Declaration risks (the individual certificates bound under the master). The coverholder submits business electronically via bordereau.

C1 — Files to delete¶

Application config — coverholder form not needed for MGA:

rm config/{CLIENT}/applicationconfig/coverholder_submission_config.json

Actions — delete DUA lineslip and fac RI action files:

# Fac RI (not applicable to MGA)
rm config/{CLIENT}/actions/cf/cf-fac-ri-actions.json
rm config/{CLIENT}/actions/gl/gl-fac-ri-actions.json
rm config/{CLIENT}/actions/pd/pd-fac-ri-actions.json

# Individual dec (MGA uses INBOUND_BORDEREAU, not manual dec entry)
rm config/{CLIENT}/actions/gl/gl-individual-dec-actions.json
rm config/{CLIENT}/actions/me/me-individual-dec-actions.json

# Non-bulking lineslip (not applicable)
rm config/{CLIENT}/actions/gl/gl-non-bulking-lineslip-actions.json
rm config/{CLIENT}/actions/me/me-non-bulking-lineslip-action.json

Pipelines — delete DUA and individual dec pipelines:

rm -rf config/{CLIENT}/pipelines/dua/
rm -rf config/{CLIENT}/pipelines/individual-dec/
rm config/{CLIENT}/pipelines/generate_ils_task.json

DUA config directory — not needed for MGA:

rm -rf config/{CLIENT}/dua/

C2 — Business class configuration¶

Create config/{CLIENT}/business-class/{BC}.json. An MGA business class enables three placing types — Open Market, Master (Binding Authority), and Dec (Inbound Bordereau) — and must have sendPasEnabled: true:

{
  "typeCode": "{BC}",
  "name": "{Business Class Full Name}",
  "duaEnabled": false,
  "sendPasEnabled": true,
  "enabledPlacingTypes": [
    {
      "placingType": "OPEN_MARKET"
    },
    {
      "placingType": "MASTER",
      "enabledPlacingSubTypes": [
        { "placingSubType": "BINDING_AUTHORITY" }
      ]
    },
    {
      "placingType": "DEC",
      "enabledPlacingSubTypes": [
        { "placingSubType": "INBOUND_BORDEREAU" }
      ]
    }
  ],
  "products": [
    { "productCode": "{PRODUCT_CODE}" }
  ],
  "retentions": [
    { "retentionCode": "DEDUCTIBLE" }
  ],
  "limitOfIndemnities": [
    { "loiCode": "LOI_LIABILITY" }
  ],
  "classConstantLists": []
}

sendPasEnabled: true enables the PAS (Policy Administration System) integration required for the declaration lifecycle.

C3 — Workflow actions¶

MGA requires two action files:

Open Market actions — config/{CLIENT}/actions/{bc}/{bc}-open-market-actions.json Standard open market workflow (quote → bind). Reference pb-open-market-actions.json.

Master actions — config/{CLIENT}/actions/{bc}/{bc}-master-actions.json Covers the facility setup workflow. Reference pb-master-actions.json as a starting point. Master MTA is configured separately in {bc}-master-mta-actions.json if in scope.

Declaration processing for INBOUND_BORDEREAU is handled by the platform's bordereau ingestion pipeline automatically — you do not write a separate actions file for it.

C4 — Submission forms¶

Master submission form — config/{CLIENT}/applicationconfig/master_submission_config.json

Defines the fields captured when creating a master facility. Copy the base repository version and trim to your business class fields.

Dec submission form — config/{CLIENT}/applicationconfig/dec_submission_config.json

Defines the fields shown on each declaration record created from a bordereau. Copy the base repository version and align the fields with your bordereau column mapping.

Open Market submission form — config/{CLIENT}/applicationconfig/open_market_submission_config.json

Standard open market new risk form. Copy and trim as for Open Market in Part B.

C5 — Bordereau template¶

Place your bordereau template in config/{CLIENT}/bordereau-templates/. The Lloyd's standard template already ships with the base repository at config/senduk/bordereau-templates/LLOYDS_2020_10.xlsx.

If using a custom template, place it alongside the Lloyd's template and reference it in the bordereau validation rules.

C6 — be_config.json settings for MGA¶

{
  "featureSwitches": "{\"DUA\": false, \"PAS\": true}",
  "policyConfig": {
    "preProcessSkeletonPolicies": true,
    "copyForMta": ["BOUND", "SKELETON"],
    "copyForRenewal": ["BOUND", "SKELETON"]
  }
}

DUA must be false. PAS must be true to enable the declaration policy lifecycle.

Part D — DUA (Delegated Underwriting Authority)¶

Use this section if your implementation is DUA only. DUA is the most configuration-intensive business type. It introduces coverholder management, bordereau validation, contracts, and the full declaration lifecycle. Plan it as a separate workstream from core platform delivery.

D1 — Files to delete¶

DUA does not use standalone Open Market placing types. If this is a pure DUA implementation with no standalone open market risks:

Application config — open market form not needed:

rm config/{CLIENT}/applicationconfig/open_market_submission_config.json

Actions — delete open market action files:

rm config/{CLIENT}/actions/ah/ah-open-market-actions.json
rm config/{CLIENT}/actions/av/av-open-market-actions.json
rm config/{CLIENT}/actions/cf/cf-open-market-actions.json
rm config/{CLIENT}/actions/cgo/cgo-open-market-actions.json
rm config/{CLIENT}/actions/cgo/cgo-open-market-mta-actions.json
rm config/{CLIENT}/actions/crd/crd-open-market-actions.json
rm config/{CLIENT}/actions/cyb/cyb-open-market-actions.json
rm config/{CLIENT}/actions/gl/gl-open-market-actions.json
rm config/{CLIENT}/actions/me/me-open-market-actions.json
rm config/{CLIENT}/actions/mf/mf-open-market-actions.json
rm config/{CLIENT}/actions/pb/pb-open-market-actions.json
rm config/{CLIENT}/actions/pb/pb-open-market-mta-actions.json
rm config/{CLIENT}/actions/pd/pd-open-market-actions.json
rm config/{CLIENT}/actions/pd/pd-open-market-mta-actions.json
rm config/{CLIENT}/actions/pt/pt-open-market-actions.json
rm config/{CLIENT}/actions/sp/sp-open-market-actions.json
rm config/{CLIENT}/actions/spr/spr-open-market-actions.json
rm config/{CLIENT}/actions/tax/tax-open-market-actions.json

# Non-bulking lineslip and individual dec (not applicable)
rm config/{CLIENT}/actions/gl/gl-non-bulking-lineslip-actions.json
rm config/{CLIENT}/actions/me/me-non-bulking-lineslip-action.json
rm config/{CLIENT}/actions/gl/gl-individual-dec-actions.json
rm config/{CLIENT}/actions/me/me-individual-dec-actions.json

# Fac RI (not applicable)
rm config/{CLIENT}/actions/cf/cf-fac-ri-actions.json
rm config/{CLIENT}/actions/gl/gl-fac-ri-actions.json
rm config/{CLIENT}/actions/pd/pd-fac-ri-actions.json

Pipelines — delete individual dec and STP pipelines:

rm -rf config/{CLIENT}/pipelines/individual-dec/
rm -rf config/{CLIENT}/pipelines/stp/

D2 — Enable the DUA feature switch¶

In config/{CLIENT}/applicationconfig/be_config.json, set DUA to true:

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

D3 — Add duaConfig to be_config.json¶

The duaConfig block sets the default bordereau reporting configuration that applies to all master facilities unless overridden at the risk level:

"duaConfig": {
  "duaImplementationDir": "dua",
  "masterBordereauReportingConfiguration": {
    "defaultValues": {
      "bordereauType": "RISK",
      "frequencyCode": "MONTHLY",
      "expectedBordereaux": 12,
      "maxReportingReturnTermDays": 14,
      "dateFormatType": "DAY_MONTH_YEAR"
    }
  }
}

The duaImplementationDir value must match the dua/ subdirectory name inside your client config folder (config/{CLIENT}/dua/).

D4 — Configure the business class for DUA¶

Set duaEnabled: true on any business class used for DUA. The BORDEREAU_MAPPING_SUFFICIENT_COVERAGES configuration specifies the minimum coverage codes that must be present in a bordereau row for it to be treated as a valid declaration:

{
  "typeCode": "{BC}",
  "name": "{Business Class Full Name}",
  "duaEnabled": true,
  "sendPasEnabled": true,
  "configurations": {
    "BORDEREAU_MAPPING_SUFFICIENT_COVERAGES": {
      "value": [
        "COV_DUA_COVH_DEC_REF",
        "COV_DUA_REINSURED_NAME"
      ]
    }
  },
  "enabledPlacingTypes": [
    {
      "placingType": "MASTER",
      "enabledPlacingSubTypes": [
        { "placingSubType": "BINDING_AUTHORITY" }
      ]
    },
    {
      "placingType": "DEC",
      "enabledPlacingSubTypes": [
        { "placingSubType": "INBOUND_BORDEREAU" }
      ]
    }
  ],
  "products": [],
  "limitOfIndemnities": [],
  "retentions": []
}

D5 — Configure the coverholder business class¶

DUA requires a DUA-CH business class to support the coverholder record type. This is a fixed platform identifier — do not change the typeCode. It lives in the DUA subdirectory, not the main business-class folder:

config/{CLIENT}/dua/business-class/coverholder.json:

{
  "typeCode": "DUA-CH",
  "name": "Coverholder",
  "duaEnabled": true,
  "facilitySetupVisible": false,
  "enabledPlacingTypes": [
    { "placingType": "COVERHOLDER" }
  ],
  "products": [],
  "limitOfIndemnities": [],
  "classConstantLists": [],
  "coverages": []
}

This file already ships with the base repository at config/senduk/dua/business-class/coverholder.json — no changes needed beyond ensuring it is present in your renamed directory.

D6 — DUA workflow actions¶

DUA uses a separate action directory structure from the main business class actions. There are two sets:

Default DUA actions (config/{CLIENT}/dua/actions/default/) — apply to all master risks unless overridden: - default-master-actions.json — the master facility workflow (setup, review, approval) - default-bordereau-dec-actions.json — the declaration workflow triggered by bordereau ingestion

Coverholder actions (config/{CLIENT}/dua/actions/dua-ch/) — apply to the coverholder risk type: - dua-ch-coverholder-actions.json — the coverholder onboarding and management workflow

These files ship with the base repository in their complete form. Review them with your delivery lead to confirm the workflow steps match the client's process, but they are usable as-is for a first deployment.

D7 — DUA screen meta data¶

The coverholder and master risk screens are configured in config/{CLIENT}/dua/screen-meta-data/. This follows the same config/files split as the main screen meta data:

config/default/ and files/default/ — fields shown on master risk actions (audit preparation, audit recommendation, audit scheduling, master risk assessment)
config/dua-ch/ and files/dua-ch/ — fields shown on coverholder actions (claims team check, coverholder risk assessment, credit control check, DUA team checklist)

These files ship with the base repository and are usable as-is. Customise the field definitions in the files/ directory to match the client's data capture requirements.

D8 — DUA UW rationale¶

UW rationale questions for master risks and coverholder reviews are configured in config/{CLIENT}/dua/uw-rationale/: - config/default.json and files/default-master-questionnaire.json — master risk rationale - config/dua-ch.json and files/dua-ch-questionnaire.json — coverholder rationale

These ship with the base repository. Review the questionnaire fields with the UW team and customise as required.

D9 — Bordereau template¶

Place your bordereau template in config/{CLIENT}/bordereau-templates/. The Lloyd's standard template ships with the base repository at config/senduk/bordereau-templates/LLOYDS_2020_10.xlsx.

The DUA bordereau validation rules pipeline (config/{CLIENT}/pipelines/bordereau_validation_rules.json) references the column definitions from this template. If you are using a custom template, update the validation rules to match your column layout.

Next steps¶

Config Repository Structure — understand the full directory layout
Multi-Environment Config Promotion — promoting from Dev through SIT and UAT to Production
Partner Portal Reference — all portal request types and when to use them
Business Class Setup — detailed reference for all business class fields
Delegated Underwriting Overview — full DUA configuration reference