Skip to main content

6.7.2 Calling OLIVE Platform APIs

This section explains how to trigger connectivity jobs and upload files on the OLIVE platform using its public APIs. Two execution approaches are covered:

  • API execution using Bruno
  • Command-line execution using Windows batch (.bat) files

Both approaches illustrate the same core workflows:

  • Invoking a connectivity job via the data-orchestrator (formerly data-layer) API
  • Polling the job until it reaches the SUCCESS state
  • Uploading files via the public file-storage-service API

All examples use the same public OLIVE endpoints; only the tooling differs.

These examples are for external API clients

They call the public OLIVE endpoints from a script, a terminal or a tool such as Bruno, and the full API is available to them subject to the caller's role. A pilet rendered inside the platform is different: from OLIVE 1.3 it may only reach the local paths /data-orchestrator/ and /repository/get, plus this public file-storage-service API with GET — uploads through it are not available to a pilet. See Client Microfrontends.

In addition, OLIVE public APIs can be invoked directly through the OpenAPI documentation by using the “Try it out” feature (API documentation). This allows you to execute requests directly from the browser without any local tooling.

Calling these same APIs from inside connectivity

An HTTP datapoint can call the public OLIVE APIs as well — that is the usual way to use file-storage-service or session-memory from a connector. In an unauthenticated development environment no credentials are needed; in an authenticated environment the datapoint must reference an Auth entry. See Calling OLIVE's own APIs from connectivity.

Connectivity can also be triggered programmatically from a custom user interface. In this model, a UI event (for example, a button click or workflow action) initiates connectivity execution. This approach is described here: Connectivity Structure.

Execution Options​

Bruno Collection​

The Bruno collection contains requests that allow you to:

  • Invoke a connectivity job via the data-orchestrator API
  • Poll the connectivity job until it reaches SUCCESS
  • Upload a file via the file-storage-service API

This option is recommended for interactive exploration and debugging.

Command Line (Windows .bat)​

Two batch scripts are provided for non-interactive or automated usage:

  • invoke-and-poll.bat
    Invokes a connectivity job, polls its status until SUCCESS, and prints the final result.
  • upload-file.bat
    Uploads a file using a multipart form request to the file-storage-service API.

Common Configuration​

All examples use the following variable:

  • envURL — Base URL of the OLIVE public API endpoint

Example:

  • https://api.<tenant>.<cluster>.<domain>/

Ensure that the chosen envURL matches the expected API base path for your environment.

Examples Using Bruno​

Setting Up Environment Variables in Bruno​

Before using the collection, environment variables must be configured. Variables can be defined at either the collection level or globally.

Required Variables​

  • envURL — Base URL of your API endpoint
    Example: https://api.<tenant>.<cluster>.<domain>/

Option 1: Collection-Level Variables​

  1. Open Bruno and load the collection

  2. Select the collection in the sidebar

  3. Open the Environments tab

  4. Create or edit an environment

  5. Add the variable:

    envURL: https://your-api-endpoint.com/

  6. Save the environment

  7. Select the environment from the top-right dropdown

Option 2: Global Variables​

Global variables are available across all Bruno collections.

  1. Open Settings in Bruno

  2. Navigate to Environments

  3. Open Global Environment

  4. Add the variable:

    envURL: https://your-api-endpoint.com/

  5. Save the changes

Official Documentation​

Detailed guidance on variable management is available in the official Bruno documentation:
https://blog.usebruno.com/manage-variables

Invoke Connectivity​

Invokes a connectable datapoint. The returned jobID is automatically stored as a variable so that polling can be executed immediately afterward. Ensure the referenced datapoint exists in the connectivity repository.

invoke-connectivity-call.bru

meta {
name: invoke connectivity
type: http
seq: 1
}

post {
url: {{envURL}}data-orchestrator/v1/invoke
body: json
auth: inherit
}

body:json {
{
"id": "postman_dp_http-postman-post",
"input": {
"test": "Hello, World!"
}
}
}

vars:post-response {
jobID: res.body.jobID
}

docs {
Invoke connectable elements. The jobID is stored in a variable, poll connectivity can directly be called afterwards.
}

Response:

Returns a jobID that is captured for subsequent polling.

Poll Connectivity​

Polls the current state or final result of a connectivity job.

poll-connectivity-result-call.bru

meta {
name: poll connectivity
type: http
seq: 2
}

post {
url: {{envURL}}data-orchestrator/v1/poll
body: json
auth: inherit
}

body:json {
{
"jobID": "{{jobID}}"
}
}

docs {
Poll the current state or the result of a job.
}

Prerequisites:

  • Requires the jobID variable captured from the invoke request

Response:

