Field Expression Operation

The feature allows manipulation of data before both sending to the upstream PSP API and storing in the database. The setting can be configured on a connector via the Manipulation: Field Operation Expression Language setting on a connector.

Configuration

The connector setting consists of:

• Fail handling : A general configuration to specify the behaviour for unexpected error scenarios.
• Rule Configuration : One or more manipulation rules.

Example configuration

Fail Handling

In addition, there is 1 general setting which applies to all rules and defines the action in case one of the manipulation rules returns an unexpected error during the evaluation:

Fail the transaction

The request will fail and the transaction will be set to error.

Skip single failed expression

The failed expression will be skipped and the error will be logged. The rest of the expression manipulations will continue to execute as usual.

Skip all expressions

All expression manipulations will be skipped and an error will be logged.

Rule Configuration

Each rule has 4 properties which define the behaviour of the rule and the manipulation.

1. Target Field
2. Action
3. If empty result
4. Expression

1. Target Field

Which field will be used to insert the resulting string:

• merchantTransactionId
• additionalId1
• additionalId2
• merchantMetaData
• description
• extraData
  • extraData.foo
  • extraData.bar
• customer.identification
• customer.firstName
• customer.lastName
• customer.billingAddress1
• customer.billingAddress2
• customer.billingCity
• customer.billingPostcode
• customer.billingState
• customer.billingCountry
• customer.billingPhone
• customer.shippingFirstName
• customer.shippingLastName
• customer.shippingCompany
• customer.shippingAddress1
• customer.shippingAddress2
• customer.shippingCity
• customer.shippingPostcode
• customer.shippingState
• customer.shippingCountry
• customer.shippingPhone
• customer.company
• customer.email
• customer.nationalId

2. Action

Which action should be done for the manipulated field:

3. Action if result is empty

What to do if the resulting value is empty:

• Use original value
• Use empty value

4. Expression

The expression describes the manipulation to be done.

Following functions are available - using any expression other than in this list will fail the validation:

Fallback Operators

Two operators are available to define a fallback value when a field is absent or empty:

?? — Null coalesce : fallback only when the value is null. An empty string "" is used as-is and does not trigger the fallback.

transaction.description ?? transaction.merchantTransactionId

?: — Elvis operator : fallback when the value is falsy (null, "", 0, false).

transaction.description ?: transaction.merchantTransactionId

Concatenating Values

Use ~ to concatenate multiple values:

transaction.description ~ transaction.merchantTransactionId

Custom strings can also be concatenated:

"something" ~ transaction.description

Combining Expressions

You may combine multiple expressions.

Example truncateAfterNChars(implode(',', array_column(transaction.items, 'name')) ?: transaction.description, 100)

The example does following:

• Collect all item names and concatenate them with a ,
• If no items exist, use the description instead
• Truncate the value to 100 characters

Available fields for Expression

• Any field referenced inside an expression must be prefixed with transaction., for example

  • transaction.description
  • transaction.merchantTransactionId

• Any field that can be used as Target Field can be used for Expressions

  • For the extraData field, use the bracket notation to access the data
    • transaction.extraData["foo"]
    • transaction.extraData["foo-bar"]

• In addition to target fields, following fields are also available for Expressions

  • transaction.amount
  • transaction.currency
  • transaction.uuid
  • transaction.items
  • Customer data must also be prefixed with transaction.customer, for example
    • transaction.customer.firstName
    • transaction.customer.lastName
    • etc.

Excluded fields for Register transactions

The following fields are not compatible with Register transactions and will be ignored when used in expressions for that transaction type:

• transaction.amount
• transaction.currency
• transaction.items

Example Configurations

Replace a billing country value before sending to the PSP

Send a mapped country code to the PSP while keeping the original value stored in the database.

The following configuration replaces customer.billingCountry value UK with GB:

• Target Field : customer.billingCountry
• Action : Send to PSP
• Expression : transaction.customer.billingCountry == 'UK' ? 'GB' : transaction.customer.billingCountry

The PSP receives GB, while the original value UK is retained in the database.