Skip to content

BMEL β€” BizMetry Expression LanguageΒΆ

BMEL (BizMetry Expression Language) is a typed expression language used inside the Business Event mapper to define computed or multi-source field mappings. It allows you to write expressions that combine, transform, or conditionally select values from one or more API payload fields and assign the result to a target Frame component.

BMEL expressions are authored in the Monaco-based BMEL Editor, which provides syntax highlighting, inline validation, type inference, and source field auto-completion.

🧩 When to Use BMEL¢

Use BMEL when a simple 1-to-1 field mapping is not sufficient:

Scenario Example
Concatenate two source fields CONCAT({op:Response}.$.firstName, " ", {op:Response}.$.lastName)
Arithmetic on a numeric field {op:Response}.$.totalCents / 100.0
Conditional value selection IF({op:Response}.$.status == "SUCCESS", 1, 0)
Extract a nested array element {op:Response}.$.items[0].price
Type conversion TO_STRING({op:Request}.$.orderId)
Default value fallback COALESCE({op:Response}.$.region, "UNKNOWN")

πŸ“ Source Field SyntaxΒΆ

All source field references in BMEL use the canonical format:

{operationName:Section Label}.$.fieldPath

Examples:

{getOrder:Response Payload}.$.total_amount
{placeOrder:Request Payload}.$.customer.address.city
{getProduct:URI Parameters}.$.productId
{createAccount:Request Headers}.$.X-Tenant-Id

The BMEL editor shows only the fields you connected in the mapper β€” not the full schema. Unconnected fields are not available as expression inputs.

πŸ”€ Type SystemΒΆ

BMEL is statically typed with type inference. The editor validates types at authoring time and reports errors inline.

BMEL Type Description Example values
STRING Text values "hello", "USD"
INTEGER Whole numbers 42, -7
FLOAT Decimal numbers 3.14, 99.99
BOOLEAN True/false true, false
ARRAY Ordered list of items [1, 2, 3]
OBJECT Nested key-value structure { "key": "value" }
NULL Absence of value null

Type mismatches produce warnings (not hard errors) in most cases β€” BizMetry attempts best-effort coercion at runtime, but explicit conversion functions are recommended.

βš™οΈ OperatorsΒΆ

ArithmeticΒΆ

Operator Description Example
+ Addition / string concatenation a + b
- Subtraction a - b
* Multiplication a * b
/ Division a / b
% Modulo a % b

ComparisonΒΆ

Operator Description
== Equal to
!= Not equal to
< Less than
<= Less than or equal
> Greater than
>= Greater than or equal

LogicalΒΆ

Operator Description
&& Logical AND
\|\| Logical OR
! Logical NOT

Operator Precedence (high to low)ΒΆ

!  (unary NOT)
*  /  %
+  -
<  <=  >  >=
==  !=
&&
||

Use parentheses to override precedence explicitly.

πŸ“š Built-in FunctionsΒΆ

String FunctionsΒΆ

Function Signature Description
CONCAT CONCAT(s1, s2, ...) β†’ STRING Concatenates two or more strings.
UPPER UPPER(s) β†’ STRING Converts to uppercase.
LOWER LOWER(s) β†’ STRING Converts to lowercase.
TRIM TRIM(s) β†’ STRING Removes leading/trailing whitespace.
SUBSTRING SUBSTRING(s, start, end) β†’ STRING Extracts a substring by character index.
LENGTH LENGTH(s) β†’ INTEGER Returns the length of a string.
CONTAINS CONTAINS(s, sub) β†’ BOOLEAN True if s contains sub.
STARTS_WITH STARTS_WITH(s, prefix) β†’ BOOLEAN True if s starts with prefix.
ENDS_WITH ENDS_WITH(s, suffix) β†’ BOOLEAN True if s ends with suffix.
REPLACE REPLACE(s, from, to) β†’ STRING Replaces all occurrences of from with to.

Numeric FunctionsΒΆ

Function Signature Description
ABS ABS(n) β†’ FLOAT Absolute value.
ROUND ROUND(n, decimals) β†’ FLOAT Rounds to specified decimal places.
FLOOR FLOOR(n) β†’ INTEGER Rounds down to nearest integer.
CEIL CEIL(n) β†’ INTEGER Rounds up to nearest integer.
MIN MIN(a, b) β†’ FLOAT Returns the smaller of two values.
MAX MAX(a, b) β†’ FLOAT Returns the larger of two values.

Type ConversionΒΆ

Function Signature Description
TO_STRING TO_STRING(v) β†’ STRING Converts any value to its string representation.
TO_INTEGER TO_INTEGER(s) β†’ INTEGER Parses a string as an integer.
TO_FLOAT TO_FLOAT(s) β†’ FLOAT Parses a string as a float.
TO_BOOLEAN TO_BOOLEAN(s) β†’ BOOLEAN Parses "true" / "false" strings.

Control FlowΒΆ

Function Signature Description
IF IF(condition, then, else) β†’ any Conditional expression. Returns then if condition is true, else otherwise.
COALESCE COALESCE(v1, v2, ...) β†’ any Returns the first non-null value.
NULL_IF NULL_IF(v, match) β†’ any Returns null if v equals match, otherwise returns v.

Array FunctionsΒΆ

Function Signature Description
COUNT COUNT(arr) β†’ INTEGER Returns the number of elements in an array.
SUM SUM(arr) β†’ FLOAT Sums all numeric elements.
AVG AVG(arr) β†’ FLOAT Averages all numeric elements.
FIRST FIRST(arr) β†’ any Returns the first element of an array.
LAST LAST(arr) β†’ any Returns the last element.

SpecialΒΆ

Function Signature Description
SELF SELF(ref) β†’ any Returns the value of a source field as-is. Used internally by IntelliSense for direct assignments.

✏️ BMEL Editor¢

The BMEL Editor opens as a dialog when you click the Ζ’ icon on a connector line in the mapping canvas.

Screenshot pending

Capture required: BMEL Editor dialog open, showing Monaco editor on the left with an expression, source fields panel on the right listing available fields with their canonical references.

Editor panelsΒΆ

  • Left β€” Expression editor: Monaco-based editor with BMEL syntax highlighting, bracket matching, and error markers.
  • Right β€” Available source fields: Lists only the fields connected in the mapper for this target component, shown with their canonical {op:Section}.$.path references. Click any field to insert it at the cursor position.

Inline validationΒΆ

The editor validates your expression as you type:

  • Red underline β€” syntax error or unknown function.
  • Yellow underline β€” type mismatch warning.
  • Green checkmark β€” expression is valid and ready to save.

Saving a malformed expression is blocked until all errors are resolved.

πŸ’‘ Expression ExamplesΒΆ

// Direct field reference
{getOrder:Response Payload}.$.order_id

// Arithmetic
{getOrder:Response Payload}.$.subtotal + {getOrder:Response Payload}.$.tax

// String concatenation
CONCAT({getOrder:Response Payload}.$.firstName, " ", {getOrder:Response Payload}.$.lastName)

// Conditional
IF({placeOrder:Response Payload}.$.status == "SUCCESS", 1, 0)

// Null coalescing
COALESCE({getOrder:Response Payload}.$.region, "GLOBAL")

// Array element count
COUNT({getOrder:Response Payload}.$.lineItems)

// Nested path
{getOrder:Response Payload}.$.payment.card.last4

// Type conversion
TO_FLOAT({getOrder:Response Payload}.$.totalCents) / 100.0