Publishing a Service and Managing Mapping Versions

Overview

Publishing a service makes it live on the platform. This action activates a specific, immutable version of its request/response mapping, generates the consumer-facing API contract, and begins serving traffic at the configured endpoint. For services in the Publish direction, the contract is an OpenAPI v3 specification. For services in the Consume direction, the platform provides a WSDL for serve-back.

To prevent deploying a misconfigured or broken service, the platform uses a publish readiness gate. This automated check assesses a service's configuration before it can go live, ensuring that all enabled operations are correctly mapped and that the backend is reachable.

This document explains the publish readiness criteria, the concept of immutable mapping versions, and how the platform handles changes to the source WSDL contract over time.

Publish Readiness

Before a service can be published, it must pass a readiness assessment. This gate prevents accidental publication of services with incomplete or invalid mappings. Readiness is determined by combining diagnostics from individual operation mappings with service-level prerequisites, such as backend connectivity.

flowchart TD
    subgraph "Readiness Inputs"
        direction LR
        A[Per-Operation Mappings]
        B[Backend Test Result]
        C[WSDL Drift Status]
        D[Consume Direction Inputs]
    end

    ReadinessInputs --> Gate{Service-Level Publish Gate}

    Gate --> Ready("Ready to Publish")
    Gate --> WithWarnings("Ready with Warnings")
    Gate --> Blocked("Publish Blocked")

Service-Level Publish Readiness

The readiness of all enabled operations is aggregated into a single service-level status, which determines if the service can be published.

• Auto-ready: All enabled operations are in the AUTO_READY state. The service can be published without any manual intervention.
• Auto-ready with warnings: One or more enabled operations have warnings (AUTO_READY_WITH_WARNINGS). The service can be published after an API publisher acknowledges the warnings.
• Manual-required: At least one enabled operation is in the MANUAL_REQUIRED state, or a non-mapping prerequisite has failed. Publishing is blocked until all issues are resolved.

Per-Operation Mapping Readiness

The platform analyzes the generated mapping for each operation in the source contract and assigns a quality grade. This status indicates whether manual review is needed before publishing.

Other Prerequisites

In addition to mapping readiness, the following service-level checks can block publishing:

• Backend Connectivity: A configured backend must be reachable. A backend test that fails due to authentication or timeout issues will block publishing.
• Consume Grounding Inputs: For services using the Consume direction, all four required grounding inputs must be provided.

Mapping Versions

Mappings are immutable and versioned. Any change to a service's configuration—such as regenerating the mapping, applying a field override, or changing an option—creates a new, distinct revision. You never edit a live mapping in place.

This versioning system provides stability and control over the service's behavior.

• Activate: Activating a version makes its mapping snapshot the live configuration used by the runtime to convert traffic. Only one version can be active at a time.
• Rollback: You can instantly roll back to a known-good configuration by activating any prior version. Because versions are immutable snapshots of the contract, mappings, and options, a rollback precisely restores the previous behavior.

Each version is stamped with metadata, including the mapping-engine version, contract version, contract parser version, and the source contract's checksum. This ensures full traceability between a live mapping and the contract from which it was generated.

Regenerate Mapping

You can regenerate the mapping for the entire service or for a single operation, for instance, after updating the source WSDL. Before a regenerated mapping can be activated, the platform produces a non-breaking check report. This report allows you to verify that the changes will not break existing API consumers before making the new version live.

WSDL Drift & Replacement Drafts

After a service is published, the platform monitors the source WSDL for changes. This "WSDL drift" is detected using the same mechanism as the re-import change detection feature. Each version of a service has a drift status.

When drift is detected for a live service, you can create a replacement draft. This process generates a new mapping version from the updated WSDL while preserving your existing REST paths and runtime policies for any operations that still exist. This allows you to upgrade the underlying contract without repeating the initial onboarding work. After reviewing the draft, you can activate it as the new live version, with the option to roll back at any time.

Troubleshooting

If a service cannot be published, it is typically because it is in the Manual-required state. Check for the following conditions:

• MANUAL_REQUIRED Operations: At least one enabled operation has a mapping issue that the platform cannot resolve automatically. Use the diagnostics UI to identify the operation and the specific fields causing the issue. Resolve the issue by applying field overrides or by disabling the problematic operation.
• Failed Backend Test: The configured backend is unreachable, or authentication is failing. Verify the backend URL, credentials, and network connectivity. A successful backend test is required to publish.
• Missing Consume Inputs: For services in the Consume direction, ensure all four required grounding inputs are configured.

See Also

• Generate & review the OpenAPI
• Consume direction
• Field-level overrides
• How mapping works: Versioned & Immutable
• Versioning Policy

All SOAP-to-REST docs