Part 8 of 12 in the Oracle EPM Cloud REST API series.
This is the post where everything from earlier in the series comes together into something you can actually run. Launching a business rule through the API, instead of clicking Launch in the Rules panel, means submitting a job and reading back what happened.
Submit the job
You POST to the jobs resource for your application, specifying jobType: "Rules", the exact jobName as it is defined in Planning, and any runtime prompt values the rule needs:
curl -X POST \
"https://epm-xyz.epm.us-phoenix-1.ocs.oraclecloud.com/HyperionPlanning/rest/v3/applications/Vision/jobs" \
-H "Content-Type: application/json" \
-H "Authorization: Basic <base64 encoded credentials>" \
-d '{
"jobType": "Rules",
"jobName": "Operating Expense Adj Plan",
"parameters": {
"MyScenario1": "Current",
"MyVersion1": "BU Version_1",
"ToEntity": "CA",
"Rule_Level_Var": "AZ",
"planType": "Plan1"
}
}'
A couple of notes on that payload. jobType and jobName are both case sensitive, so the rule name has to match Calculation Manager exactly, capitalization included. The parameters object carries the rule's runtime prompts. Leave it out and Oracle falls back to whatever defaults are configured in Calculation Manager, which is fine for some rules and wrong for others, so being explicit here is usually the safer habit.
Read back the job ID
The response confirms the job was accepted and hands you an ID to track it by, along with an initial status:
{
"jobID": 145,
"jobName": "Operating Expense Adj Plan",
"status": 0,
"descriptiveStatus": "Completed",
"details": "Job submitted successfully"
}
The status field is an integer, not a simple true or false. Memorize the scale: negative one means still in progress, zero means success, one means error, two means a cancellation is pending, three means cancelled, and four means an invalid parameter was passed. For anything beyond a trivially fast rule, do not expect a zero right away. Most jobs come back as negative one first and need to be checked again a moment later, which is exactly the subject of the next post in this series.
Required access
Running rules through the API needs the same access you would need in the browser. A Service Administrator role covers everything. A Power User can launch specific rules too, as long as rule launch access has been granted for that rule.
Beyond business rules
The jobs resource is not limited to rules. The same POST, capture the ID, then check on it pattern works for importing data, refreshing a cube, exporting metadata, and dozens of other job types Oracle EPM Cloud supports. Rules just happen to be the most common starting point, since they map directly onto something every administrator already does by hand.
Submitting the job is only the first half of the story. The next post covers how to actually confirm it finished, and what to do with the response you get back.