Skip to main content

6.4 Placeholder Resolutions - Connectable Elements

Placeholder Resolution (${...})​

Overview​

Placeholders in the form ${...} allow values to be resolved dynamically at runtime.
They are used to connect datapoints, pass input through connectors, and interpolate values into strings.

Placeholders can be used anywhere a string value is accepted.

Syntax​

${expression}

The expression is evaluated against the current execution context.

Expression Language​

Internally, placeholder expressions are evaluated using a JSONata-compatible expression engine (see also: Using JSONata).

Note: Only the documented namespaces and fields are considered stable and supported.

Placeholder expressions use a JSONata-compatible expression language. When accessing object properties, the allowed characters depend on the notation used.

An unquoted property name has to be a valid JSONata identifier:

  • Letters: A–Z, a–z
  • Digits: 0–9 (not as the first character)

A name containing anything else — a dash, a space, a period — is still reachable, but only if it is quoted in the expression. Backticks, single quotes and double quotes all work:

${response.firstRef.headers.'content-type'}
${response.firstRef.headers.`content-type`}

Unquoted, those characters are read as JSONata operators: ref.my-value is parsed as ref.my minus value, which evaluates to nothing. No error is raised — the placeholder simply resolves to empty.

That is why names you create yourself — above all a connector element's ref — should be camelCase: see Naming Convention Guidelines. Quoting is for names you do not control, such as HTTP header names in a response.

Resolution Rules​

  • Placeholders are resolved before execution of the element
  • Multiple placeholders in a string are supported
  • Resolution is context-dependent: which namespaces exist depends on where the placeholder sits

Namespaces by scope​

This is the complete set. A namespace that is not listed for a scope does not exist there, and an expression referencing it resolves to nothing rather than failing.

NamespaceDatapointConnector elementInput transformerOutput transformerDescription
inputyesyesyesyesThe current execution payload. In a connector this is the output of the previous element
envyesyesyesyesValues of environment elements registered in the repository
root—yes——The payload the connector was invoked with, unchanged for the whole execution
ref—yes——Documented output of an earlier element in the same connector
response—yes——Full HTTP response of an earlier element in the same connector
params—yes——The parameters declared on the current connector element
output———yesThe result of the element the transformer is attached to
template————Resolved once at template instantiation, not at execution time

A datapoint invoked on its own therefore has only input and env. The same datapoint used inside a connector can additionally be given root, ref, response and params values — but only through the parameters of the connector element that calls it, because those namespaces are resolved in the connector's context, not the datapoint's.

Do not reference ref, response, root or params inside a datapoint definition

They are not part of a datapoint's resolution context. Pass the value in from the connector element's parameters instead, and read it in the datapoint as ${input.<name>}.

Nothing warns you about this. There are no datapoint-specific validation rules, so such an expression is stored without complaint and resolves to nothing at execution time — the datapoint runs and receives an empty parameter. See Semantic Validation Rules for what the editor does and does not check.

Environment variables (env)​

${env.<key>} resolves against the environment elements registered in the repository, so a value that differs per deployment — an API base URL, a tenant identifier — can live outside the datapoint definition and move with the environment rather than with the solution.

The lookup happens lazily: it is performed only when an expression in the element actually contains env., and the resolved values are not written into the stored definition.


Placeholders in Datapoints​

Datapoints support placeholders to dynamically resolve values from their execution input.
Placeholders are resolved before the datapoint is executed.

Supported namespaces​

NamespaceDescription
inputInput object passed to the datapoint at execution time
envValues of environment elements registered in the repository

These two are the only namespaces available in a datapoint definition. See Namespaces by scope.

Example datapoint (minimal)​

{
"id": "example-dp-echo-postman",
"type": "datapoint",
"datapoint": {
"type": "http",
"parameters": {
"echo": "${input.text}"
}
}
}

Execution body​

{
"id": "echo-postman",
"input": {
"text": "test"
}
}

Placeholder resolution​

${input.text} → "test"

Example datapoint response​

{
"state": "SUCCESS",
"result": {
"data": {
"echo": "test"
}
}
}

Output contract​

