API-Driven Form Options

Available from version 2.24.0. Configure a dropdown to load its options from a client microservice endpoint at runtime, rather than from a static business constant. This is useful when the list of choices depends on runtime data — for example, products available for a specific risk, dynamic lookup tables, or values that change based on other form inputs.

When to use API-driven options

Use this approach when:

• The options list depends on runtime data that cannot be expressed as a static business constant
• The options change frequently and managing a business constant deployment for each change would be impractical
• The options are specific to the current risk context (e.g. filtered by the risk's business class or placing type)
• The options come from an external system that Workbench can call at form-load time

Configuration

In the screen meta data element definition, set:

{
  "key": "productCategory",
  "label": "Product Category",
  "type": "select",
  "optionList": "API",
  "optionListParams": {
    "formOptionsSourceUrl": "/underwriting-rest/v1/client/product-form-options"
  }
}

The formOptionsSourceUrl is the path to your client microservice endpoint (relative URL within the Workbench internal network).

Implementing the endpoint

In the client microservice, implement the CustomFormOptionsProvider interface from riskwire-extensions. The endpoint must return a List<FormOption>:

@GetMapping("/v1/client/product-form-options")
public ResponseEntity<List<FormOption>> getProductOptions() {
    List<FormOption> options = productService.getAvailableOptions()
        .stream()
        .map(p -> new FormOption(p.getLabel(), p.getCode()))
        .collect(Collectors.toList());
    return ResponseEntity.ok(options);
}

Each FormOption requires two fields:

Field	Description
label	The display text shown to the user in the dropdown
value	The code stored when the user selects this option

Passing risk context to the endpoint

If the options need to be filtered based on the current risk (e.g. only show products for the risk's business class), you can include the risk ID or other context in the URL:

{
  "optionListParams": {
    "formOptionsSourceUrl": "/underwriting-rest/v1/client/risk/{riskId}/product-options"
  }
}

Workbench will replace the {riskId} placeholder with the current risk's ID at form-load time.

Testing

Once configured, open the action pop-up and verify:

1. The dropdown loads without errors
2. The options displayed match what your endpoint returns
3. Selecting an option saves the correct value (not label)

If the dropdown shows empty or fails to load, check the browser network tab for the endpoint call and any error response from the client microservice.