Appendix: Using Retail Home Services to Retrieve Exported OAS Reports

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 `YYYY-MM-DD`
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"
}