TABLE OF CONTENTS

• Commerce Connector - Mapping Functions and Macro Support
  • Overview
  • Supported Mappings
    • Example 1: Direct Property Mapping
    • Example 2: Nested Properties and Functions
  • Supported Functions
  • Function Notes
  • Macros Support in Step Configuration
    • Supported Macro Locations
      • i. Endpoint URL (API Transmission Mode)
      • ii. Query Parameters (API Transmission Mode)
      • iii. Header Parameters (API Transmission Mode)
      • iv. Custom Authentication Header Parameters (API Transmission Mode)
      • v. Pagination Parameters (API Transmission Mode)
  • Global Variables
    • i. Environment Variables (IsSecret = 0)
      • Examples
      • Typical Use Cases
    • ii. Secret Variables (IsSecret = 1)
      • Examples
      • Typical Use Cases
  • Usage Examples
    • Endpoint Example
  • Important Notes
  • Best Practices
  • Summary

Commerce Connector - Mapping Functions and Macro Support

Overview

The mapping capabilities in Commerce Connector have been enhanced to support Functions and Macro Mappings while maintaining backward compatibility with the existing YAML mapping implementation.

Supported Mappings

The following examples demonstrate the supported mapping formats.

Example 1: Direct Property Mapping

{
  "OrderNumber": "{{$Step1.data[].orderNumber}}",
  "LinkedOrderNumber": "{{$Step1.data[].linkedOrderNumber}}",
  "Status": "{{$Step1.data[].status}}",
  "StatusCode": "{{$Step1.data[].statusCode}}",
  "OrderDate": "{{$Step1.data[].orderDate}}",
  "CustomerId": "{{$Step1.data[].customer.customerId}}",
  "CustomerEmail": "{{$Step1.data[].customer.email}}"
}

Example 2: Nested Properties and Functions

{
  "dataAreaId": "usmf",
  "order.orderNumber": "{{ $Step1.data[].classNumber }}",
  "order.orderDate": "{{ FormatDate($Step1.data[].orderDate, "yyyy-MM-dd") }}",
  "order.status.status": "{{ $Step1.data[].classStatus }}",
  "order.customer.name": "{{ $Step1.data[].customerName }}",
  "order.customer.email": "{{ $Step1.data[].customerEmailId }}",
  "order.customer.conatenatednameemail": "{{ Concat($Step1.data[].customerName, " ", customerEmailId) }}",
  "order.customer.totalwithcurrency": "{{ Concat("$", Step1.data[].total) }}"
}

---

Supported Functions

The Commerce Connector mapping engine provides the following built-in functions.

Function	Syntax	Description	Example	Return Type
Upper	Upper(value)	Converts the input string to uppercase using the invariant culture.	Upper("active") → "ACTIVE"	string
Lower	Lower(value)	Converts the input string to lowercase using the invariant culture.	Lower("ADMIN") → "admin"	string
Trim	Trim(value)	Removes leading and trailing whitespace from the input string.	Trim(" John ") → "John"	string
Concat	Concat(value1, value2, ...)	Concatenates multiple values into a single string. Accepts any number of arguments.	Concat("ORD-", OrderNumber) → "ORD-1001"	string
Replace	Replace(text, oldValue, newValue)	Replaces all occurrences of a substring with another substring.	Replace("A-B-C","-","") → "ABC"	string
Substring	Substring(text,startIndex) Substring(text,startIndex,length)	Returns a portion of a string beginning at the specified index.	Substring("ORD1001",3) → "1001"	string
Left	Left(text,count)	Returns the specified number of characters from the beginning of a string.	Left("ORD1001",3) → "ORD"	string
Right	Right(text,count)	Returns the specified number of characters from the end of a string.	Right("ORD1001",4) → "1001"	string
Length	Length(value)	Returns the number of characters in a string or the number of elements in a collection.	Length("Hello") → 5	long
DateTime.Today	DateTime.Today()	Returns the current system date with the time component set to midnight (00:00:00).	DateTime.Today()	DateTime

