Skip to content

Step 6 — Configure Mapping

The mapping step is where you connect source fields from your selected API operations to the frame components defined in the target Frame Type.

This step presents a visual connector interface divided into two panels: source fields on the left, target components on the right. You draw connectors between them, and optionally write BMEL expressions for derived or computed fields.

🖥️ Interface Layout

┌─────────────────────────────┬─────────────────────────────┐
│   SOURCE FIELDS             │   TARGET FRAME COMPONENTS   │
│                             │                             │
│  ▼ GET /orders/{id}         │  ▼ Order Resource           │
│    ▸ Request                │    ○ order_id               │
│      • id (path param)      │    ○ total_amount           │
│    ▸ Response Payload       │    ○ currency               │
│      • order_id             │    ○ status                 │
│      • total                │  ▼ Customer Resource        │
│      • currency             │    ○ customer_id            │
│      • status               │    ○ customer_name          │
│      • customer.id    ──────┼──► customer_id              │
│      • customer.name        │                             │
│                             │                             │
└─────────────────────────────┴─────────────────────────────┘
  • Left panel — shows all fields available from the configured operations, organized by operation and section (Request Payload, Response Payload, URI Params, Query Params, Headers).
  • Right panel — shows all components of the target Frame Type, grouped by resource.
  • SVG connectors — lines drawn between left and right panels represent mappings.

Screenshot pending

Capture required: Full mapping step UI showing both panels with several connectors drawn between source fields and target components.

🔗 Creating a Mapping

Direct Mapping (Drag & Drop)

  1. Click and drag from a source field on the left panel.
  2. Drop onto a target component on the right panel.
  3. A connector line appears linking the two.

Screenshot pending

Capture required: A connector being drawn from a source field to a target component mid-drag.

Direct Mapping (Click-to-Connect)

Alternatively:

  1. Click the source field — it highlights.
  2. Click the target component — the mapping is created.

🔢 Connector Types

Each connector carries a type badge indicating what kind of mapping it represents:

Badge Type Description
1:1 Direct One source field maps directly to one target component.
ƒ Expression A BMEL expression computes the target value from one or more source fields.
[ ] Array The source is an array — each element maps to a row in a nested table component.

🧮 Expression Mapping (BMEL Editor)

When a target component requires a computed or transformed value, click the ƒ icon on any existing connector (or on an unconnected target component) to open the BMEL Editor.

The BMEL Editor provides:

  • A Monaco-based code editor with syntax highlighting for BMEL expressions.
  • A source fields panel showing all available source fields you can reference.
  • Real-time validation — errors and warnings are shown inline as you type.
  • Auto-complete for function names and field references.

Screenshot pending

Capture required: BMEL Editor dialog open, showing the Monaco editor with an expression written (e.g., concat($op0_RESPONSE_FIELD_$.firstName, " ", $op0_RESPONSE_FIELD_$.lastName)), source fields panel on the left, and validation status.

See: BMEL Expression Language for the full language reference.

📋 Source Field Reference Format

Source fields in mappings are referenced using the canonical format:

{operationName:Section Label}.$.fieldPath

Examples:

Format Meaning
{getOrder:Response Payload}.$.order_id The order_id field from the response of the getOrder operation.
{createOrder:Request Payload}.$.customer.id Nested field customer.id from the request body of createOrder.
{getOrder:URI Parameters}.$.id The id path parameter of the getOrder endpoint.
{getOrder:Request Headers}.$.Authorization The Authorization header from the getOrder request.

This format is used both in the visual connector labels and inside BMEL expressions.

🤖 IntelliSense Auto-Mapping

Instead of mapping fields manually, you can click "Run IntelliSense" to let BizMetry automatically suggest and apply mappings based on semantic similarity between source field names and target component names.

IntelliSense uses the bizmetry-llm service (sentence-transformers) to compute semantic similarity scores and propose the best mapping for each unmapped target component.

See: IntelliSense Auto-Mapping

🗑️ Removing a Mapping

  • Hover over a connector line — a remove (×) button appears.
  • Click it to delete the mapping.

Or right-click a connector for the context menu.

Screenshot pending

Capture required: Connector with the remove button visible on hover.

✅ Completing the Step

Once all required frame components have at least one mapping, the "Create Business Event" button becomes active.

Components without mappings are not mandatory — only components marked as required by the Frame Type definition must be mapped before publishing.

Unmapped required components

If required components are unmapped, you can still create the event in DRAFT status, but the event cannot be published until all required mappings are in place.