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
SUCCESSstate - Uploading files via the public
file-storage-serviceAPI
All examples use the same public OLIVE endpoints; only the tooling differs.
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.
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 untilSUCCESS, 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
-
Open Bruno and load the collection
-
Select the collection in the sidebar
-
Open the Environments tab
-
Create or edit an environment
-
Add the variable:
envURL: https://your-api-endpoint.com/ -
Save the environment
-
Select the environment from the top-right dropdown
Option 2: Global Variables
Global variables are available across all Bruno collections.
-
Open Settings in Bruno
-
Navigate to Environments
-
Open Global Environment
-
Add the variable:
envURL: https://your-api-endpoint.com/ -
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
jobIDvariable 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
jobIDvariable 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:
- Sends
POST {{envURL}}data-orchestrator/v1/invokeusing a JSON input file - Extracts the returned
jobID - Polls
POST {{envURL}}data-orchestrator/v1/poll - Repeats polling until the job reaches
SUCCESS - 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.
- Sends a
multipart/form-datarequest - Uploads the specified file
- 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:
keyfilenameurlfor downloading the file
Notes for Command Line Usage
curl.exemust be available on the system (included with modern Windows versions)- Verify that
envURLinside the.batfiles matches your OLIVE environment - File upload examples require the referenced file path to exist