Portal Mapping Lifecycle Management

Purpose

This functional area manages the transformation of imported downstream APIs into stable, curated tool definitions that the Runtime can expose.

Mappings are the business bridge between technical downstream endpoints and AI-facing tools.

Main Capabilities

• create mapping proposals from imported APIs, optionally attaching reference documents to guide immediate enrichment
• edit mapping definitions while they are in an editable status (Draft or Proposed)
• manage mapping versions
• approve mappings
• publish mappings
• deprecate mappings
• revert mappings
• restore historical versions
• cancel a pending mapping version (Draft, Proposed, Under review, or Approved) and revert to the previous published version
• delete mappings
• cancel in-progress semantic enrichment runs
• accept or discard enrichment proposals

Mapping Creation

The Portal can generate an initial mapping proposal from an imported API definition.

Functionally, this gives administrators a starting point rather than forcing them to define every tool-facing concept from scratch.

The proposal process is protocol-aware. It can seed mappings from OpenAPI operations and from SOAP/WSDL operations using the imported contract metadata, request structures, response structures, and SOAP header definitions.

Mapping Maintenance

Administrators can refine mappings over time by updating:

• mapping names and descriptions
• exposed endpoints
• endpoint annotation hints (MCP behavioral signals)
• request and response field rules
• endpoint-level protocol metadata inherited from onboarding
• endpoint behavior for returning the raw downstream response when no response field rules match
• versioned mapping content

Endpoint Annotation Hints

Each endpoint in a mapping can carry up to four MCP behavioral annotation hints:

• Read-only — signals that the endpoint does not mutate state. MCP clients may use this to auto-approve or skip confirmation prompts.
• Destructive — signals that the endpoint may cause irreversible side effects. Clients can use this to trigger extra confirmation steps.
• Idempotent — signals that calling the endpoint multiple times with the same arguments produces the same outcome. Clients can use this to retry safely without risk of duplication.
• Open-world — signals that the endpoint may interact with external systems beyond those described in the tool definition.

Each hint is tri-state: Yes, No, or Not set. When not set, the hint is omitted from the MCP tool descriptor entirely and the client applies its own defaults. Annotation hints are behavioral signals for MCP clients — they do not enforce any access restriction at the Runtime level.

Hints can be set manually in the endpoint editor or inferred by the semantic enrichment pipeline when the Endpoint annotation hints enrichment target is selected.

At field level, mappings define the contract boundary between AI callers and downstream APIs:

• ExposedFieldName is the client-facing field name the Runtime exposes through MCP and direct tool invocation
• SourceFieldName is the downstream field path used when the Runtime builds the outbound request and reads the downstream response

This allows mappings to evolve safely as downstream APIs or business needs change.

When a mapping is regenerated or revised, the editor preserves existing endpoint inclusion choices where possible so administrators do not need to repeatedly re-select the same endpoint exposure decisions.

Editing Rules

A mapping can only be edited in place while its latest version is in Draft or Proposed status:

• Mappings that are Enriching cannot be edited until the background enrichment run finishes or is canceled.
• Deprecated mappings can never be edited — a replacement mapping must be created instead.
• Under review, Approved, and Published mappings cannot be edited directly. To make further changes, revert the mapping to Draft first (Published mappings instead use the Create new version workflow, seeding a fresh draft from the published contract).

This is a strict rule with no automatic fallback: earlier, editing an Approved or Published mapping silently cloned it into a new draft version behind the scenes. That implicit behavior has been removed — the Portal now blocks the edit action outright (with an explanatory tooltip) and expects the administrator to explicitly revert or create a new version first, so it is always clear which version is being changed.

Approval And Publication

The Portal separates draft work from approved and published states.

Functionally, this supports:

• controlled review before release
• distinction between prepared mappings and live mappings
• predictable runtime behavior for AI clients

Published mappings become candidates for runtime exposure. The runtime selects the highest-numbered published version that is not deprecated, so a mapping can have a newer draft version without disrupting active tool consumers.

Enrichment Cancellation

