Configure Mapping¶

The mapping step is the visual canvas where you define how fields extracted from API operations are assigned to components in the target Telemetry Frame. This is where the Business Event gets its observability power — translating raw API payload data into structured, business-meaningful telemetry.

🗺️ Canvas Layout¶

The mapping canvas is split into three panels:

┌─────────────────────────┬──────────────────┬────────────────────────────┐
│   SOURCE FIELDS         │   CANVAS         │   TARGET FRAME COMPONENTS  │
│                         │                  │                            │
│  ▾ getOrder (GET)       │  ●─────────────▶ │  ▾ Order (Resource)        │
│    REQUEST              │                  │    order_id                │
│      path: order_id     │  ●─────────────▶ │    total_amount            │
│    RESPONSE             │                  │    currency                │
│      body: total        │                  │    status                  │
│      body: currency     │  [ƒ]───────────▶ │    processing_latency      │
│      body: status       │                  │                            │
│                         │                  │  ▾ AI Model (Resource)     │
│  ▾ placeOrder (POST)    │                  │    model_name              │
│    REQUEST              │                  │    tokens_used             │
│      ...                │                  │    cost_usd                │
└─────────────────────────┴──────────────────┴────────────────────────────┘

• Left panel — Source Fields: Organized by operation, then by section (REQUEST / RESPONSE) and further by payload path.
• Center — Connector canvas: The visual area where mapping lines are drawn.
• Right panel — Target Frame Components: The resources and their attributes defined in the selected Frame Type.

🔗 Simple Field Mapping (Drag & Drop)¶

To create a direct 1-to-1 mapping between a source field and a frame component:

1. Hover over a source field in the left panel — a connection dot (●) appears.
2. Click and drag from the dot to the target component in the right panel.
3. Release to create the connector line.

The connector appears as a colored line across the canvas. The source field value will be directly assigned to the target component attribute at capture time.

Removing a mapping¶

Click the connector line to select it, then press Delete or click the trash icon that appears on the selected connector.

ƒ BMEL Expression Mapping¶

For cases where a target component requires a computed value — combining multiple source fields, applying transformations, or implementing conditional logic — click the ƒ icon on an existing connector (or right-click a target component and select "Edit Expression").

This opens the BMEL Expression Editor. See BMEL Expression Language for full reference.

A connector that uses a BMEL expression is visually distinguished from simple connectors by the ƒ badge on the line.

⚡ IntelliSense Auto-Mapping¶

The IntelliSense button in the mapper toolbar triggers BizMetry's AI-assisted auto-mapping engine.

IntelliSense analyzes the semantic similarity between source field names and target component names — using sentence-transformers to cluster and suggest the most likely mappings — and populates the canvas automatically.

See IntelliSense Auto-Mapping for how it works and how to review suggestions.

📋 Source Field Reference¶

Each source field is identified by a canonical reference in the format:

{operationName:Section Label}.$.fieldPath

For example:

This format is used when writing BMEL expressions to reference specific fields.

Section labels by field location¶

⚠️ Mapping Validation¶

BizMetry validates mappings before allowing you to save:

• Type compatibility — a numeric source field mapped to a string component will generate a warning (not a blocker, as BMEL can handle coercion).
• Unmapped required components — if a Frame component is marked as required but has no mapping, a validation error blocks saving.
• Invalid BMEL expressions — the BMEL editor runs inline validation; malformed expressions block saving.
• Duplicate targets — a single target component cannot receive more than one simple mapping (use a BMEL expression to combine multiple sources instead).

💾 Saving¶

Once all required components are mapped and validations pass, click "Save" to store the Business Event as a DRAFT.

The event is saved with: - The selected operations - All connector mappings (simple and BMEL) - The target Frame Type reference - Version 1.0 in DRAFT state

To activate telemetry capture, you must Publish the DRAFT. See Managing Versions.

🔗 Related Sections¶

• BMEL Expression Language
• IntelliSense Auto-Mapping
• Managing Versions
• Lifecycle & States