Dynamic variable substitution

Dynamic variable substitution enables service configurations to reference and resolve values from multiple runtime data sources using a consistent placeholder syntax.

Instead of hardcoding values directly in configuration, you can dynamically retrieve values from the following sources:
  • Request payloads (JSON)
  • Request payloads (XML)
  • Request headers
  • Query parameters
  • OMS properties
  • JVM system properties
This capability helps you build more flexible, reusable, and configuration-driven integrations while reducing the need for custom code.
Attention: Dynamic variable substitution is a platform capability designed for broader use across Service Definition Framework (SDF) components. In the 10.0.2607.0 release, support is available only within REST API component configuration.

Benefits

Dynamic variable substitution helps you:

  • Build reusable service configurations
  • Avoid hardcoded values
  • Pass runtime business data to downstream services
  • Reuse integrations across environments and scenarios
  • Reduce custom extension development

Support in 10.0.2607.0

In the 10.0.2607.0 release, dynamic variable substitution can be configured in the following REST API component fields:

  • Endpoint URL
  • Request headers
  • Query parameters

Future SDF components may support the same capability as availability expands.

Supported expressions

The following placeholder expressions are supported:

Table 1. Supported expression syntax by source
Source Syntax example
OMS property ${yfs.some.property}
JVM system property ${sys:user.timezone}
Request header ${header:X-Tenant-ID}
Query parameter ${query:customerId}
JSON payload ${json:$.order.customerId}
XML payload ${xml://Order/@OrderNo}

Configure a dynamic endpoint URL

In the REST API configuration, enter expressions directly in the REST_URL field.

Example

REST_URL:

https://api.example.com/customers/${json:$.order.customerId}/orders

Incoming JSON:

{
  "order": {
    "customerId": "CUST1001"
  }
}

Resolved URL:

https://api.example.com/customers/CUST1001/orders

Configure dynamic request headers

In the Custom Headers section, you can use expressions as all or part of a header value.

Example 1: Header propagation

Table 2. Header propagation example
Header name Header value
Authorization Bearer ${header:X-Auth-Token}

Incoming header:

X-Auth-Token: abc123xyz

Header sent:

Authorization: Bearer abc123xyz

Example 2: Header value construction

Table 3. Header value construction example
Header name Header value
X-Order-Reference ORD-${json:$.order.orderNo}

Incoming JSON:

{
  "order": {
    "orderNo": "10001"
  }
}

Header sent:

X-Order-Reference: ORD-10001

This demonstrates that substitutions can be embedded within larger strings.

Configure dynamic query parameters

Example

Table 4. Dynamic query parameter example
Query parameter Value
region ${query:region}
customerId ${json:$.order.customerId}

Incoming request:

?region=us-east

Incoming JSON:

{
  "order": {
    "customerId": "CUST1001"
  }
}

Request sent:

?region=us-east&customerId=CUST1001

Use OMS and system properties

Values can be sourced from OMS properties or JVM system properties.

REST_URL using an OMS property:

${yfs.api.baseurl}/orders

Header configuration

Table 5. Header name and value
Header name Header value
X-Server-Timezone ${sys:user.timezone}

If the JVM is started with -Duser.timezone=America/New_York, the header resolves to:

X-Server-Timezone: America/New_York

Combine multiple sources

Expressions from different sources can be combined in a single field.

REST_URL:

https://api.example.com/customers/${json:$.customerId}/orders?region=${query:region}

Header

Table 6. Multi-source header example
Header name Header value
X-Correlation-ID ${sys:tenant.id}-${json:$.order.orderNo}

Result

URL:    https://api.example.com/customers/CUST001/orders?region=us-east
Header: X-Correlation-ID: acme-10001

Best practices

  • Use runtime substitution to avoid hardcoded customer-specific values.
  • Validate that referenced values will be available at runtime.
  • Reuse service configurations by externalizing deploy-time values into properties where appropriate.
  • Use meaningful header and parameter names to improve maintainability.