Mapping Automation and Regeneration

Overview

The Mapping Automation Service provides functionality to diagnose and regenerate the SOAP-to-REST mappings for API operations. When a backend SOAP service's WSDL contract is updated, the corresponding mappings that translate REST-style API consumer requests into SOAP and vice-versa must also be updated. This service automates that process.

Its primary functions are:

1. Diagnosis: To assess the state and "readiness" of an operation's mapping for automated management. It checks for consistency between the operation's schema and its active mapping, flagging issues that may require manual intervention.
2. Regeneration: To create a new, updated mapping for an operation, a service, or all draft services. The regeneration process re-parses the original WSDL, applies automated mapping rules, and preserves existing manual customizations where possible.

This service is typically invoked via an administrative API to manage the lifecycle of SOAP-to-REST mappings, particularly after a new WSDL has been imported for a service. It reads from and writes to the platform's mapping and service definition repositories.

How it works

The service offers two main capabilities: diagnosis and regeneration.

Mapping Diagnosis

The diagnosis functions (diagnoseOperation, diagnoseService) evaluate how well an existing operation mapping aligns with its underlying SOAP contract.

For a given operation, the process is:

1. Fetch the operation's context, including its service details and its stored request and response schemas.
2. Fetch the currently active OperationMappingRecord.
3. Call the internal evaluateReadiness function to compare the two.
4. evaluateReadiness performs a series of checks, generating errors, warnings, or informational notes. Key checks include:
   • An active mapping must exist.
   • The mapping's mappingEngineVersion should be the expected version (contract-mapping-v2).
   • A contractChecksum must exist on both the operation's schema and the mapping, and they must match.
   • The mapping strategies should be contract-json-to-soap for requests and contract-soap-to-json for responses.
   • The presence of manual mapping rules is noted.
5. Based on the outcome, the operation is assigned a readiness status:
   • AUTO_READY: No errors or warnings. The mapping is considered healthy.
   • AUTO_READY_WITH_WARNINGS: No errors, but warnings are present. The mapping is functional but may be outdated or suboptimal.
   • MANUAL_REQUIRED: Errors are present. The mapping is likely broken or incomplete and requires manual intervention.

The diagnoseService function aggregates these results for all operations within a service, providing a summary of the service's overall mapping health.

Mapping Regeneration

The regeneration functions (regenerateOperation, regenerateService, regenerateAllDraftServices) create a new version of an operation's mapping. All regeneration calls flow through a canonical regenerateOneOperation method to ensure consistent behavior.

The regeneration process for a single operation follows these steps:

flowchart TD
    A[Start Regeneration] --> B{Is WSDL source available?};
    B -->|Yes| C[Re-parse WSDL and imported schemas];
    C --> D{Schema quality check};
    D -->|No (Degraded)| E[Use previously stored schema];
    D -->|Yes (OK)| F[Update stored schema];
    B -->|No| E;
    E --> G[Generate new mapping using stored schema];
    F --> H[Generate new mapping using fresh schema];
    G --> I{Preserve manual rules & auto-match fields};
    H --> I;
    I --> J[Save new mapping version];
    J --> K[End];

1. Schema Re-derivation: The service first attempts to re-derive the operation's request and response schemas by re-parsing the original WSDL XML file associated with the service version. This ensures that any fixes or improvements in the WSDL parser are applied to existing operations.
2. Preservation: The new mapping is generated by regenerateActiveWithPreservation, which attempts to carry forward manual customizations (such as rules) from the previous active mapping. It also uses an auto-matching algorithm to map fields that may have been renamed between WSDL versions, comparing the old and new schemas.
3. Persistence: If successful, a new OperationMappingRecord is created and persisted. The process captures any manual customizations that could not be preserved (droppedCustomizations) and any fields that were successfully auto-matched (appliedAutoMatches).
4. Failure Handling: If regeneration fails for any reason (e.g., a database error), an error message is returned. The bulk regeneration methods will log the failure and continue to the next operation.

Schema Re-derivation and Degradation Guard

A critical part of regeneration is the rederiveSchemasFromWsdl step. To ensure correctness, the WSDL parser loads the entire "schema closure" (the main WSDL file and all its imported XSDs) that was captured when the WSDL was first imported.

API Reference

The service exposes public methods for diagnosis and regeneration. These are typically accessed through an administrative API.

diagnoseOperation

Diagnoses the mapping readiness for a single operation.

Returns

A Map<String, Object> containing a detailed readiness report for the operation.

Errors

• IllegalArgumentException: If the operationId is not found.

diagnoseService

Diagnoses the mapping readiness for all operations within a service.

