Rating Service¶

The Send Rating Service integrates Workbench with external rating tools, allowing premium calculations to be performed outside the platform and the results returned into the risk record. Two integrations are supported: Microsoft Office 365 Excel (rating workbooks stored in SharePoint/OneDrive) and HyperExponential (Hx).

Note

The Rating Service is a core platform component but is not enabled for every client. It must be explicitly configured and requires setup by your DevOps team. Check with Send before starting rating configuration.

How rating works¶

Rating follows a round-trip pattern:

Workbench exports risk data fields to a rater (Excel workbook or HyperExponential)
The rater calculates the premium
Workbench imports the results back into the risk record

Both directions are controlled by mapping configuration files stored in the client config repository. The direction of a given mapping is defined by the direction field:

Direction	Meaning
`WB_TO_RATER`	Workbench exports data to the rater
`RATER_TO_WB`	Rater returns results to Workbench

Config file location¶

Rating configuration lives in the client config repository at:

config/{client}/rating/

The platform also ships core mapping defaults at:

config/core/rating/mappings/

Client-level mappings in config/{client}/rating/mappings/ override or extend the core defaults.

Office 365 (Excel) rating¶

How it works¶

The platform uses the Microsoft Graph API to interact with Excel workbooks stored in SharePoint or OneDrive. When a rating action is triggered:

Workbench writes risk field values into named cells or a structured table in the Excel workbook (WB_TO_RATER)
Excel recalculates using the workbook's built-in formulas
Workbench reads back the calculated premium values (RATER_TO_WB)

Rating config file¶

Each business class / placing type combination that uses Excel rating needs a config entry:

{
  "businessClassTypeCode": "PB",
  "placingTypes": ["OPEN_MARKET"],
  "riskTypes": ["NEW", "RENEWAL"],
  "supportedData": ["RISK_DATA"],
  "raterStructure": "TABLE",
  "tableName": "RatingTable",
  "tabName": "Rating",
  "direction": "WB_TO_RATER",
  "description": "PB Open Market rating export",
  "mapperFile": "pb-open-market-rating-export.json"
}

Field	Description
`businessClassTypeCode`	Business class this config applies to
`placingTypes`	Placing types this config applies to
`riskTypes`	Risk types: `NEW`, `RENEWAL`, `MTA`, `BACK_LOADED`, `VERSIONED`
`supportedData`	Data types to include: `RISK_DATA`, `ASSET`, `ASSET_LOCATION`, etc.
`raterStructure`	How data is structured in Excel: `TABLE` or `KEY_VALUE_PAIRS`
`tableName`	Named table in the Excel workbook (for TABLE structure)
`tabName`	Worksheet tab name
`direction`	`WB_TO_RATER` or `RATER_TO_WB`
`mapperFile`	Reference to the field mapping file

Field mapping file¶

The mapper file (mapperFile) defines which Workbench JSON paths map to which Excel column names:

[
  {
    "jsonPath": "$['riskData']['insuredName']",
    "worksheetColumnName": "insured_name"
  },
  {
    "jsonPath": "$['riskData']['inceptionDate']",
    "worksheetColumnName": "inception_date"
  },
  {
    "jsonPath": "$['riskData']['estimatedPremiumIncome']",
    "worksheetColumnName": "epi"
  }
]

The jsonPath references the risk record's data structure. The worksheetColumnName must exactly match the column header in the Excel table.

Supported data types¶

Code	Description
`RISK_DATA`	Core risk record fields
`ASSET`	Asset schedule entries
`ASSET_LOCATION`	Location data for assets
`ASSET_BASIC_CLAIM`	Basic claim data per asset
`ASSET_BORDEREAU`	Bordereau-level asset data
`ASSET_CUSTOM`	Custom asset fields
`ASSET_PERILS_AND_DEDUCTIBLES`	Peril and deductible data per asset
`RELATED_POLICIES_EXPIRED`	Expiring policy data
`RELATED_POLICIES_SKELETON`	Skeleton policy data

Local development¶

The Rating Service (port 4910) requires a rating database schema:

CREATE DATABASE IF NOT EXISTS rating;

Microsoft Graph API calls require valid O365 credentials. In local development you can use a dedicated service account. Credentials are set in pde.dev.json:

{
  "o365": {
    "clientId": "...",
    "clientSecret": "...",
    "tenantId": "...",
    "driveId": "..."
  }
}

HyperExponential (Hx) rating¶

Note