When a datapoint is used inside a connector, its result payload is exposed via:

ref.<refName>

For this datapoint, the documented and stable output is:

ref.<refName>.data.echo : string

Schemas (optional)​

Datapoints may define optional input and output schemas.

  • Schemas are informational only
  • Schemas are not enforced at runtime
  • Schemas document stable fields intended for use by connectors

Full datapoint definition​

The following section shows the complete datapoint definition, including schemas, for reference.

{
"id": "example-dp1-echo-postman",
"type": "datapoint",
"version": "0.0.1",
"displayName": "echo postman endpoint",
"tags": [
"automated-testing",
"bootstrap-testing"
],
"description": "",
"deprecated": false,
"name": "echo postman endpoint",
"datapoint": {
"type": "http",
"http": {
"url": "https://postman-echo.com/post",
"method": "POST",
"headers": {
"content-type": "application/json"
}
},
"parameters": {
"echo": "${input.text}"
}
},
"owner": "",
"input": {
"schema": {
"type": "json",
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "echo-postman input",
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"description": "Text that will be echoed by the datapoint."
}
}
}
}
},
"output": {
"schema": {
"type": "json",
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "echo-postman output",
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"required": [
"echo"
],
"properties": {
"echo": {
"type": "string",
"description": "Echoed value originating from input.text."
}
}
}
}
}
}
}
}

Connectors​

Connectors orchestrate the execution of multiple connectable elements and allow data to be passed between them using placeholders.

Elements are executed sequentially in the order they are defined.

Placeholder namespaces​

The following namespaces are available when resolving placeholders inside connectors.

NamespaceDescription
inputThe current execution payload — the output of the previous element
rootThe payload the connector was invoked with, unchanged throughout
refDocumented output of previously executed elements
responseFull HTTP response of previously executed elements
paramsThe parameters declared on the current connector element
envValues of environment elements registered in the repository

input​

The input namespace represents the current execution payload.

In connectors, this payload may originate from the initial connector input or from a previous execution step, depending on the execution order.

root​

The root namespace provides access to the initial execution context of the connector.

This allows access to values that remain constant throughout the connector execution.

ref​

The ref namespace exposes the documented output payload of previously executed connector elements.

For an element with the reference firstRef, the documented output is accessible under:

ref.firstRef

Only fields documented by the referenced datapoint should be accessed via ref.

response​

The response namespace exposes the full HTTP response of executed connector elements.

This allows access to HTTP-level information such as status codes, headers, and raw response bodies.

For an element with the reference firstRef, the HTTP response is available under:

response.firstRef

Accessing HTTP response properties​

HTTP response properties can be accessed using JSONata-compatible expressions.

When property names contain special characters (such as hyphens), quoted notation must be used.

Example:

${response.firstRef.headers.'content-type'}

Relationship between ref and response​
NamespacePurpose
refStable, documented output intended for data flow
responseFull HTTP response including protocol-level details

Use ref.* for business logic and data passing between elements.
Use response.* only when HTTP-specific information is required.

⚠️ Note: The "response" placeholder only works for http responses and only works on server side - connectivity triggered from an OLIVE micro frontend can not interpret the response placeholder correctly.

Execution order​

  • Connector elements are executed top to bottom
  • Only elements that have already been executed can be referenced via ref or response
  • Placeholders are resolved before each element execution

Special cases (advanced usage)​

Placeholders in datapoint HTTP properties​

Placeholders can be used inside certain datapoint HTTP configuration properties,
such as URLs and header values.

This allows datapoints to be more flexible and environment-agnostic.

Example

{
"datapoint": {
"type": "http",
"http": {
"url": "https://${input.postmanUrl}/post",
"method": "POST",
"headers": {
"content-type": "${input.contentType}"
}
},
"parameters": {
"echo": "${input.text}"
}
}
}

Important limitations​

The following is not supported:

  • Using placeholders to generate property keys
  • Using placeholders to dynamically change parameter names

Placeholders in datapoint properties are supported for values only.

Recommendation​

  • Prefer placeholders in parameters
  • Use placeholders in HTTP properties sparingly
  • Treat this as advanced usage