Returns

A Map<String, Object> containing a summary and a detailed report for each operation.

Errors

• IllegalArgumentException: If the serviceId is not found.

regenerateOperation

Regenerates the mapping for a single operation.

Returns

An OperationMappingRecord object representing the newly created mapping.

Errors

• IllegalArgumentException: If the operationId is not found.
• IllegalStateException: If the regeneration process fails. The exception message will contain the reason for failure.

regenerateService

Regenerates mappings for all mutable operations within a single service.

Returns

A Map<String, Object> containing a summary of the regeneration task.

Errors

• IllegalArgumentException: If the serviceId is not found.

regenerateAllDraftServices

Regenerates mappings for all operations across all mutable (draft, non-active) service versions in the system.

Returns

A Map<String, Object> containing a detailed report of the bulk regeneration task.

Example Response for regenerateAllDraftServices

{
  "totalServices": 1,
  "totalOperations": 2,
  "regeneratedCount": 1,
  "immutableCount": 0,
  "failedCount": 1,
  "droppedCustomizations": [
    {
      "operationId": "c2f8c0b5-...",
      "operationKey": "updateInventory",
      "xpath": "*",
      "customizationKind": "schema-rederive",
      "reason": "schema-rederive-degraded: request schema would lose 2 resolved type(s) (unresolved 0 -> 2); re-import the WSDL from its source so its imported schemas resolve"
    }
  ],
  "appliedAutoMatches": [
    {
        "operationId": "a1b2c3d4-...",
        "operationKey": "getInventory",
        "oldXpath": "/Envelope/Body/GetInventory/partId",
        "newXpath": "/Envelope/Body/GetInventory/itemId",
        "similarityScore": 0.95
    }
  ],
  "failedOperations": [
    {
      "operationId": "f9e8d7c6-...",
      "operationKey": "submitOrder",
      "message": "mapping regeneration failed"
    }
  ],
  "perService": [
    {
      "serviceId": "b1a2b3c4-...",
      "serviceKey": "inventory-service",
      "environment": "staging",
      "operationCount": 2,
      "regeneratedCount": 1,
      "immutableCount": 0,
      "failedCount": 1
    }
  ]
}

Troubleshooting

Regeneration Failures

• IllegalStateException: Thrown by regenerateOperation when regeneration fails. The message indicates the cause.
• failedOperations list: In bulk regeneration (regenerateService, regenerateAllDraftServices), individual operation failures do not stop the entire process. Failures are caught, logged with code S2R-ADM-0483, and added to the failedOperations list in the response.

Schema Re-derivation Issues

During regeneration, the service may be unable to re-derive schemas from the source WSDL. This is reported in the droppedCustomizations list with a customizationKind of schema-rederive. Common reasons include:

• no-wsdl-artifact-on-service-version: The service version has no associated WSDL artifact.
• wsdl-xml-not-stored: The WSDL XML was not stored during import (a behavior of older platform versions).
• operation-not-found-in-wsdl: The operation could not be located in the parsed WSDL.
• wsdl-parse-failed: The stored WSDL XML is invalid and could not be parsed.
• schema-rederive-degraded: The degradation guard was triggered. Re-parsing the WSDL would result in a lower-quality schema, so the existing schema was used instead. This may indicate the WSDL should be re-imported.
• persist-failed: The re-derived schema could not be saved to the database. A S2R-ADM-0481 warning is logged.

Diagnosis Warnings and Errors

The diagnoseOperation and diagnoseService functions may report the following issues in their warnings and errors lists:

Errors (result in MANUAL_REQUIRED status):

• active operation mapping is missing: No mapping exists for the operation.
• request/response mapping does not include generated contract: The mapping is missing the machine-readable contract portion.
• mapping contractChecksum does not match current operation schema: The mapping was generated from a different version of the WSDL schema and is now out of sync.

Warnings (result in AUTO_READY_WITH_WARNINGS status):

• request/response contract snapshot is missing on operation schema: The stored schema is missing contract metadata.
• request/response strategy is not contract-json-to-soap/contract-soap-to-json: The mapping uses a legacy or non-standard transformation strategy.
• mappingEngineVersion is not contract-mapping-v2: The mapping was generated by an older engine.
• request/response mapping does not declare mappingEngineVersion: The engine version is missing from the mapping metadata.

See Also

• OperationMappingRepository: The repository service responsible for persistence logic, including regenerateActiveWithPreservation.
• WsdlParser: The component that parses WSDL and XSD documents.
• WsdlSchemaClosureResolver: The component that resolves xsd:import and wsdl:import statements.

All SOAP-to-REST docs