Configure Duration Formatting Overrides for API Operations

Overview

The Duration Handling Apply Service provides a mechanism for API publishers to configure the formatting of xsd:duration data types in SOAP responses on a per-operation basis. This allows for fine-grained control, overriding the system-wide default formatting to meet the specific requirements of different API consumers.

This service is an administrative function. It is called to apply configuration for a specific API operation. The configuration consists of two parts:

1. An operation-level override mode.
2. A map of field-specific overrides, where each field is identified by its soapXPath in the response message.

The applied configuration is persisted to the s2r_operation_mapping database table. During request processing, the runtime reads this configuration and applies it to format xsd:duration values in the SOAP response. The runtime resolves the formatting mode by following a precedence chain: a per-field override is used if present; otherwise, the per-operation override is used; if neither is set, the system default is applied.

Configuration can only be applied to operations belonging to a service version that is in a draft status and not yet active.

How it Works

The service processes requests to update duration handling configuration through a single apply method. The process involves validation, merging new and existing settings, and persisting the result to the database.

The logical flow for applying configuration is as follows:

flowchart TD
    subgraph "Duration Handling Apply Service"
        A[Start] --> B{Receive Apply Request};
        B --> C{Load Operation Metadata};
        C --> D{Is Service Version Mutable?};
        D -- No --> E[Fail: S2R-ADM-0410 Mapping Immutable];
        D -- Yes --> F{Normalize Operation Override Mode};
        F --> G[Validate Operation Override Mode];
        G -- Invalid --> H[Fail: S2R-VAL-0498 Invalid Mode];
        G -- Valid --> I{Read Existing Field Overrides from DB};
        I --> J[Merge with New Field Overrides];
        J --> K{Validate Merged Field Overrides};
        K -- Invalid --> L[Fail: S2R-VAL-0498 Invalid Field/Mode];
        K -- Valid --> M[Serialize Merged Map to JSON];
        M --> N{Update Operation Mapping in DB};
        N -- 0 Rows Updated --> O[Fail: S2R-ADM-0404 No Active Mapping];
        N -- 1 Row Updated --> P[Construct ApplyResult];
        P --> Q[Return Success];
    end
    
    subgraph "Inputs"
        direction LR
        In1[operationId]
        In2[operationOverride]
        In3[fieldOverrides]
    end

    subgraph "Outputs"
        direction LR
        Out1[ApplyResult]
        Out2[ValidationException]
    end

    Inputs --> B;
    E --> Out2;
    H --> Out2;
    L --> Out2;
    O --> Out2;
    Q --> Out1;

1. Validate Mutability: The service first loads metadata for the specified operationId. It verifies that the operation's parent service version is not active and has a status of draft. If the operation is part of an active or non-draft version, it is considered immutable, and the request is rejected.

2. Normalize and Validate Modes: The top-level operationOverride mode is normalized (trimmed and converted to lowercase). It is then validated against a predefined set of allowed modes.

3. Merge Field Overrides: The service reads the existing map of field-specific overrides from the database. It then iterates through the fieldOverrides provided in the request, merging them with the existing map:

   • Add/Update: A FieldEntry with a soapXPath and a valid mode will add a new override or update an existing one for that path.
   • Remove: A FieldEntry with a soapXPath and a null or blank mode will remove the override for that path.
   • Validation: Each soapXPath must be non-blank, and each mode must be valid.

4. Persist Changes: The normalized operationOverride and the final, merged map of field overrides (serialized as a JSONB string) are written to the s2r_operation_mapping table. The update targets the active mapping record for the given operationId.

5. Return Result: If the database update is successful, the service returns an ApplyResult object containing the final applied configuration, including the operation key and the merged map of field overrides.

API Reference

The component exposes its functionality through the DurationHandlingApplyService class.

apply Method

Applies duration handling overrides for a specific operation. This method is transactional.

apply(UUID operationId, String operationOverride, List<FieldEntry> fieldOverrides)

Parameters

Return Value

On success, returns an ApplyResult object.

FieldEntry Type

The FieldEntry record defines a single field-specific override.

Troubleshooting

When a call to the apply method fails, it throws an ApplyValidationException containing an error code and a descriptive message.

All SOAP-to-REST docs