When a mapping is in the Enriching state, the Portal allows operators to cancel the background enrichment job before or during execution.

The cancellation flow:

1. A confirmation dialog appears in the Portal so accidental interruption is prevented.
2. On confirmation, the mapping is reset to its pre-enrichment state.
3. The active enrichment run is marked Canceled.
4. An abort signal is published to the Jobs Worker to stop any in-flight LLM calls.

Canceled runs are recorded in the Enrichment Dashboard and can be reviewed like completed or failed runs.

Enrichment Proposal Acceptance

When semantic enrichment completes, the resulting suggestions are stored as a separate proposal alongside the current draft. The draft is never overwritten automatically.

Administrators can:

• review the proposal inside the mapping editor to see a diff of endpoint names, descriptions, annotation hints, and field-level changes
• selectively accept individual fields, all fields in an endpoint, or the entire proposal
• discard the proposal entirely to keep the current draft unchanged

Partial acceptance is supported. After a partial save, any suggestions that were not accepted remain in the proposal for a subsequent review session.

Enrichment Warnings

An enrichment run can finish successfully while still flagging issues it encountered along the way — for example, an operation chunk that partially failed or a suggestion the LLM could not confidently produce. These warning messages are shown as their own alert in the mapping editor, directly beneath the "Last enrichment" summary, rather than being folded into the change-summary text. This keeps the change summary focused on what changed, while warnings are visible and clearly attributed to the enrichment run that produced them. Warnings are cleared automatically the next time the version is manually edited or re-enriched.

Canceling A Pending Version

Beyond discarding a Draft, administrators can cancel any pending (not-yet-published) version of a mapping — whether it is in Draft, Proposed, Under review, or Approved status — as long as at least one previous (typically published) version exists. This is exposed in the Portal as Cancel version, available both as a row action in the mapping list and inside the Lifecycle action modal's "Go back" panel.

Canceling a pending version:

1. Removes the in-progress version entirely.
2. Reverts the mapping to its previous version and that version's status.
3. Clears the mapping's approved-version reference if the version being canceled was the one currently marked as approved.

This gives administrators a single, consistent way to abandon in-progress work at any stage of review — not just while still in Draft — and fall back cleanly to the last published contract. The action requires confirmation and cannot be undone from the UI.

Versioning

Mappings are version-aware so the platform can maintain historical continuity.

This supports:

• traceability of changes
• rollback or restore behavior
• safer governance for production tool exposure

Creating A Version Targeted At A Specific API Version

When a downstream API has been versioned through the API Onboarding family mechanism, administrators can create a new mapping version that is explicitly seeded from a chosen API revision rather than from scratch.

The New version panel exposes a Target API version selector when the mapping's source API belongs to a family. Administrators select which API revision to base the new version on. The default selection is the current version of the family.

The platform then:

1. Reads the operations from the selected API revision.
2. Seeds the new mapping version's endpoints from those operations.
3. Preserves the existing endpoint GUIDs for any operations whose path, method, and operationId match what was already in the mapping — this carries forward toolset selections and schema discovery overrides without manual re-configuration.
4. Assigns new GUIDs to operations that are new or changed (new path, method, or operationId), effectively orphaning them from prior toolset selections so administrators must consciously include them.

The target API version is recorded on the mapping version as metadata. It does not affect how the Runtime executes the tool — the Runtime reads only the baked endpoint data.

Guards On New Version Creation

The platform blocks creation of a new API-version-targeted mapping version when:

• the mapping already has an editable version in Draft, Proposed, or UnderReview state — administrators must discard or advance the existing editable version first
• the mapping is in Deprecated status — deprecated mappings cannot receive new versions

These guards prevent accidental version accumulation and keep the workflow predictable.

Deprecation And Cleanup

The Portal also supports retirement and cleanup activities through:

• deprecation
• canceling a pending version (see "Canceling A Pending Version" above)
• mapping deletion

This helps keep the platform catalog clean and operationally manageable.

Operational Importance

This is one of the most important functional areas in the whole platform because it turns imported API structure into governed AI tool behavior.