DateTime.Now	DateTime.Now()	Returns the current local date and time.	DateTime.Now()	DateTime
DateTime.UtcNow	DateTime.UtcNow()	Returns the current Coordinated Universal Time (UTC).	DateTime.UtcNow()	DateTime
FormatDate	FormatDate(date, format)	Converts a date value into the specified .NET date format using the invariant culture.	FormatDate(OrderDate, "yyyy-MM-dd")	string
Math.Round	Math.Round(value) Math.Round(value, digits)	Rounds a numeric value using MidpointRounding.AwayFromZero.	Math.Round(10.456, 2) → 10.46	double
Math.Max	Math.Max(value1, value2, ...)	Returns the largest value from the supplied numeric arguments.	Math.Max(10, 15, 12) → 15	double
Math.Min	Math.Min(value1, value2, ...)	Returns the smallest value from the supplied numeric arguments.	Math.Min(10, 15, 12) → 10	double
Math.Abs	Math.Abs(value)	Returns the absolute (non-negative) value of a number.	Math.Abs(-25) → 25	double
Math.Ceiling	Math.Ceiling(value)	Rounds a decimal number upward to the nearest whole number.	Math.Ceiling(5.2) → 6	double
Math.Floor	Math.Floor(value)	Rounds a decimal number downward to the nearest whole number.	Math.Floor(5.9) → 5	double
Coalesce	Coalesce(value1, value2, ...)	Returns the first argument whose value is not null. It does not treat empty strings as null.	Coalesce(Customer.Email, "unknown@example.com")	Depends
IsNull	IsNull(value)	Returns true if the supplied value is null; otherwise returns false.	IsNull(Customer.Phone) → true	bool
Guid	Guid()	Generates a new globally unique identifier (GUID).	Guid()	Guid
Guid.NewGuid	Guid.NewGuid()	Alias for Guid(). Generates a new GUID.	Guid.NewGuid()	Guid

---

Function Notes

• Function names are case-insensitive. For example, Upper, upper, and UPPER are treated identically.
• Functions such as Concat, Coalesce, Math.Max, and Math.Min accept a variable number of arguments.
• Coalesce() returns the first non-null value. It does not treat an empty string ("") as null.
• FormatDate() expects a valid DateTime value and a standard .NET date format string (for example, yyyy-MM-dd or MM/dd/yyyy).
• Length() supports both strings and collections. Passing any other type results in an exception.
• Substring() validates the specified indexes and throws an exception if the requested range is outside the bounds of the string.
• Left() and Right() safely return the entire string if the requested length exceeds the string length.
• Math.Round() uses MidpointRounding.AwayFromZero, making it suitable for financial calculations.

---

Macros Support in Step Configuration

Macro mappings allow data generated in previous steps of a multi-step transmission pipeline to be referenced dynamically during runtime. The mapping engine uses the pattern {{$StepN.FieldName}} to resolve values from preceding steps.

Supported Macro Locations

i. Endpoint URL (API Transmission Mode)

Macros can be used within the endpoint URL to dynamically construct API endpoints.

Syntax

{{Step1.OrderNumber}}

Example

https://api.example.com/orders/{{Step1.OrderId}}

---

ii. Query Parameters (API Transmission Mode)

Example

Property	Value
Key	orderId
Value	{{Step1.OrderNumber}}

---

iii. Header Parameters (API Transmission Mode)

Example

Property	Value
Key	Authorization
Value	Bearer {{Step1.Token}}

---

iv. Custom Authentication Header Parameters (API Transmission Mode)

Example

Property	Value
Key	X-Customer-Id
Value	{{Step1.CustomerId}}

---

v. Pagination Parameters (API Transmission Mode)

Example

Property	Value
IndexParams.Value	{{Step1.PageNumber}}
SizeParams.Value	{{Step1.RecordsPerPage}}

---

Global Variables

Global Variables provide a centralized, reusable key-value store for environment-specific configuration. These values can be referenced throughout a multi-step data exchange using macro expressions, reducing duplication and simplifying configuration management.

