Introduction

Oracle Analytics Publisher (formerly known as BI Publisher) on Oracle Analytics Cloud (OAC) runs on Oracle Cloud Infrastructure (OCI).

This article describes how to use the Oracle Analytics Publisher REST APIs to run or schedule Publisher reports on Oracle Analytics Cloud. Understand how to generate the OAuth token using the Resource Owner grant type or the Refresh Token grant type, and then use the OAuth tokens to run the Publisher REST API commands. Use the OAuth token generated in Oracle Identity Cloud Services (IDCS) or IAM Identity Domains to access the Publisher REST APIs.

See Unlocking Oracle Analytics Cloud with OAuth 2.0 to understand the grant types such as Resource Owner, Refresh Tokens, JWT Assertion, and Device Code.

Prerequisites

• You must have the BI Service Administrator role privileges to generate the OAuth token.
• You must have a native IDCS/IAM Identity Domain user name and password to generate an OAuth token using the Resource Owner grant type. You can’t use federated users.
• You must be a user (native or federated) in IDCS or IAM Identity Domain to generate an OAuth token using the Refresh Token grant type. You don’t need the user name and password.

Create a Confidential Application for OAuth Client

Follow the blog post to create a confidential application that uses Client Credentials as the grant type.

While following this article, in the current example consider the following steps.

1. Select Resource Owner and Refresh Token as the Allowed Grant Types.
2. Click Add Scope and select the Oracle Analytics Publisher application from the list of applications.
3. Copy the scope value for further usage in the REST API commands.
4. Don't grant any App Roles for the confidential application.

Client Application Attributes Required For Authentication

Client ID:  eea4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx33db

Client Secret:  6xxxxxxx6-0xx2-4xx9-axxb-0xxxxxxxxxxa

Scope:  https://<xxxxxxxxxxxxxxxxxxxx>.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all

IDCS or IAM Domain URL:  https://idcs-f5xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx03.identity.oraclecloud.com

Generate the base64 encoded clientID and clientSecret

echo -n "eea4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx33db:6xxxxxxx6-0xx2-4xx9-axxb-0xxxxxxxxxxa" | base64 -w 0

REST API Commands to Generate an OAuth Token Using the Resource Owner Grant Type

Generate the access token

curl --request POST "https://idcs-f5xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx03.identity.oraclecloud.com/oauth2/v1/token" --header "Authorization: Basic <base64 encoded ClientID:clientSecret>" --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=password' --data-urlencode "username=<BIServiceAdministrator_UserName>" --data-urlencode "password=<User_Password>" --data-urlencode "scope= https://<xxxxxxxxxxxxxxxxxxxx>.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all"

Capture the access token value from the output

