B Appendix: Using Retail Home Services to Retrieve Exported OAS Reports
OAS allows exporting reports to Object Storage in cloud environments. Retail Home and Platform Services can be used to download these exported reports by creating a PAR URL to access them.
Setting up the PAR
Creating the PAR requires making a REST call to Platform Services. This requires setting up an OAuth client for authentication.
Creating the OAuth Client
The OAuth client can be created using the Manage OAuth Clients screen in Retail Home.
Calling Platform Services deployed with Retail Home requires a scope of the form rgbu:rh:services-RH-<ENV>
. ENV
is the environment type and index of the Retail Home environment (for example, PRD1
). If you’re not sure, this value can be found in the Retail Home URL, which will be of the form /rgbu-common-<customer>-<env>-rh/retailhome
. (for example, in the URL https://home.retail.us-phoenix-1.ocs.oc-test.com/rgbu-common-rhdev-dev99-rh/retailhome
, the environment home is DEV99
)
Create a new OAuth client with the required scope and record the client ID and client secret returned by Retail Home. The name and description for the new client can be set to anything as long as the name isn’t already in use.
Calling Platform Services
Get OAuth Access Token
Calling Platform Services requires first getting the OAuth access token from IDCS. This requires making a POST call to IDCS at the following endpoint:
https://<idcs host>/oauth2/v1/token
The IDCS host can be found in the login page URL. For example, for https://idcs-ca69887b7ea4451ebdf967e2a383629e.identity.c9dev2.oc9qadev.com/ui/v1/sigsig
, the endpoint is https://idcs-ca69887b7ea4451ebdf967e2a383629e.identity.c9dev2.oc9qadev.com/oath2/v1/token
The call should use basic authorization with the client ID and client secret for your created OAuth client as the username and password. The payload of the request is as follows, substituting the same scope as in the previous step:
grant_type=client_credentials&scope=<scope>
Set the content-type header to application/x-www-form-urlencoded
.
The response will be in JSON format. Copy the value of the access_token
field for use in the next step.
Call the Platform Services Endpoint
To create the PAR, make a POST call to /RetailAppsPlatformServices/services/private/dis/createpar/{tenantId}
. You can get the full URL by looking up Retail Home’s Platform Service URL on the Application Navigator Config screen, and
the tenant ID can be found in the URL for BI Publisher.
Example
Retail Home has a Platform Service URL of https://home.retail.us-ashburn-1.ocs.oraclecloud.com/rgbu-common-rhdev-dev99-rh/RetailAppsPlatformServices
BI Publisher is located at https://rgbu.gbua.ocs.oc-test.com/fn9tojyo1js4rhhzwqx0/xmlpserver
.
The POST call will go to https://home.retail.us-ashburn-1.ocs.oraclecloud.com/rgbu-common-rhdev-dev99-rh/RetailAppsPlatformServices/
services/private/dis/createpar/fn9tojyo1js4rhhzwqx0
Set the following headers for the request:
-
Authorization: Bearer <access token>
-
Accept-Language: en-US
The request payload is a JSON object with the following fields:
Property | Type | Required | Description |
---|---|---|---|
disUrl |
String |
Y |
Host URL for BI Publisher |
name |
String |
Y |
Name for the PAR |
dateExpires |
String |
Y |
Expiration date for the PAR. Must be in the future. Uses the format |
objectName |
String |
Y |
Path to the object in Object Storage. Will be provided by customer. |
Example JSON
{
"disUrl": "https://rgbu.gbua.ocs.oc-test.com",
"name": "Example",
"dateExpires": "2025-01-31",
"objectName": "home/1000/example.pdf"
}
The disUrl
field can be taken from the BI Publisher URL. For example, https://rgbu.gbua.ocs.oc-test.com/fn9tojyo1js4rhhzwqx0/xmlpserver results in a disUrl
of https://rgbu.gbua.ocs.oc-test.com
.
The response from Platform Services will be a JSON message with a URL field. The returned URL can be used to download the report from Object Storage.
An example response:
{
"status": "Success",
"id": "ABC123ZMMMpnNSI8FcE13FqcN2e5gf6Wl4XvWXt5nVfWBoj24PNyZV3a2k/home/1000/example.pdf",
"url": "https://objectstorage.us-phoenix-1.oraclecloud.com/p/ABC123ABC123ABC123ABC123ABC123/n/oraclegbudevcorp/b/cds_gbua_cndevcorp_rgbu_rgbu_q8qolpw40tamqx8npfp6_RGBU_DEV56_1/o/home/1000/example.pdf"
}