Skip to main content

6.2 Datapoints

Datapoints are the fundamental execution units in OLIVE. They define what external interaction should happen and how it should be executed, without prescribing when or in which sequence this execution takes place.
This separation allows datapoints to be reused across connectors and workflows.

Conceptually, a datapoint represents a single, well-defined operation, such as:

  • Calling a REST endpoint
  • Executing a cloud function
  • Triggering an AI prompt
  • Performing a semantic search

Datapoints are passive definitions. They become active only when they are invoked by the OLIVE Data-Orchestrator, either directly or as part of a connector execution.

See also the definition in the data metamodel: DataPoint

Syntax and Structure​

Every datapoint is defined as a JSON configuration with a stable outer structure and a specialized inner definition.

A datapoint definition consists of two conceptual layers:

  1. Metadata layer
    Used for identification, versioning, and discoverability.
  2. Execution layer
    Defines the technical behavior of the datapoint.

A minimal structure looks as follows:

{
"id": "example-datapoint",
"type": "datapoint",
"version": "0.0.1",
"datapoint": {
"type": "http"
}
}

The outer attributes (id, name, tags, version) are managed by the OLIVE repository and tooling.
The inner datapoint object defines the executable logic and is specialized by its type.

Field reference​

Outer attributes — the same on every connectable element:

FieldTypeRequiredDescription
idstringyesUnique identifier. Registering an element with an existing id overwrites it
typestringyes"datapoint"
versionstringyesInformational only; does not affect identity
namestring—Technical name, shown in the connectivity editor
displayNamestring—Name shown in user-facing, non-technical contexts
descriptionstring—What the element does
tagsstring[]—For search and grouping, and for selecting an export set
deprecatedboolean—Default false
ownerstring—Person responsible for the element
inputobject—Input DataHandler — schema and input transformer
outputobject—Output DataHandler — schema and output transformer
templateID, originalID, mmVersionstring—Set by the platform during template instantiation. Do not set these by hand

datapoint — the execution layer, common to every datapoint type:

FieldTypeRequiredDescription
typestringyesThe technical type: http, transform, cloudfunction, manualtask, mock, or an extension type such as prompt, agent, mcpserver
<type>object—The type-specific configuration, under a key matching type — http for an HTTP datapoint, transform for a transform datapoint, and so on
parametersobject | string | number | boolean—Default values passed to the datapoint. Merged with the incoming input, which wins on a key collision
authstring | object—An auth entry id, a placeholder resolving to one, or an inline auth object
asyncboolean—Whether the datapoint resolves later rather than returning immediately. Default false; manualtask is asynchronous by default. See Long Running & Asynchronous Datapoints
auth sits on datapoint, not inside the type-specific block

It is resolved as datapoint.auth. Placing it inside datapoint.http, or at the root of the element beside id and type, leaves the request unauthenticated — the property is simply not read there, and nothing reports an error. Only datapoints can carry auth; connectors and workflows cannot.

input and output — both are a DataHandler:

FieldTypeDescription
schemastring | objectEither the id of a schema element in the repository, or a schema configuration: { "type": "json" | "xml", "schema": { … } }. A url may be given instead of inline content. Not enforced at runtime
transformerobject{ "type": "jsonata", "transform": "${ … }" }. type defaults to jsonata, which is the only supported engine. See Transforming Connectivity Input & Output Data

HTTP Datapoints​

HTTP is a concrete specialization of the abstract Datapoint concept.
An HTTP datapoint represents exactly one HTTP request.

It defines all information required to execute this request, including:

  • Target URL
  • HTTP method
  • Optional headers and parameters
  • Optional authentication reference

Because HTTP datapoints specialize Datapoint, they can:

  • Be executed directly via the OLIVE Data-Orchestrator
  • Be orchestrated inside connectors

Example: HTTP Datapoint

The following example shows an HTTP datapoint.

{
"id": "base-dp-call-http-post-params",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-call-http-post-params",
"displayName": "base-dp-call-http-post-params",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Example HTTP datapoint that executes a POST request to a URL provided via input. It declares datapoint parameters and forwards the provided input values into the request payload for the target endpoint.",
"deprecated": false,
"datapoint": {
"type": "http",
"http": {
"url": "${input.urlPost}",
"method": "POST",
"headers": {
"Content-Type": "application/json"
}
},
"parameters": "${input.params}"
}
}

Example: HTTP Datapoint with Authentication

The following example shows an HTTP datapoint that performs a GET request against a protected endpoint.

{
"id": "base-dp-call-http-get-auth",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-call-http-get-auth",
"displayName": "base-dp-call-http-get-auth",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Simple example datapoint that performs an HTTP GET request to a user-supplied URL. Intended for demonstrating basic connectivity and validating HTTP request execution.",
"datapoint": {
"type": "http",
"http": {
"url": "${input.urlGet}",
"method": "GET"
},
"auth": "${input.authID}"
}
}

Explanation:

  • datapoint.type
    Declares this datapoint as an HTTP datapoint.
  • datapoint.http block
    Defines the concrete HTTP request that will be executed.
  • datapoint.auth
    References an authentication object that is resolved at execution time.
  • datapoint.parameters
    Endpoints expect input data, so the required payload must be defined using datapoint parameters. Without declared parameters, no input is passed.

The mechanics of dynamic value resolution ${input} and placeholder syntax are described in detail in the Placeholder Resolution documentation and are not covered in this chapter: Placeholder Resolutions - Connectable Elements

Http request body​

If a http datapoint should be sent with a body, there are multiple options:

  • Define a body directly in the http datapoint
  • Define parameters on the datapoint — they are used as the body if no other body is set
  • Call the datapoint with input parameters
    • If no other body is set they are used as body instead
    • If no other body is set but parameters are defined, then the input parameters are merged with the datapoint parameters

