1 Administrative Tasks
This document captures key information needed to administer Retail Insights, such as user and group details in IDCS or OCI IAM. For information regarding standard end user activities like creating and viewing reports, please see the Oracle Retail Insights User Guide.
Retail Analytics and Planning
As part of the Retail Analytics and Planning cloud services, Retail Insights shares many common components, tools, and processes with other applications like AI Foundation Cloud Services. The Retail Analytics and Planning Administration Guide covers these shared areas in greater detail as they apply to all solutions. If you are implementing the Retail Insights or AI Foundation Cloud Services, begin with those RAP level documents and return here only as needed for Retail Insights-specific content.
Retail Insights Cloud Services Enterprise Roles
Retail Insights Cloud Service leverages Oracle Cloud Infrastructure Identity and Access Management (OCI IAM), which is Oracle's cloud-native security and identity platform. For information on Oracle Retail’s authentication policies and setup information, refer to the Oracle Retail Identity Management for OCI IAM Startup Guide.
Unlike previous-generation architecture, the RI, OAS, and DV group names are prefixed with a unique tenant ID that is specific to your cloud service. This is necessary because the same Oracle Analytics platform can be shared across multiple Oracle Retail solutions now, and you may also have multiple OAS instances on one IAM (such as Dev, Stage, and Prod environments), so the groups must be unique to each environment. The tenant ID is a long string of characters like this:
bd835fj48ffj3lwisda4h
The role names may look like this:
bd835fj48ffj3lwisda4h-BIConsumer_JOB
The following RI application roles and OCI IAM groups are available:
Table 1-1 Retail Insights Cloud Services Default Enterprise Roles
Application Module | Enterprise Roles (OCI IAM Groups) | Corresponding Application Roles |
---|---|---|
RI |
<tenant ID>-AltHierarchyInsights_JOB |
AltHierarchyInsights |
RI |
<tenant ID>-ConsumerInsights_JOB |
ConsumerInsights |
RI |
<tenant ID>-CustomerInsights_JOB |
CustomerInsights |
RI |
<tenant ID>-CustomerDetailInsights_JOB |
CustomerDetailInsights |
RI |
<tenant ID>-CustomerLoyaltyInsights_JOB |
CustomerLoyaltyInsights |
RI |
<tenant ID>-CustomerOrderInsights_JOB |
CustomerOrderInsights |
RI |
<tenant ID>-CustomerSegmentInsights_JOB |
CustomerSegmentInsights |
RI |
<tenant ID>-EmployeeInsights_JOB |
EmployeeInsights |
RI |
<tenant ID>-Flex1Insights_JOB |
Flex1Insights |
RI |
<tenant ID>-Flex2Insights_JOB |
Flex2Insights |
RI |
<tenant ID>-Flex3Insights_JOB |
Flex3Insights |
RI |
<tenant ID>-Flex4Insights_JOB |
Flex4Insights |
RI |
<tenant ID>-FranchiseInsights_JOB |
FranchiseInsights |
RI |
<tenant ID>-InventoryInsights_JOB |
InventoryInsights |
RI |
<tenant ID>-PlanningInsights_JOB |
PlanningInsights |
RI |
<tenant ID>-PromotionInsights_JOB |
PromotionInsights |
RI |
<tenant ID>-PurchaseOrderInsights_JOB |
PurchaseOrderInsights |
RI |
<tenant ID>-SalesInsights_JOB |
SalesInsights |
RI |
<tenant ID>-SupplierInsights_JOB |
SupplierInsights |
RI |
<tenant ID>-RetailAnalysts_JOB |
RetailAnalyst |
RI |
<tenant ID>-TenderInsights_JOB |
TenderInsights |
RI |
PLATFORM_SERVICES_ADMINISTRATOR_ABSTRACT |
Assign to all users accessing Retail Home to see tiles or links to RI |
POM |
PROCESS_SERVICE_ADMIN_JOB |
POM Business Role |
POM |
BATCH_SCHEDULE_ADMINISTRATOR_JOB |
POM Batch Admin Role |
RH |
PLATFORM_SERVICES_ADMINISTRATOR |
Retail Home/BI Integration Admin (Integrate RI with RH APIs) |
IW |
DATA_SCIENCE_ADMINISTRATOR_JOB |
Administer the Innovation Workbench/APEX workspace |
IW |
DATA_SCIENCE_OLDS_ADMIN_JOB |
Administer the Innovation Workbench Python notebooks |
Using a combination of the RI groups above will grant access to sets of metrics and attributes in RI in an additive fashion. One exception is the CustomerDetailInsights role, which is a special role intended to grant access to detailed customer information, such as their name and phone number. This role must be used in combination with the CustomerInsights role to get access to these attributes, and can be limited to a subset of RI users. Without the additional role, the CustomerInsights role only grants access to basic non-identifying customer information such as the customer ID and generic user-defined attributes.
The other groups listed are commonly used for Retail Insights customer administration users (depending on the other applications you administer). The Retail Home groups should be granted to any user that will be maintaining Retail Home dashboards, notifications, label customizations, or cross-application task menus. The POM groups should be granted to any user involved in monitoring or modifying the batch schedules for nightly and on-demand processes. The Innovation Workbench roles must be given to any user responsible for controlling access to APEX, including for custom apps and integrations.
Additionally, the following Oracle Analytics groups are used in combination with the RI application groups above. Assign a combination of these roles depending on the level of access to OAS functionality required for each user. For example, a local systems administrator could be granted all of the roles in this table, and the permissions will be additive.
Table 1-2 Retail Insights Cloud Services OAS Roles
Application Module | Enterprise Roles/IDCS or OCI IAM Groups | Permissions Level |
---|---|---|
ORMI/ORCI |
<tenant ID>-BIConsumer_JOB |
Ability to view content created by others. Cannot create new content. |
ORMI/ORCI |
<tenant ID>-BIAuthors_JOB |
Ability to create and share new content, including analyses, dashboards, data visualizer projects, and XLS uploads to DV. |
ORMI/ORCI |
<tenant ID>-RIApplicationAdministrators_JOB |
Customer administrator responsible for creating and maintaining Agents, BI Publisher jobs, and Catalog permissions. |
Data Visualization |
<tenant ID>-RetailVisualAnalyzer_JOB |
Grants direct access to the Data Visualization (DV) module in OAS, without granting access to any functional modules in RI itself. |
Assign the above roles to the user following the steps mentioned in the previous section as per your requirement. The table below describes some common user types and the associated roles they could be granted for RI access.
Table 1-3 Retail Insights Cloud Services User Examples
Example User | Enterprise Roles/IDCS or OCI IAM Groups | Description |
---|---|---|
RI Administrator Super-User |
bd835fj48ffj3lwisda4h-BIConsumer_JOB bd835fj48ffj3lwisda4h-BIAuthors_JOB bd835fj48ffj3lwisda4h-RIApplicationAdministrator_JOB bd835fj48ffj3lwisda4h-RetailAnalysts_JOB |
This user has access to all functional areas in RI and will have the ability to manage Agents and modify and delete objects in the /Shared Folders/Custom/ space in the catalog. |
Merchandisers |
bd835fj48ffj3lwisda4h-BIConsumer_JOB bd835fj48ffj3lwisda4h-BIAuthors_JOB bd835fj48ffj3lwisda4h-SalesInsights_JOB bd835fj48ffj3lwisda4h-InventoryInsights_JOB bd835fj48ffj3lwisda4h-SupplierInsights_JOB |
This user has access to the Sales, Inventory, and Supplier areas in RI, which are typically required for merchandisers and buying teams. |
Store Managers |
bd835fj48ffj3lwisda4h-BIConsumer_JOB bd835fj48ffj3lwisda4h-RetailAnalysts_JOB |
This user has read-only access to RI, meaning they can run any report shared with them but cannot create content themselves. |
Note:
For additional information, see Appendix: Roles and Permission Grants.
Nightly Batch File Uploads
The following is the SFTP file upload process for Retail Insights in our 1st Generation architecture. If you using our 2nd Generation architecture, then you will not use SFTP, all files are uploaded to Object Storage. Refer to the Retail Analytics and Planning Administration Guide for more information.
The Private/Public Keys must be generated and the Public Key must be associated with your SFTP Account for the file uploads. The Adding Authorized Keys section describes the step-by-step method to generate the Keys (2048 bit RSA Keys).
Adding Authorized Keys
The following is the process to generate a 2048 bit RSA key and add the same to the SFTP server. This is done with the help of WinSCP tool on Windows. However the same can be done using ssh-keygen on Linux as well.
-
Launch WinSCP and select Tools -> Run PuttyGen.
-
Select "SSH-2 RSA" for the type of key to generate and enter "2048" for the number of bits in a generated key field and click Generate.
Figure 1-1 Key Generator
-
Move the mouse over the blank space in the window until the key is generated.
Figure 1-2 Key Generator Progress
-
Once the key is generated, click the Save public key button to save the public key to a file.
-
Click the Save private key button to save the Private key to a file. Confirm to save it with/without a passphrase.
-
Open an SR with Oracle Support, to associate the Public half of the Key with your SFTP account (attach the Key with the SR).
Steps – Login to WinSCP
The Upload steps uses the private key generated in the earlier section.
-
Launch WinSCP and connect to <SFTP Server> using port 22.
-
Enter the username and click Advanced.
-
Click Authentication.
-
In the Private Key File field, click the Browse button and select the private key created in the earlier section.
Figure 1-3 Advanced Site Settings Dialog
-
After loading the private key file, click OK.
Figure 1-4 Private Key File Loaded
-
Click Login. The window does not prompt for a password and logs into the SFTP server. Provide a passphrase if one has been set up.
Steps to Upload the Batch File
Login to the WinSCP by Following the Steps – Login to WinSCP section.
-
Transfer all data files to the directory /<SFTP User>.
-
Create a directory called COMMAND under /<SFTP User>if it does not already exist.
-
Change to the /<SFTP User>/COMMAND directory.
-
Transfer an empty file called COMPLETE.
Export File Downloads
Login to the WinSCP by following the Steps – Login to WinSCP section. The following is the download file process.
-
Change directory to /<SFTP User>/EXPORT.
-
Download all data files.
Creating Exports Using BI Publisher
In our 1st Generation architecture, RI application administrators may take advantage of the BI Publisher module in OAS to generate data files and reports on the SFTP server. Such files would be made available in the EXPORT directory as described above. If you are using Object Storage in the 2nd Generation architecture, this feature is not currently available.
The steps to instruct BI Publisher to send a file to SFTP are as follows:
-
Create a Data Model in OAS and setup the desired queries and datasets that will feed your export file.
Figure 1-5 SampleExtract_DM
-
Select the Bursting option from the list of properties in the left pane of the Data Model, and add a new bursting query.
Figure 1-6 Bursting Option
-
Select SQL Query as the Type, and Oracle BI EE as the Data Source.
-
Select the bursting object from the left pane to add a query to it. Below is a sample query which is used to create a CSV file:
select 0 as "KEY", 'SampleExtract_Rep' TEMPLATE, 'en-US' LOCALE, 'CSV' OUTPUT_FORMAT, 'FILE' DEL_CHANNEL, VALUEOF("SFTP_PATH") PARAMETER1, 'SampleExtract.csv' PARAMETER2 from "Retail Insights As-Is"
Figure 1-7 Bursting Query
-
Continue to define the rest of the BI Publisher objects (Reports and Jobs) following standard OAS procedure. When a Report Job is executed for this Data Model, it will use the values in the bursting query to create the file and write it to the export directory on the SFTP server.
For more information on Bursting queries, refer to the Oracle Fusion Middleware Data Modeling Guide for Oracle Business Intelligence Publisher:
https://docs.oracle.com/middleware/12213/bip/BIPDM/toc.htm
Resource Bundles
All Oracle Retail applications come packaged with resource bundles, files that contain text resources. These text resources appear throughout the Oracle Retail application as instructions, messages, labels, errors, virtually any text that appears in the application comes from a resource bundle.
Many Oracle Retail applications support the ability for retailers to customize the text that appears in the Oracle Retail application to better match that retailer's business language. The capability to change the text for a resource is provided through the Resource Bundles area of Retail Home. Retailers can customize text resources for any Oracle Retail supported language.
Resources and Customizations Explained
All text resources in the Oracle Retail application have the following values:
-
Base Application Code - This value identifies the Oracle Retail application that owns this text resource.
-
Language - This value identifies the language of the text resource.
-
Bundle - This value identifies the bundle file where this text resource resides.
-
Resource - This value is the unique name that can be used to get the text for this resource.
-
Base Text - This value is the text provided by the Oracle Retail application. This is the text that will appear in the application by default.
Every text resource in Oracle Retail applications is uniquely identified by the combination of Application Code, Language, Bundle, and Resource.
A resource customization is a change that a retailer made to the text of a resource. In addition to the values above, customizations also have the following values:
-
Current Text - This is the text that will actually appear in the Oracle Retail application. If a retailer has provided custom text for the resource, then this value will display the retailer's custom text. Otherwise, it will display the base text provided by the Oracle Retail application.
Task Flows
The Resource Bundles area of Retail Home consists of the following task flows:
-
Resource Text Strings
-
Imports Management
Resource Text Strings
From the Retail Home lower-left hand Settings menu, the user can access the Resource Bundles link. The Resource Text Strings screen provides the capability to customize the resources present in the resource bundles in an application. The user can search the resources in the application using the Bundle, Language, Resource, Contains Custom Text, or Text fields.
Figure 1-8 Resource Text Strings Screen
![Resource Text Strings Resource Text Strings](img/resource_textstrings.png)
The results table in the Resource Text Strings screen will display the Resource, Base Text, Current Text, Contains Custom Text, Updated Date, and Updated By columns for the resources matching the entered search criteria. If there is a custom value present for a resource, it will be displayed in the Text column along with the date and the user who customized that entry. The Contains Custom Text column will display Yes if a custom value is present for a resource. If there is no custom value present for a resource, the Text column will display the base text and the Updated Date and Updated By columns will be displayed empty. The Contains Custom Text column will display No in this scenario. The user can view, add, edit, or remove custom text for a resource using this screen.
The user can also export the results table to an Excel CSV file using this screen. The export action allow the user to modify custom text for many resources at one time, and upload all the custom values in a single action in Imports Management.
Figure 1-9 Edit or Remove Custom Text
![Edit or Remove Custom Text Edit or Remove Custom Text](img/editremove_customtext.png)
Edit
The user can add or edit the custom text for a resource using the Edit menu item or the pencil icon. If no custom text is present for a resource, a new custom text will be added. If a custom text is already present for a resource, it will be modified. The Updated Date and Updated By columns will be changed to reflect the addition or modification. The Edit option opens up a popup showing the resource, its base text and editable custom text. Only one record can be edited at a time in a popup. If more than one record or no record is selected, a warning is displayed to the user. The Edit popup can also be opened by double clicking a record on the results table.
Figure 1-10 Edit Resource Text Screen
![Edit Resource Text Screen Edit Resource Text Screen](img/editresource_text.png)
Remove Customization
The user can remove the custom text for one, many or all the selected resources using the Remove Customization menu item or the cross icon. The user can select a single or multiple records and remove custom values for the records. The Remove Customization option will give a confirmation warning message before the custom text is removed for the selected records. The base text is not impacted by the Remove Customization operation.
Figure 1-11 Delete Custom Text Confirmation Pop-up
![Delete Custom Text Confirmation Dialog Delete Custom Text Confirmation Dialog](img/customtext_delete.png)
Export to Excel
The user can export the details of the resources from the results table to an Excel CSV file. When the user selects the Export to Excel action, the browser will perform its download behavior. Depending on the user's browser preferences, the browser may prompt the user asking whether the exported file should be opened or saved, what program should be used to open the file, or where on the user's computer the file should be saved. Exporting a large number of strings may take some time to complete, during which time the browser may remain in an active/processing state.
Importing Customizations from a CSV File
The user can change the values in the Text column of an exported CSV, and then import the CSV file from the Imports Management screen. When the user does this, the values of the Text column are imported into the custom text of each newly customized resource. The user can customize multiple rows with a single action by importing a file which contains multiple customized rows. Importing a file that has not been modified will do nothing, since the text for each resource is already exactly the same in Retail Home the Oracle Retail application.
The imported file must meet the following assumptions for the import to succeed:
-
The imported file must be a well-formed CSV file. The user can use any compatible program to edit the exported CSV file, as long as the program is able to read the CSV file and save it again in CSV format.
-
The user should only edit values in the Text column. If the user edits any of the values in the Base Application Code, Language, Bundle, or Resource columns, the import may fail, or invalid customizations may be created.
-
The user can only add or edit customizations in the import. The user cannot remove customizations using import. Deleting the contents of the Text field or copying the Source Text into the Text field will cause the row to be ignored.
-
The size of the imported file is limited to 2000 KB. Users will not be allowed to upload a file larger than this.
From the Import Management screen, select the relevant application code and click the Create action. When the user selects the Create file action, a popup opens prompting the user to select a file to import.
Figure 1-12 Import CSV File Pop-up
![Import CSV File Dialog Import CSV File Dialog](img/import_csv.png)
It is possible that, after a user exports resources to a CSV file, but before the user imports the file into Retail Home, another user may go to Retail Home and customize one or more of the exported resources. In this case, the values of resources in Retail Home would be newer than the values in the exported file. In order to ensure that an import does not inadvertently overwrite these values, the import action will skip resources that have been recently updated in Retail Home, and notify the user. The user can tell the import to instead use the values from the imported file by selecting the "Overwrite recently updated resources" checkbox on the import pop-up.
Data Visualization Usage
All implementations of AI Foundation and Retail Insights include Oracle Data Visualization (DV) as a tool for custom analytics and reporting. Administrators should be aware of how DV is maintained as part of your Oracle Cloud environments so that you can manage user-created content and access permissions in the tool.
Accessing the Application
The URL to access the DV application is below, where xxx and yyy are the specific identifiers for your environment.
https://xxx-yyy-rsi-ris.oracleindustry.com/dv/?pageid=home
Permission to access DV can be granted through IDCS or OCI IAM using the group DVContentAuthor. DV access is also granted automatically if you have certain Retail Insights groups assigned, such as BIAuthors_JOB or RIApplicationAdministrator_JOB.
Managing User Content
User-created content comes in several forms and each type of content is managed separately, as defined below.
Table 1-4 DV User Content
Object Type | Usage |
---|---|
Projects |
DV reports and analyses are saved as Project files in the Oracle Analytics Catalog. In Oracle Retail cloud solutions, you may only use two assigned folders in the catalog: /My Folders/ and /Shared Folders/Custom/. You must not save or modify projects in any other location, as these two folders are the only ones designated for backup between upgrades/patches. Projects have their own permissions assigned and are not granted to anyone but the owner by default. The owner must grant the object to administrators if you want them to be centrally managed. |
Datasets |
Users can create datasets by uploading Excel spreadsheets or by querying pre-defined database connections. Datasets have their own permissions assigned and are not granted to anyone but the owner by default. The owner must grant the object to administrators if you want them to be centrally managed. |
Connections |
Database connections are managed by Oracle at this time, end users are not expected to create or modify these objects. |
Data Flows |
Data flows are used to combine multiple datasets or perform complex transformations and data mining algorithms. Data flows cannot be seen or administered by anyone but the object owner. |
Jobs and Schedules |
Data flows are executed using Jobs, which can also be scheduled to run periodically. Only the data flow owner can modify jobs and the associated schedules, even though the jobs are visible to other users. |