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

An OAuth client application registered in Oracle Identity Cloud Service (IDCS) or an OCI IAM identity domain is required to authenticate calls to Retail Home Platform Services.

For current guidance on whether to create an OAuth client application through Retail Home or directly in the OCI Console, see PALRT2931 - Retail Cloud Services: OAuth Client Application Guidance Related to OCI Identity Changes.

For instructions on creating an OAuth client application directly in the OCI Console, see My Oracle Support document KB911163, Procedure to Create an OCI Identity Domain Integrated Confidential Application for Oracle Retail API Access.

Configure the OAuth client application with the following scope required by Retail Home Platform Services:

rgbu:rh:services-RH-<ENV>

<ENV> is the Retail Home environment type and index, such as PRD1. This value can be identified from the Retail Home URL, which has the following format:

/rgbu-common-<customer>-<env>-rh/retailhome

For example, in the following URL, the environment is DEV99:

https://<base-url>/rgbu-common-rhdev-dev99-rh/retailhome

After creating the application, securely record the client ID and client secret. These credentials are required to obtain an OAuth access token for calls to Retail Home Platform Services.

Short-term Alternative: Oracle-managed Application

As a short-term alternative, customers can create an Oracle-managed OAuth client application through Retail Home. For more information about creating and managing OAuth client applications through Retail Home, see Chapter 6, OAuth Client Applications.

Calling Platform Services

Get OAuth Access Token

Calling Retail Home Platform Services requires an OAuth access token. Obtain the token from the IDCS or OCI IAM identity domain in which the OAuth client application is registered.

Use the OAuth token endpoint associated with that identity domain. For instructions on creating and configuring an OAuth client application directly in the OCI Console, see My Oracle Support document KB911163, Procedure to Create an OCI Identity Domain Integrated Confidential Application for Oracle Retail API Access.

Send an HTTP POST request to the token endpoint. Use basic authorization with the OAuth client ID as the username and the client secret as the password.

Set the following Content-Type header:

application/x-www-form-urlencoded

Use the following request payload:

grant_type=client_credentials&scope=<scope>

Replace <scope> with the scope configured for the OAuth client application, for example:

rgbu:rh:services-RH-<ENV>

The response is returned in JSON format. Copy the value of the access_token field and use it as the bearer token when calling Retail Home Platform Services.

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://<base-url>/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://<base-url>/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://<base-url>/p/ABC123ABC123ABC123ABC123ABC123/n/oraclegbudevcorp/b/cds_gbua_cndevcorp_rgbu_rgbu_q8qolpw40tamqx8npfp6_RGBU_DEV56_1/o/home/1000/example.pdf"
}