i. Environment Variables (IsSecret = 0)

Environment Variables are stored as plain text and are readable in the database. They are intended for non-sensitive configuration values that may vary across environments but do not require encryption.

Examples

Key	Value	Is Secret
API_BASE_URL	https://api.prod.example.com	0
TENANT_ID	TENANT-789	0
WEBHOOK_TIMEOUT_MS	30000	0
REGION	US-EAST-1	0
FEATURE_FLAG_V2_API	true	0

Typical Use Cases

• Non-sensitive API endpoints and webhook URLs
• Configuration flags and feature switches
• Numeric settings such as timeouts and batch sizes
• Public identifiers including tenant IDs and region names

---

ii. Secret Variables (IsSecret = 1)

Secret Variables are stored as DPAPI-encrypted values in the database and are intended for sensitive information that must remain encrypted at rest.

Examples

Key	Value	Is Secret
API_KEY_PROD	[ENCRYPTED_CIPHERTEXT_1234]	1
DB_PASSWORD	[ENCRYPTED_CIPHERTEXT_5678]	1
OAUTH_CLIENT_SECRET	[ENCRYPTED_CIPHERTEXT_9012]	1

Typical Use Cases

• API Keys and access tokens
• Database passwords
• OAuth Client Secrets
• Webhook signing secrets
• Private encryption keys

---

Usage Examples

The following examples demonstrate how Environment and Secret Variables can be referenced throughout Commerce Connector configurations.

Endpoint Example

{{Env.API_BASE_URL}}/v2/products?region={{Env.REGION}}

Component	Field	Example
API Configuration	Endpoint	{{Env.API_BASE_URL}}/v2/orders
API Configuration	Query Parameters	key={{Secret.API_KEY}}
API Configuration	Headers	Authorization: Bearer {{Secret.TOKEN}}
API Configuration	Username	{{Env.SERVICE_ACCOUNT}}
API Configuration	Password	{{Secret.SERVICE_PASSWORD}}
SFTP Configuration	Host	{{Env.SFTP_HOST}}
SFTP Configuration	Username	{{Env.SFTP_USER}}
SFTP Configuration	Password	{{Secret.SFTP_PASSWORD}}
SFTP Configuration	Remote File Path	/inbox/{{Env.TENANT_ID}}/data.csv
Blob Configuration	Connection String	Contains {{Secret.BLOB_KEY}}
Blob Configuration	Container Name	{{Env.CONTAINER_PREFIX}}-staging
Request Body Template	Any JSON Field	{"api_key":"{{Secret.API_KEY}}"}
Pagination Configuration	Page Size	{{Env.PAGE_SIZE}} (if numeric)
Mapping Template	Any Transformation Field	{{Env.CURRENCY_CODE}}

---

Important Notes

• Function names are case-insensitive and can be used in any combination of upper or lower case.
• Macro expressions are evaluated at runtime using values from previous steps or configured Global Variables.
• Functions and macros can be combined within the same mapping expression to perform dynamic transformations.
• Existing YAML mappings continue to be supported, ensuring backward compatibility with previously configured Data Exchanges.
• Global Variables should be used for reusable configuration values to avoid hardcoding environment-specific information within mappings.
• Sensitive information such as API keys, passwords, OAuth secrets, and connection strings should always be stored as Secret Variables.

---

Best Practices

• Use descriptive Step Codes to improve mapping readability.
• Store environment-specific values as Global Variables instead of hardcoding them in requests.
• Store all sensitive values as Secret Variables.
• Use mapping functions to perform transformations instead of creating custom processors wherever possible.
• Validate mappings using sample payloads before deploying to production.
• Keep mapping expressions simple and reusable to improve maintainability.

---

Summary

Commerce Connector provides a powerful mapping engine that supports direct property mappings, nested object mappings, built-in transformation functions, macro expressions, and reusable Global Variables. These capabilities simplify the creation of dynamic, reusable, and environment-independent integrations while maintaining full backward compatibility with existing YAML-based mappings.