Full Hx documentation — including the complete configuration reference, authentication options, teams configuration, async task strategies, and screen metadata — is covered in the dedicated HyperExponential (Hx) Integration page. The overview below covers how Hx fits into the rating flow.

HyperExponential is a third-party actuarial pricing platform. Unlike the Excel integration — which is a file round-trip — Hx maintains a live policy object in its own system that Workbench creates, updates, and transitions through a defined lifecycle. Workbench acts as the system of record for the risk, while Hx acts as the pricing engine.

How it works¶

Risk Action (Quote) → Rating Service → Hx API (create/update policy)
                                             ↓
                               Underwriter prices in Hx UI
                                             ↓
                      Rating Service ← Hx (complete quote / sync status)
                             ↓
                   Rated premium written back to risk record

The Workbench Rating Service communicates with Hx via its REST API. Every risk that is rated in Hx has a corresponding Hx policy (and optionally multiple policy options for multi-option quoting). The Rating Service manages the full lifecycle of that policy, keeping Hx and Workbench statuses in sync.

Full configuration reference¶

All Hx configuration lives in the hxPricingConfig block of be_config.json (S3 business config). A representative configuration, annotated:

{
  "hxPricingConfig": {
    "connectionTimeoutInSeconds": 15,
    "readTimeoutInSeconds": 15,
    "hxSessionTimeoutInSeconds": 15,

    "authScheme": "AZURE_AD",
    "authenticationURL": "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token",
    "grantType": "client_credentials",
    "clientId": "${HX_CLIENT_ID}",
    "clientSecret": "${HX_CLIENT_SECRET}",
    "scope": "api://{hx-app-id}/.default",

    "apiURL": "https://api.hyperexponential.com",
    "role": "underwriter",

    "policyCreatedAsLive": false,
    "onlyAllowPublishedModels": true,
    "onlyAllowTestableModelVersions": false,
    "sendCustomerId": true,

    "pricingStrategy": "INCEPTION_DATE",
    "forceQuotesOnSameModelToUseSameModelVersion": false,
    "additionalPricingDetailRequired": false,
    "priceSynchronizationEnforced": false,

    "productCoverMatchingStrategy": "PRICING_ENGINE_ID",

    "validationErrorIgnoredOnStatusUpdate": false,
    "setRaterStatusOnUpdate": true,

    "enableMultiOption": false,

    "importExpiringPolicyData": true,
    "shouldIncludeProductCodeOnProductCoverLevel": true,
    "shouldSetExpiringPolicyReferenceOnRenewals": false,
    "shouldReuseExpiringPolicyReferenceOnCopiedPolicies": false,

    "asyncStatusUpdateEnabled": false,
    "useNewHxAsyncTaskTriggering": false,
    "asyncTaskPollerMaxAttempts": 3,
    "asyncTaskPollerBackOffPeriod": 2000,
    "postPolicyCreationAsyncTask": null,
    "updatePoliciesStatusesTaskName": "workbench_sync_status",

    "statusUpdateThreadPoolSize": 20,
    "statusUpdateTimeoutInSeconds": 120,

    "teamsProviderConfig": null
  }
}

Warning

clientId, clientSecret, and any other credentials must be injected via environment variables or AWS Secrets Manager. Never store them in plain text in the config repository or in be_config.json directly.

Authentication¶

Hx supports two authentication schemes, set via authScheme:

Scheme	When to use	Required fields
`AZURE_AD`	Client uses Azure AD for identity (most common)	`authenticationURL`, `clientId`, `clientSecret`, `grantType`, `scope`
`AUTH0`	Client uses Auth0	`authenticationURL`, `clientId`, `clientSecret`, `userName`, `password`, `audience`

Azure AD example:

{
  "authScheme": "AZURE_AD",
  "authenticationURL": "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token",
  "grantType": "client_credentials",
  "clientId": "${HX_CLIENT_ID}",
  "clientSecret": "${HX_CLIENT_SECRET}",
  "scope": "api://{hx-app-id}/.default"
}

Auth0 example:

{
  "authScheme": "AUTH0",
  "authenticationURL": "https://{your-domain}.auth0.com/oauth/token",
  "clientId": "${HX_CLIENT_ID}",
  "clientSecret": "${HX_CLIENT_SECRET}",
  "audience": "https://api.hyperexponential.com",
  "userName": "${HX_USERNAME}",
  "password": "${HX_PASSWORD}"
}

The Rating Service caches and refreshes auth tokens automatically. hxSessionTimeoutInSeconds controls how long an Hx browser session is considered active before Workbench considers it timed out.

Pricing strategy¶

