Boolean Handling Overrides for API Operations

Overview

The BooleanHandlingApplyService provides a mechanism for API publishers to define how boolean values are represented for a specific API operation. This is necessary when a backend SOAP service expects booleans in a format different from the platform's default, such as representing true/false as 1/0.

This service allows for two levels of configuration:

1. Operation-level override: A single setting that applies to all boolean fields within an operation.
2. Per-field override: Granular settings that apply to individual fields, overriding the operation-level or system-level default.

The service is called with an operation's unique identifier (operationId) and a set of desired overrides. It validates the inputs, merges them with existing settings, and persists them to the active configuration for that operation. The result is an updated mapping that the API gateway uses at runtime to transform boolean values in requests and responses.

This service modifies the configuration of an operation only when its parent service version is in a draft state and not active.

How It Works

The service applies boolean handling overrides by updating the s2r_operation_mapping table for a given operationId. The core logic resides in the apply method, which orchestrates validation, merging, and persistence.

Overrides Hierarchy

Configuration is applied at two levels, creating a clear hierarchy:

1. Operation-Level Override: A single string value stored in the boolean_handling_override column. It can be set to as-bool or as-int. If this value is null, the operation inherits the system-wide default handling.
2. Per-Field Overrides: A more specific override for an individual field, identified by its soapXPath. These are stored in two jsonb map columns: request_field_boolean_handling and response_field_boolean_handling. An override for a specific soapXPath in these maps takes precedence over the operation-level override. If a field's soapXPath is not present in the map, it falls back to the operation-level setting.

Data Flow and Persistence

The process of applying overrides follows a distinct sequence of steps to ensure data integrity and provide clear feedback.

flowchart TD
    subgraph "BooleanHandlingApplyService.apply()"
        A[Start: apply call with overrides] --> B{Load Operation Metadata};
        B --> C{Is Service Version Mutable?};
        C -- No --> D[Throw S2R-ADM-0410];
        C -- Yes --> E[Validate Operation & Field Overrides];
        E -- Invalid --> F[Throw S2R-VAL-04xx];
        E -- Valid --> G[Read existing per-field maps from DB];
        G --> H[Merge new field overrides into maps];
        H --> I{was operation override provided?};
        I -- Yes --> J[UPDATE operation_override AND field_maps];
        I -- No --> K[UPDATE field_maps ONLY];
        J --> L{Rows updated?};
        K --> L;
        L -- No --> M[Throw S2R-ADM-0404];
        L -- Yes --> N[Construct and return ApplyResult];
    end
    subgraph "Result"
        N --> Z[Success];
        D --> X[Failure];
        F --> X;
        M --> X;
    end

1. Load and Validate Operation: The service first retrieves metadata for the specified operationId to confirm that its service version is mutable (status is draft and is_active is false). If not, it throws an ApplyValidationException with code S2R-ADM-0410.
2. Validate Inputs: It validates the operationOverride value and all fieldEntries. Invalid modes, directions, or malformed soapXPath values will trigger an ApplyValidationException with a specific error code.
3. Read and Merge: The service reads the existing jsonb maps for request and response field overrides from the database. It then merges the new fieldEntries into these maps.
   • Providing a mode of as-bool or as-int for a soapXPath adds or updates an entry.
   • Providing a mode of null for a soapXPath removes that entry from the map, causing the field to inherit the operation-level or system default.
4. Persist Changes: The service writes the updated configuration to the database.
   • If the hasOperationOverrideKey parameter is true, the boolean_handling_override column is updated along with the per-field maps. An explicit null for operationOverride will clear the operation-level setting.
   • If hasOperationOverrideKey is false, only the per-field maps are updated, leaving the operation-level override untouched.
5. Return Result: On success, the service returns an ApplyResult object containing the final, authoritative state of the boolean handling configuration for the operation.

Attribution and Data Shape

When a per-field override is written, it is stored in the database as a JSON object that includes attribution metadata. This allows for auditing changes over time.

• Storage Shape: {"mode": "<mode>", "_source": "<actor>", "_at": "<timestamp>"}
• API Shape: "<mode>"

The service automatically handles this wrapping and unwrapping. The readFieldMap method and the ApplyResult object returned by apply provide a simple Map<String, String> view, exposing only the mode for backward compatibility with API consumers. The service can read both the legacy plain-string format and the new object format, ensuring a seamless transition.

Applying Overrides: A Conceptual Example

While this service is internal, it is typically exposed via an administrative API endpoint. The following demonstrates how to structure a call to the apply method to configure an operation.

To set an operation-level override to as-int and configure two specific fields:

1. A request field at //input/isComplete should be as-bool.
2. A response field at //output/isValid should have its override cleared.

The input fieldEntries list would be structured as follows:

// The unique ID of the target operation
UUID targetOperationId = UUID.fromString("...");

// The list of per-field overrides
List<FieldEntry> entries = List.of(
    // Override a request field to be treated as a boolean
    new FieldEntry(
        "//input/isComplete",
        "request",
        "as-bool"
    ),
    // Clear any existing override for a response field
    new FieldEntry(
        "//output/isValid",
        "response",
        null // A null mode clears the override for this XPath
    )
);

// Conceptually calling the service
ApplyResult result = booleanHandlingApplyService.apply(
    targetOperationId,
    "as-int", // Set operation-level override
    true,     // Indicate that the operation-level override was explicitly provided
    entries
);

Expected Result

The apply method returns an ApplyResult object. Based on the example inputs, it would contain:

• operationId: The targetOperationId.
• operationOverride: "as-int".
• requestFieldOverrides: A map containing {"//input/isComplete": "as-bool"}.
• responseFieldOverrides: An empty map, as the override for //output/isValid was removed.

API Reference

The BooleanHandlingApplyService exposes the following public methods.

apply

Applies operation-level and/or per-field boolean handling overrides. This method is transactional.

There are two overloads for this method:

1. apply(UUID operationId, String operationOverride, boolean hasOperationOverrideKey, List<FieldEntry> fieldEntries): A backward-compatible version that automatically stamps new overrides with the current system time.
2. apply(UUID operationId, String operationOverride, boolean hasOperationOverrideKey, List<FieldEntry> fieldEntries, String actorSource, Clock clock): The primary method which includes parameters for change attribution (actorSource) and precise timestamping (clock).

Parameters

Returns

An ApplyResult object representing the complete, updated boolean handling configuration for the operation.

Throws

ApplyValidationException if any input is invalid or if the operation is not in a mutable state.

readFieldMap

readFieldMap(UUID operationId, String column)

Reads the per-field override map for a given operation and direction (request or response). This method is backward-compatible and correctly reads both legacy and current data formats, returning a simple Map<String, String>.

Parameters

Returns

A Map<String, String> where keys are soapXPath expressions and values are the override modes (as-bool or as-int). Returns an empty map if no overrides are configured.

readOperationOverride

readOperationOverride(UUID operationId)

Reads the operation-level override for a given operation.

Parameters

Returns

A String containing the override mode (as-bool or as-int) or null if no operation-level override is set.

Data Structures

FieldEntry

Represents a single per-field override.

ApplyResult

Represents the successful result of an apply call, containing the full configuration state.

Troubleshooting

Calls to the apply method may fail with an ApplyValidationException. The exception contains a code that identifies the specific error. These codes are typically mapped to S2R-VAL-04xx HTTP status responses by the controller.

All SOAP-to-REST docs