Returns the current job state and, upon completion, the execution result.

Upload File​

Uploads a file to the public file-storage-service.

upload-file-call.bru

meta {
name: upload file
type: http
seq: 3
}

post {
url: {{envURL}}file-storage-service/upload
body: multipartForm
auth: inherit
}

body:multipart-form {
file: @file(naming-convention-guidelines.pdf)
}

docs {
Uploads a file to the public file-storage-service. The form field must be named "file", and the
file name becomes part of the storage key, so it must not contain spaces.
}

Response:

Returns upload confirmation and file metadata.

Additional Notes for Bruno​

  • Ensure the API endpoint is reachable before executing requests
  • The jobID variable is populated automatically after invoking connectivity
  • The upload example requires the referenced file to be present

Examples Using Command Line (.bat)​

Connectivity and file uploads can also be executed from the Windows command line. The provided batch files use curl.exe and PowerShell to interact with the same public OLIVE APIs.

invoke-and-poll​

This script executes the full connectivity lifecycle:

  1. Sends POST {{envURL}}data-orchestrator/v1/invoke using a JSON input file
  2. Extracts the returned jobID
  3. Polls POST {{envURL}}data-orchestrator/v1/poll
  4. Repeats polling until the job reaches SUCCESS
  5. Prints the final poll response to the console

invoke-and-poll.bat

@echo off
setlocal

rem ===== Config =====
set "envURL=https://api.<tenant>.<cluster>.<domain>/"
rem Optional: extra curl args (edit as needed)
set "CURL_EXTRA="

if "%~1"=="" (
echo Usage:
echo %~nx0 path\to\invoke.json
echo.
echo Example:
echo %~nx0 .\input.json
exit /b 1
)

set "BODY_ARG=%~1"
set "PS1=%~dp0invoke-and-poll.ps1"

if not exist "%PS1%" (
echo ERROR: Missing "%PS1%"
exit /b 2
)

powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" -EnvURL "%envURL%" -BodyArg "%BODY_ARG%"
exit /b %ERRORLEVEL%


invoke-and-poll.ps1

param(
[Parameter(Mandatory=$true)][string]$EnvURL,
[Parameter(Mandatory=$true)][string]$BodyArg
)

# Normalize base URL
if (-not $EnvURL.EndsWith('/')) { $EnvURL += '/' }

$invokeUrl = $EnvURL + 'data-orchestrator/v1/invoke'
$pollUrl = $EnvURL + 'data-orchestrator/v1/poll'

# Resolve invoke body: either a file path or inline JSON
[string]$invokeBodyFile = $null
if (Test-Path -LiteralPath $BodyArg) {
$invokeBodyFile = (Resolve-Path -LiteralPath $BodyArg).Path
} else {
$invokeBodyFile = Join-Path $env:TEMP ("invoke_body_{0}.json" -f ([Guid]::NewGuid().ToString('N')))
[IO.File]::WriteAllText($invokeBodyFile, $BodyArg, [Text.UTF8Encoding]::new($false))
}