pricingStrategy controls which Hx model version is used when a quote is created:

Value	Behaviour
`INCEPTION_DATE`	The Hx model version in force on the risk's inception date is used. This is the standard choice for most clients — it ensures renewals and MTAs use the model that was live when the risk was first written
`FIRST_QUOTE`	The model version used for the first quote on a risk is locked in and reused for all subsequent quotes on that same risk, regardless of model updates

forceQuotesOnSameModelToUseSameModelVersion enforces that all Hx policy options on the same Workbench risk use the same model version. Enable this when multi-option quoting is active and consistency between options is required.

onlyAllowPublishedModels prevents users from rating against Hx draft models, ensuring only production-ready models are used. Set to true in SIT, UAT, and production; you may set it to false in Dev to test against unpublished model iterations.

Policy lifecycle¶

Every Workbench risk that uses Hx rating follows this lifecycle in Hx:

Create Policy → Open Quote → Complete Quote → Broker Response → Bind (set to Live)

Each transition is triggered by a corresponding Workbench risk action and calls the appropriate Rating Service endpoint:

Lifecycle step	Rating Service endpoint	Typical Workbench action
Create policy	`POST /v1/hx/`	Triggered on first quote action
Update policy	`PUT /v1/hx/`	Triggered when risk data changes
Complete quote	`POST /v1/hx/complete-quote`	"Complete Quote" action
Restart quote	`POST /v1/hx/restart-quote`	"Reopen Quote" action
Complete broker response	`POST /v1/hx/complete-broker-response`	"Broker Response" action
Restart broker response	`POST /v1/hx/restart-broker-response`	"Reopen Broker Response" action
Update risk processing status	`POST /v1/hx/risk-processing-status`	Internal — fires on risk status changes
Clone policy (e.g. renewal)	`POST /v1/hx/clone`	Triggered on renewal creation

Status is tracked at four levels — risk, instance, option, and layer — allowing fine-grained synchronisation between Hx and Workbench.

Product cover matching strategy¶

productCoverMatchingStrategy controls how Workbench maps its product structure to Hx model sections:

Value	How matching works
`PRICING_ENGINE_ID`	Matches on section ID and Hx pricing engine ID only. Simpler and most commonly used
`PRODUCT_HIERARCHY`	Matches on `productCode`, `subType`, and `subType2`. Use this when your Hx model sections map directly to Workbench product hierarchy nodes

Policy creation settings¶

Field	Description
`policyCreatedAsLive`	When `true`, policies are created in Hx as live from the start. Typically `false` — policies only go live at bind
`sendCustomerId`	Sends the Workbench customer ID to Hx when creating a policy. Keep `true` unless advised otherwise by Hx
`role`	The Hx role under which policies are created (e.g. `"underwriter"`)
`additionalPricingDetailRequired`	When `true`, Workbench requires additional customer data to be present before the Hx rating action is available
`priceSynchronizationEnforced`	When `true`, the annual premium (AP) and technical premium (TP) must be in sync in Hx before a quote can be completed in Workbench

Renewals and MTAs¶

Field	Description
`importExpiringPolicyData`	Automatically imports expiring policy data from Hx into the renewal risk when it is created. Defaults to `true`
`shouldIncludeProductCodeOnProductCoverLevel`	Includes the product code in the Hx product cover mapping. Defaults to `true`
`shouldSetExpiringPolicyReferenceOnRenewals`	Sets the expiring Hx policy reference on the renewal policy. Enable if your Hx models use expiring policy references for continuity
`shouldReuseExpiringPolicyReferenceOnCopiedPolicies`	Reuses the expiring policy reference when a risk is copied. Defaults to `false`

Async task configuration¶

Some Hx operations (particularly status updates on large fleets) are performed asynchronously. Workbench polls for completion using a configurable retry strategy:

{
  "asyncStatusUpdateEnabled": false,
  "useNewHxAsyncTaskTriggering": false,
  "asyncTaskPollerMaxAttempts": 3,
  "asyncTaskPollerBackOffPeriod": 2000,
  "postPolicyCreationAsyncTask": null,
  "updatePoliciesStatusesTaskName": "workbench_sync_status",
  "asyncTaskTriggerPoints": {
    "policyCreation": "hx_policy_created",
    "quoteCompletion": "hx_quote_completed",
    "brokerResponseCompletion": "hx_broker_response_completed"
  }
}

