Developer ToolsFree generatorPDF, Excel, Word exportOracle Hyperion / EssbaseAll Oracle Hyperion and Essbase tools

Essbase 21c REST API Request Generator (Jobs, Files, Applications)

This generator builds the REST calls most Essbase 21c automation needs: list applications and cubes, upload a data file, run a calc job, run a dataload job with a rules file and poll the job until it finishes. It outputs raw HTTP, a curl command and a Python script you can schedule.

Fill in

Essbase base URL

Application

Database (cube)

Calc script file

Data file

Rules file

Essbase user

Generated code

Download:

1. List applications and cubes

GET https://essbase.example.com:9001/essbase/rest/v1/applications?links=none
Authorization: Basic <base64 of svc_essbase_batch:password>
Accept: application/json

GET https://essbase.example.com:9001/essbase/rest/v1/applications/Sample/databases?links=none
Authorization: Basic <base64 of svc_essbase_batch:password>
Accept: application/json

2. Upload the data file to the cube directory

PUT https://essbase.example.com:9001/essbase/rest/v1/files/applications/Sample/Basic/Data_Basic.txt?overwrite=true
Authorization: Basic <base64 of svc_essbase_batch:password>
Content-Type: application/octet-stream

<file bytes>

3. Run a calc job

POST https://essbase.example.com:9001/essbase/rest/v1/jobs?links=none
Authorization: Basic <base64 of svc_essbase_batch:password>
Accept: application/json
Content-Type: application/json

{
  "application": "Sample",
  "db": "Basic",
  "jobtype": "calc",
  "parameters": { "script": "CalcAll.csc" }
}

4. Run a dataload job with a rules file

POST https://essbase.example.com:9001/essbase/rest/v1/jobs?links=none
Authorization: Basic <base64 of svc_essbase_batch:password>
Accept: application/json
Content-Type: application/json

{
  "application": "Sample",
  "db": "Basic",
  "jobtype": "dataload",
  "parameters": {
    "file": "Data_Basic.txt",
    "rule": "Data.rul",
    "abortOnError": "true"
  }
}

5. Poll the job (statusCode 100 in progress, 200 completed, 300 completed with warnings, 400 failed)

GET https://essbase.example.com:9001/essbase/rest/v1/jobs/<job_ID>?links=none
Authorization: Basic <base64 of svc_essbase_batch:password>
Accept: application/json

curl equivalent

curl -X POST "https://essbase.example.com:9001/essbase/rest/v1/jobs?links=none" \
  -u "svc_essbase_batch:$ESSBASE_PASSWORD" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"application":"Sample","db":"Basic","jobtype":"calc","parameters":{"script":"CalcAll.csc"}}'

Python (requests): run calc and wait

import os
import time
import requests

BASE = "https://essbase.example.com:9001/essbase/rest/v1"
AUTH = ("svc_essbase_batch", os.environ["ESSBASE_PASSWORD"])
HDR = {"Accept": "application/json", "Content-Type": "application/json"}

body = {
    "application": "Sample",
    "db": "Basic",
    "jobtype": "calc",
    "parameters": {"script": "CalcAll.csc"},
}
r = requests.post(BASE + "/jobs?links=none", json=body, auth=AUTH, headers=HDR, timeout=60)
r.raise_for_status()
job_id = r.json()["job_ID"]

while True:
    s = requests.get(BASE + "/jobs/" + str(job_id) + "?links=none", auth=AUTH, headers=HDR, timeout=60).json()
    if s["statusCode"] != 100:
        break
    time.sleep(5)

print(job_id, s["statusCode"], s["statusMessage"], s.get("jobOutputInfo"))
if s["statusCode"] == 400:
    raise SystemExit(1)

Paths and body parameters checked against the REST API for Oracle Essbase 21c: GET /applications, GET /applications/{applicationName}/databases, PUT /files/{path}, POST /jobs (calc uses parameters.script; dataload uses file, optional rule and abortOnError) and GET /jobs/{id} returning job_ID, statusCode and statusMessage. Port and context root depend on your install; Essbase on OCI and OAC use their own URLs and identity setup, so confirm the base URL and auth method with your administrator.