# Read + validate invoke JSON (encoding-safe)
try {
$invokeBodyText = [IO.File]::ReadAllText($invokeBodyFile)
$null = $invokeBodyText | ConvertFrom-Json
} catch {
Write-Host "ERROR: Provided invoke body is not valid JSON."
Write-Host ("File used: `"{0}`"" -f $invokeBodyFile)
Write-Host ("JSON parse error: " + $_.Exception.Message)
exit 1
}

# Optional curl extras from environment (keep empty unless you know you need it)
$curlExtra = @()
if ($env:CURL_EXTRA -and $env:CURL_EXTRA.Trim().Length -gt 0) {
$curlExtra = $env:CURL_EXTRA.Split(' ', [System.StringSplitOptions]::RemoveEmptyEntries)
}

# Temp poll file
$pollBodyFile = Join-Path $env:TEMP ("poll_body_{0}.json" -f ([Guid]::NewGuid().ToString('N')))

# ----------------
# INVOKE
# ----------------
$invokeArgs = @('-s') + $curlExtra + @(
'-H','Content-Type: application/json',
'-X','POST', $invokeUrl,
'--data-binary', ('@' + $invokeBodyFile)
)

$invokeRespText = & curl.exe @invokeArgs

Write-Host "Invoke response:"
Write-Host $invokeRespText

if (($LASTEXITCODE -ne 0) -or [string]::IsNullOrWhiteSpace($invokeRespText)) {
Write-Host "ERROR: invoke call failed."
exit 3
}

# Extract jobID (support top-level jobID and nested body.jobID)
[string]$jobID = $null
try {
$invokeObj = $invokeRespText | ConvertFrom-Json
$jobID = $invokeObj.jobID
if (-not $jobID -and $invokeObj.body) { $jobID = $invokeObj.body.jobID }
} catch {
Write-Host "ERROR: Could not parse invoke response as JSON."
exit 4
}

if (-not $jobID) {
Write-Host "ERROR: jobID not found in invoke response."
exit 4
}

# ----------------
# POLL loop (max 300 tries, 100ms)
# ----------------
for ($i = 1; $i -le 300; $i++) {

$pollBodyJson = (@{ jobID = $jobID } | ConvertTo-Json -Compress)
[IO.File]::WriteAllText($pollBodyFile, $pollBodyJson, [Text.UTF8Encoding]::new($false))

$pollArgs = @('-s') + $curlExtra + @(
'-H','Content-Type: application/json',
'-X','POST', $pollUrl,
'--data-binary', ('@' + $pollBodyFile)
)

$pollRespText = & curl.exe @pollArgs

Write-Host ("Poll #{0} response:" -f $i)
Write-Host $pollRespText

if (($LASTEXITCODE -ne 0) -or [string]::IsNullOrWhiteSpace($pollRespText)) {
Start-Sleep -Milliseconds 100
continue
}

try {
$pollObj = $pollRespText | ConvertFrom-Json

if ($pollObj.error) {
Write-Host "ERROR: poll endpoint returned an error:"
Write-Host $pollRespText
exit 6
}

if ($pollObj.state -eq 'SUCCESS') {
# Print final JSON result and exit
$pollRespText
exit 0
}
} catch {
# ignore parse errors and keep polling
}

Start-Sleep -Milliseconds 100
}

Write-Host "ERROR: Polling timed out after 300 tries."
exit 5


Usage:

.\invoke-and-poll.bat .\input.json

input.json

{
"id": "postman-dp-http-postman-post",
"input": {
"test": "Hello, World!"
}
}

The script prints the invoke response, intermediate poll responses, and the final SUCCESS result.

upload-file​

Uploads a file to the public OLIVE file-storage-service API.

  1. Sends a multipart/form-data request
  2. Uploads the specified file
  3. Prints the returned file key and download URL

upload-file.bat

@echo off
setlocal

rem ===== Config =====
set "envURL=https://api.<tenant>.<cluster>.<domain>/"
rem Optional: add auth headers etc. (simple tokens only)
set "CURL_EXTRA="

rem ===== File to upload (EDIT THIS) =====
set "UPLOAD_FILE="

rem Allow overriding the file path via first argument:
rem .\upload-file.bat "C:\path\to\file.pdf"
if not "%~1"=="" set "UPLOAD_FILE=%~1"

set "PS1=%~dp0upload-file.ps1"
if not exist "%PS1%" (
echo ERROR: Missing "%PS1%"
exit /b 2
)

powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" -EnvURL "%envURL%" -FilePath "%UPLOAD_FILE%"
exit /b %ERRORLEVEL%



upload-file.ps1

param(
[Parameter(Mandatory=$true)][string]$EnvURL,
[Parameter(Mandatory=$true)][string]$FilePath
)

# Normalize base URL
if (-not $EnvURL.EndsWith('/')) { $EnvURL += '/' }
$uploadUrl = $EnvURL + 'file-storage-service/upload'

# Validate file
if (-not (Test-Path -LiteralPath $FilePath)) {
Write-Host "ERROR: File not found:"
Write-Host $FilePath
exit 1
}

$resolved = (Resolve-Path -LiteralPath $FilePath).Path

# Optional curl extras from environment
$curlExtra = @()
if ($env:CURL_EXTRA -and $env:CURL_EXTRA.Trim().Length -gt 0) {
$curlExtra = $env:CURL_EXTRA.Split(' ', [System.StringSplitOptions]::RemoveEmptyEntries)
}

# Build curl args for multipart upload
# IMPORTANT: The form field name here is "file".
$curlArgs = @('-s') + $curlExtra + @(
'-X','POST', $uploadUrl,
'-F', ('file=@' + $resolved)
)

$response = & curl.exe @curlArgs

Write-Host "Upload response:"
Write-Host $response

if ($LASTEXITCODE -ne 0) {
Write-Host "ERROR: curl upload failed (exit code $LASTEXITCODE)."
exit 2
}

exit 0


Usage:

.\upload-file.bat "..\naming-convention-guidelines.pdf"

Returns a JSON response containing:

  • key
  • filename
  • url for downloading the file

Notes for Command Line Usage​

  • curl.exe must be available on the system (included with modern Windows versions)
  • Verify that envURL inside the .bat files matches your OLIVE environment
  • File upload examples require the referenced file path to exist