Example with body:

{
"id": "base-dp-call-http-post-body",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-call-http-post-body",
"displayName": "base-dp-call-http-post-body",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Generic example datapoint that performs an HTTP POST request to a user-specified URL with a JSON request body.",
"deprecated": false,
"datapoint": {
"type": "http",
"http": {
"url": "${input.urlPost}",
"method": "POST",
"headers": {
"Content-Type": "application/json"
},
"body": "${input.body}"
}
}
}

The http block​

FieldTypeDescription
urlstringTarget URL. Placeholders are allowed, subject to the per-position character rules in Security in Connectivity Engineering
methodstringGET, POST, PUT, PATCH, DELETE, …
headersobjectRequest headers. Header names cannot be produced by a placeholder
queryobjectQuery parameters
bodyobject | stringRequest body. When set, it is used as-is and is not merged with the incoming parameters
redirectstringWhat to do with a redirect response. Passed to the HTTP client, so the values are follow (the default), error and manual
allowErrorStatusbooleanDefault false. By default a response with status 400 or above makes the datapoint fail; set this to true when an error status is a valid result you want to inspect

There is no auth inside this block — see the note under Field reference above.

Transform Datapoints​

Transform is a concrete specialization of the abstract Datapoint concept.

A Transform datapoint defines a lightweight, declarative transformation step that is executed inside the OLIVE runtime. It is used to modify, reshape, or derive data from the incoming input without invoking an external system.

Transform datapoints are typically used to:

  • Post-process the output of another datapoint
  • Prepare or normalize input data before passing it to the next datapoint in a connector
  • Restructure payloads using a declarative expression language

Because Transform datapoints specialize Datapoint, they can:

  • Be executed directly via the OLIVE Data-Orchestrator
  • Be orchestrated inside connectors and workflows

Example: Transform Datapoint

The following example shows a Transform datapoint that maps two input parameters into a new object structure.

{
"id": "base-dp-transformer-jsonata",
"type": "datapoint",
"version": "0.0.1",
"name": "base-dp-transformer-jsonata",
"displayName": "base-dp-transformer-jsonata",
"tags": [
"simple-example",
"example",
"scenario-example-base",
"scenario-example-base-datapoints"
],
"description": "Example Transform datapoint that uses a JSONata expression to map multiple input parameters into a new structured output object. Demonstrates how input values can be reshaped and prepared for consumption by subsequent datapoints in a workflow or connector.",
"datapoint": {
"type": "transform",
"transform": "${ {\"firstParam\": input.param, \"secondParam\": input.param2} }"
}
}

Explanation:

  • datapoint.type
    Declares this datapoint as a Transform datapoint.
  • datapoint.transform
    Defines the transformation expression. The expression is evaluated using Jsonata and applied to the input payload.
  • input.param, input.param2
    Refer to values provided at execution time, either directly via the Data-Orchestrator or as output from a previous datapoint in a connector.

The result of the transformation is returned as the datapoint output and can be consumed by subsequent datapoints. The mechanics of dynamic value resolution ${input} and placeholder syntax are described in detail in the Placeholder Resolution documentation and are not covered in this chapter: Placeholder Resolutions - Connectable Elements

For details on the Jsonata expression syntax, see: Using JSONata

Authentication and Datapoints​

Datapoints do not store credentials directly.
Instead, authentication is modeled as a separate concept and referenced from the datapoint. For more information on authentication and secret management: Authentication and Secrets Management

This design provides:

  • Separation of concerns
  • Centralized credential management
  • Reusability across multiple datapoints
  • Improved security by avoiding embedded secrets

An HTTP datapoint may reference an Auth object, but the datapoint itself remains independent of the concrete authentication details.

Datapoints that call OLIVE's own APIs need auth too

In an unauthenticated development deployment, OLIVE's public APIs (file-storage-service, session-memory, data-orchestrator, repository) accept a request without credentials, so a bare HTTP datapoint works. In an authenticated deployment the same datapoint is rejected with 401.

If your datapoint calls an OLIVE service, add an auth reference of type oidc before the solution goes into productive use: Calling OLIVE's own APIs from connectivity.

Registering Datapoints in OLIVE​

Datapoints must be created and registered in the OLIVE connectivity editor before they can be used.

Registration makes the datapoint:

  • Addressable by its id
  • Discoverable in the OLIVE Connectivity Editor
  • Available for execution via the Data-Orchestrator
  • Reusable in connectors

Registration is declarative. No execution happens at this stage.

Executing Datapoints​

Datapoints are executed only when they are explicitly invoked.

Typical execution paths include:

  1. Direct execution via the OLIVE Data-Orchestrator: Service APIs – Version 1
  2. Execution as part of a connector
  3. Invocation by a tool like Bruno

Example execution request, using an API tool like Bruno:

{
"id": "base_dp_call-http-get-auth",
"input": {
"authID": "base_a_bearer-api-key"
}
}

At runtime, OLIVE:

  • Resolves all required references
  • Applies authentication
  • Executes the HTTP request
  • Returns the result to the caller

Key Takeaways​

  • Datapoints are reusable, passive definitions of executable operations
  • HTTP datapoints represent a single, concrete HTTP request
  • Authentication is referenced, not embedded
  • Datapoints must be registered before use
  • Execution happens only when datapoints are explicitly invoked
  • Dynamic value resolution is handled separately and documented elsewhere

This approach keeps OLIVE connectivity definitions modular, secure, and easy to maintain across different scenarios and environments.

Restriction: JSON return values​

In the current version of OLIVE it is not possible to have a datapoint return a JSON object with the property name "result" on root level.

Not working:

{
"result": "my-result-text"
}

Working:

{
"someproperty": {
"moreproperties": {
"result": "my-result-text"
}
}
}