Moving MaxL jobs to Essbase 21c?

Send your current MaxL batch and we will map each step to the matching REST job call with error handling.

Optional. The tool and every export work without this. No spam.

Was this tool useful?

How to use it

Enter the base URL of your Essbase 21c server, the application and cube, the calc script, data file and rules file names and a batch user. Upload the calc script and rules file to the cube directory first (through the web interface Files page or the same PUT /files call). Then POST a job and read job_ID from the response. Poll GET /jobs/{id} until statusCode is no longer 100. A 200 means completed, 300 completed with warnings and 400 failed; for loads, warnings usually mean rejected records, so read the error file before calling the run clean.

Store the password in an environment variable or vault, never in the script.
Use a dedicated batch user with Database Update on the cube.
Add ?links=none to shrink responses when you do not need HATEOAS links.

Where this fits in Essbase versions

The /essbase/rest/v1 API arrived with the newer Essbase line (Essbase on OCI/OAC and independent Essbase 19c and 21c). Essbase 11.1.2.4 on-prem has no equivalent REST jobs API; automation there uses MaxL through essmsh, the Java API or the C API, and many shops keep their MaxL scripts after upgrading. In 21c, the calc job takes the script name in parameters.script and expects a .csc file in the cube directory. File paths outside the cube directory use a catalog prefix such as catalog/shared/file.txt. Dimension builds use jobtype dimbuild with file and rule parameters and Database Manager permission.

Worked example

With the defaults, the Python block posts a calc job for Sample.Basic with CalcAll.csc and prints the job ID, final status code, status message and jobOutputInfo, then exits with code 1 on failure so a scheduler like cron, Control-M or Windows Task Scheduler can alert on it. To chain a nightly cycle, run the upload, then the dataload job with abortOnError true, wait for 200, then the calc job. The same pattern works for a dimbuild job before the load. Because each step returns a job ID, you can log every run alongside the job history the Essbase web interface already keeps.

Gotchas

abortOnError is passed as a string "true" in the documented example. A 401 usually means the user is not provisioned for the application, not a wrong URL. Large uploads can time out through a reverse proxy; raise the proxy timeout or use the multipart file upload endpoints (create, upload part, commit). Essbase on OAC and OCI may sit behind identity domains that require OAuth tokens instead of basic auth. Job status values can arrive in different letter case between releases, so compare statusCode numbers, not message strings.

Frequently Asked Questions

How do I run an Essbase calc script with the REST API?

POST to /essbase/rest/v1/jobs with a JSON body containing application, db, jobtype "calc" and parameters {"script": "CalcAll.csc"}. The script must already be in the cube directory. The response contains job_ID, which you poll with GET /essbase/rest/v1/jobs/{id} until statusCode is 200, 300 or 400.

Does Essbase 11.1.2.4 have a REST API?

Not the 21c-style jobs API. On 11.1.2.4, automation uses MaxL scripts run with essmsh, the Java API, or the C API. Provider Services exposes Java API access for Smart View and custom clients. If you plan to migrate, port MaxL jobs to REST calls step by step and keep the same job names.

What do Essbase job status codes mean?

In the 21c REST API, statusCode 100 is IN_PROGRESS, 200 is COMPLETED, 300 is COMPLETED_WITH_WARNINGS and 400 is FAILED. For data loads, 300 often means some records were rejected; check jobOutputInfo and the error file in the cube directory. Compare the numeric code in your scripts.

Which permission does a REST data load need?

Calc and dataload jobs need at least Database Update on the cube, plus access to the calc script for calc jobs. Dimension builds need Database Manager. Use a dedicated service user with exactly those roles so a leaked credential cannot change security or delete applications.

If you want an on-prem assistant that can explain Essbase job failures and kick off approved jobs through this API, we can set that up on your servers.

Talk to an Expert Explore More Free Tools