Per-Operation Date/Time Handling Overrides

Overview

The Date/Time Handling Apply Service provides a mechanism for API publishers to set per-operation overrides for date, time, and timestamp handling. These settings allow fine-grained control over how date/time values are formatted for a specific API operation, overriding any system-wide defaults.

This service is part of the administrative API and is used to modify the configuration of an existing API operation. It directly updates the s2r_operation_mapping table with the specified overrides. The platform's runtime component then uses these per-operation settings as part of a resolution chain to determine the final date/time handling behavior. The resolution order is: per-field override, then per-operation override (this component), and finally the system default.

You can use this service to configure:

• The standard format for date/time values.
• A custom format pattern.
• The time zone for interpretation.
• The representation of null date/time values.

Changes can only be applied to operations belonging to a service version that is in a mutable state (e.g., a 'draft' version).

How It Works

The service applies date/time handling overrides to a specific operation in a transactional, multi-step process. The core logic distinguishes between callers that supply the nullModeOverride field and those that omit it, ensuring backward compatibility.

flowchart TD
    subgraph "Input Validation"
        A[Start: apply() called] --> B{Validate all inputs};
        B --> C{format='custom'?};
        C -- Yes --> D{customPattern provided?};
        D -- No --> Z1[Fail: S2R-VAL-0491];
        C -- No --> E;
        D -- Yes --> E;
        E{timezone='local'?};
        E -- Yes --> F{localTimezone provided?};
        F -- No --> Z2[Fail: S2R-VAL-0492];
        F -- Yes --> G;
        E -- No --> G;
    end

    subgraph "Operation & Persistence"
        G[Load Operation Metadata] --> H{Service version mutable?};
        H -- No --> Z3[Fail: S2R-ADM-0410];
        H -- Yes --> I{nullModeOverride supplied?};
        I -- Yes --> J[UPDATE all 5 override columns in DB];
        I -- No --> K[UPDATE 4 override columns, PRESERVE null_mode in DB];
        J --> L{Update successful?};
        K --> L;
        L -- No --> Z4[Fail: S2R-ADM-0404];
    end

    subgraph "Result Construction"
        L -- Yes --> M{nullModeOverride supplied?};
        M -- Yes --> N[Use supplied nullMode for result];
        M -- No --> O[Read preserved nullMode from DB];
        N --> P[Construct ApplyResult];
        O --> P;
        P --> Q[End: Return ApplyResult];
    end

    Z1 --> Q;
    Z2 --> Q;
    Z3 --> Q;
    Z4 --> Q;

The process is as follows:

1. Input Validation: The service first validates the format and value of all provided override parameters, regardless of whether the target operation exists. This ensures that malformed requests fail early with a specific error code.
   • formatOverride, timezoneOverride, and nullModeOverride are checked against their respective sets of allowed values.
   • customPatternOverride is validated as a syntactically correct date/time pattern.
   • localTimezoneOverride is validated as a valid IANA time zone identifier.
2. Cross-Parameter Validation: The service checks for logical dependencies between parameters.
   • If formatOverride is set to 'custom', then customPatternOverride must be provided.
   • If timezoneOverride is set to 'local', then localTimezoneOverride must be provided.
3. Mutability Check: It loads the metadata for the target operationId and verifies that its parent service version is in a mutable state (e.g., status is draft and it is not active). If the version is locked, the request is rejected.
4. Database Update: The service executes a SQL UPDATE against the s2r_operation_mapping table for the specified operationId. The behavior depends on whether the nullModeOverride was included in the request:
   • nullModeOverride Supplied: All five date/time override columns are updated. Providing an explicit null for nullModeOverride will clear the setting in the database, causing the operation to inherit the system default.
   • nullModeOverride Omitted: Only the four other override columns (datetime_format_override, datetime_custom_pattern_override, datetime_timezone_override, datetime_local_timezone_override) are updated. The existing datetime_null_mode_override value is intentionally preserved. This ensures backward compatibility for older clients.
5. Result Construction: An ApplyResult object is returned. If nullModeOverride was omitted from the request, the service performs an additional database read to fetch the preserved value and include it in the response, ensuring the returned object accurately reflects the final persisted state.

Applying Overrides

To apply overrides, invoke the service with the target operationId and the desired override values. A null value for any override parameter indicates that the operation should inherit the setting from a higher-level scope (e.g., the system default).

Example Invocation

This example shows a conceptual invocation of the service to configure an operation to use a custom date format and a specific time zone.

Parameters:

• operationId: a1b2c3d4-e5f6-7890-1234-567890abcdef
• formatOverride: "custom"
• customPatternOverride: "yyyy-MM-dd'T'HH:mm:ss.SSSX"
• timezoneOverride: "utc"
• localTimezoneOverride: null
• nullModeOverride: "omit"
• nullModeSupplied: true

Execution: The service validates the inputs, confirms the operation is mutable, and updates the corresponding record in the s2r_operation_mapping table.

Expected Result: The service returns an ApplyResult object confirming the new settings.

{
  "operationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "operationKey": "find-widgets-by-id",
  "formatOverride": "custom",
  "customPatternOverride": "yyyy-MM-dd'T'HH:mm:ss.SSSX",
  "timezoneOverride": "utc",
  "localTimezoneOverride": null,
  "nullModeOverride": "omit"
}

API Reference

The service exposes several public methods for applying overrides. The primary method takes seven arguments, providing full control over presence-aware updates. Convenience overloads are provided for backward compatibility and simpler use cases.

Methods

apply(operationId, formatOverride, customPatternOverride, timezoneOverride, localTimezoneOverride, nullModeOverride, nullModeSupplied)

This is the primary, presence-aware method. It allows distinguishing between an omitted nullModeOverride field and an explicit null value.

apply(operationId, formatOverride, customPatternOverride, timezoneOverride, localTimezoneOverride, nullModeOverride)

A 6-argument convenience method that assumes nullModeOverride was supplied. An explicit null for nullModeOverride will clear the persisted setting.

apply(operationId, formatOverride, customPatternOverride, timezoneOverride, localTimezoneOverride)

A 5-argument backward-compatible method. It behaves as if nullModeOverride was omitted from the request, meaning any existing datetime_null_mode_override setting for the operation is preserved.

Parameters

Return Value

All apply methods return an ApplyResult object upon success.

Troubleshooting

If an apply call fails, the service throws an ApplyValidationException containing a machine-readable error code and a descriptive message.

All SOAP-to-REST docs