Field	Description
`asyncStatusUpdateEnabled`	Enables asynchronous status update flow. When `false`, updates are synchronous
`useNewHxAsyncTaskTriggering`	Switches to the newer async trigger strategy. Set to `true` for new implementations
`asyncTaskPollerMaxAttempts`	How many times to poll before declaring the async task failed
`asyncTaskPollerBackOffPeriod`	Milliseconds to wait between polling attempts
`updatePoliciesStatusesTaskName`	The Hx async task name used to sync policy statuses back to Workbench
`asyncTaskTriggerPoints`	Named async tasks to fire at specific lifecycle moments

Multi-option quoting¶

When enableMultiOption is true, Workbench supports creating multiple Hx policy options on a single risk — allowing the underwriter to present the broker with several pricing scenarios. Options are created via POST /v1/hx/options/bulk and managed independently.

Note

Multi-option quoting requires corresponding configuration in the Hx model itself. Confirm with your Hx account team that the model supports multiple options before enabling this flag.

Status update performance¶

For high-volume environments (e.g. DUA with many certificate risks), status synchronisation from Hx can become a bottleneck. These settings control the thread pool used:

{
  "statusUpdateThreadPoolSize": 20,
  "statusUpdateTimeoutInSeconds": 120
}

Increase statusUpdateThreadPoolSize if you observe slow status propagation under load. statusUpdateTimeoutInSeconds is the maximum time Workbench will wait for a status update response from Hx before treating it as a timeout.

Validation errors and session conflicts¶

Two error conditions are handled by the platform via hx_error_messages.json in config/core/business-constants/:

Error code	Message	Cause
`VALIDATION_ERROR`	"Cannot make HX policy option with id %s final because it has validation errors"	The Hx model has validation errors preventing finalisation. The user must fix them in the Hx UI
`SESSION_ERROR`	"This action cannot be completed as the policy option is still open in hx, please close the hx window and try again"	A user has the Hx policy open in a browser session. Hx prevents concurrent edits

validationErrorIgnoredOnStatusUpdate — when set to true — suppresses the validation error and allows a status update to proceed regardless. This should only be enabled where advised by Send, as it bypasses Hx's own validation gates.

Local development configuration¶

In pde.dev.json the hxPricingConfig block should have null values for all credentials, with policyCreatedAsLive: false and onlyAllowPublishedModels set according to the Hx sandbox environment being targeted:

{
  "hxPricingConfig": {
    "connectionTimeoutInSeconds": 15,
    "readTimeoutInSeconds": 15,
    "hxSessionTimeoutInSeconds": 15,
    "authScheme": null,
    "authenticationURL": null,
    "grantType": null,
    "clientId": null,
    "clientSecret": null,
    "userName": null,
    "password": null,
    "audience": null,
    "scope": null,
    "apiURL": null,
    "role": null,
    "policyCreatedAsLive": false,
    "validationErrorIgnoredOnStatusUpdate": false,
    "pricingStrategy": "INCEPTION_DATE",
    "additionalPricingDetailRequired": false,
    "priceSynchronizationEnforced": false,
    "sendCustomerId": true,
    "postPolicyCreationAsyncTask": null,
    "teamsProviderConfig": null
  }
}

When developing features that interact with Hx, populate apiURL, authScheme, and the relevant auth credentials pointing at an Hx sandbox environment provided by HyperExponential.

Triggering rating from an action¶

Rating is typically triggered by a dedicated risk action (e.g. "Rate Risk"). The action's pipeline calls the Rating Service at the appropriate step. In the action config:

{
  "code": "rate_risk",
  "label": "Rate Risk",
  "initialPipeline": "rating_export_pipeline",
  "completionPipeline": "rating_import_pipeline"
}

The initialPipeline exports risk data to the rater. The completionPipeline runs after the user has reviewed/adjusted the rater and imports the results back.

Rating templates¶

Rating templates (Excel workbook templates) are stored as assets and managed via the template_resource table in the rating database schema. Template management is handled by the Send platform team — contact Send to upload or update a rating workbook.

Rating Service¶

How rating works¶

Config file location¶

Office 365 (Excel) rating¶

How it works¶

Rating config file¶

Field mapping file¶

Supported data types¶

Local development¶

HyperExponential (Hx) rating¶

How it works¶

Full configuration reference¶

Authentication¶

Pricing strategy¶

Policy lifecycle¶

Product cover matching strategy¶

Policy creation settings¶

Renewals and MTAs¶

Async task configuration¶

Multi-option quoting¶

Status update performance¶

Validation errors and session conflicts¶

Local development configuration¶

Triggering rating from an action¶

Rating templates¶

See also¶