{"access_token":"eyJ4NXQjUzI1NiI6IkttM1VBWEttaHpHa0pxeDFnQldrZ1RFOFVJU0VtYklEdVpJUGdYVVUtb1EiLCJ4NXQiOiJ1S0h3cXp6M1c2S3czcWU3NnE5UFdXbTRQS3ciLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0…………………………………... jtlr6Njab5i5qW1A","token_type":"Bearer","expires_in":100"}

REST API Commands to Generate an OAuth Token Using the Refresh Token Grant Type

There are multiple ways to get a Refresh Token. You can either use the user interface or REST APIs or the automation script to get the Refresh Token. This article uses the automation script.

Using the automation script to get the Refresh Token

If you want to generate the Refresh Token using the REST API commands but don’t want to store any BI Service Administrator user name and password, use the following script to interactively read the user name and password at the prompt without saving the values to any file and generate the Refresh Token. It needs the Resource Owner and Refresh Token grant types selected in the confidential application.

Download the Script →  getRefreshToken.sh

The Refresh Token Expiration value must exceed the frequency of the REST API script execution. For example, the Refresh Token Expiration is 86,400 seconds, equivalent to 24 hours. The automation scripts should be executed daily with an interval less than 24 hours so that the Refresh Token is valid for the subsequent script execution. The automation process renews the Refresh Token, uses the new Refresh Token while running the scripts, and saves the new Refresh Token in the refreshToken.txt file so that the new token is valid for the next 24 hours.

NOTE: Access Token Expiration is 100 seconds, which might be sufficient. If a long-running script fails due to the Access Token Expiration, increase the value accordingly. Even with a Confidential Application and its grant types, the token expiration values are from the Publisher Application in IDCS or IAM Domain.

REST API Commands to Get the Access Token Using the Refresh Token

Generate the Access Token

NOTE: This approach needs the Refresh Token grant type in the Confidential Application.

curl –location --request POST "https://idcs-f5xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx03.identity.oraclecloud.com/oauth2/v1/token" --header "Authorization: Basic <base64 encoded ClientID:clientSecret>" --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode "refresh_token=${REFRESH_TOKEN}" --data-urlencode "scope= https://<xxxxxxxxxxxxxxxxxxxx>.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all"

Capture the Access Token value from the output

{"access_token":"eyJ4NXQjUzI1NiI6IkttM1VBWEttaHpHa0pxeDFnQldrZ1RFOFVJU0VtYklEdVpJUGdYVVUtb1EiLCJ4NXQiOiJ1S0h3cXp6M1c2S3czcWU3NnE5UFdXbTRQS3ciLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0…………………………………... jtlr6Njab5i5qW1A","token_type":"Bearer","expires_in":100,"refresh_token":"AgAgNzRjNDQxOWIyZDkwNGY4MzlkMGE3YzBmMDJmZjk4……………………………………………………………………………………………………………………………..vy2w_41xmpg="}

Run a Publisher Report

When you send a request to Publisher to run a specific report, the request is synchronized, and the response contains the report output.

For example, if the Sample_Publisher_Report Publisher report is in the /Shared Folders/SAND_BOX Catalog folder, specify SAND_BOX%252fSample_Publisher_Report as the absolute path for the report. Use %252f for each / (slash) in the folder path after the first folder under Shared Folders.

REST API Command to run a Publisher report

curl -X POST -H "Authorization: Bearer eyJ4NXQjUzI1NiI6IkttM1VBWEttaHpHa0pxeDFnQldrZ1RFOFVJU0VtYklEdVpJUGdYVVUtb1EiLCJ4NXQiOiJ1S0h3cXp6M1c2S3czcWU3NnE5UFdXbTRQS3ciLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0………………………………………………………tlr6Njab5i5qW1A" -o SampleOAPReport.pdf -H "Content-Type:multipart/form-data" -v -F 'ReportRequest={"attributeFormat":"pdf"};type=application/json' https://<instancename>-<NameSpace>-<region>.analytics.ocp.oraclecloud.com/api/xmlpserver/services/rest/v1/reports/SAND_BOX%252fSample_Publisher_Report/run

For example, to download the SampleOAPReport.pdf file, use -o SampleOAPReport.pdf.

Schedule a Publisher Report

Schedule a job to run the report and provide the parameter values for the report.

Create a payload as a JSON file (report2schedule.json) with the required Publisher report path and format, and pass the JSON file name as the data file to the REST API command to schedule the report.

{
  "dataModelUrl":"/SAND_BOX/Sample_Report_DM.xdm",
  "saveOutputOption":"true",
  "saveDataOption":"true",
  "reportRequest":{
    "reportAbsolutePath":"/SAND_BOX/Sample_Publisher_Report.xdo",
    "attributeFormat":"pdf"
    }
}

REST API Command to schedule a Publisher report

curl -X PUT -H "Authorization: Bearer eyJ4NXQjUzI1NiI6IkttM1VBWEttaHpHa0pxeDFnQldrZ1RFOFVJU0VtYklEdVpJUGdYVVUtb1EiLCJ4NXQiOiJ1S0h3cXp6M1c2S3czcWU3NnE5UFdXbTRQS3ciLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0………………………………………………………tlr6Njab5i5qW1A" -H "Content-Type: application/json" -v -d @report2schedule.json https://<instancename>-<NameSpace>-<region>.analytics.ocp.oraclecloud.com/xmlpserver/services/rest/v1/jobs/scheduleJob

You can check the scheduled job in the Job History page.

Automation Script for Using the Resource Owner Grant Type

Download the Script →  runNscheduleReport_RO.sh

Automation Script for Using the Refresh Token Grant Type

Download the Script →  runNscheduleReport_RT.sh

Call to Action

You've learned how to generate the OAuth tokens, run the Publisher reports, and schedule Publisher reports using the Publisher REST APIs on Oracle Analytics Cloud. Try them out yourself.

To explore more features, see REST API for Oracle Business Intelligence Publisher and How to use REST API for Oracle BI Publisher to Schedule Jobs using the PUT method? (Doc ID 2740901.1).