1. Configuration Guide
  2. Configuration

1 Configuration

This guide addresses the configuration of the RPASCE platform.

Overview

This guide will help you understand what is involved in defining a custom configuration on the Retail Predictive Application Server Cloud Edition (RPASCE) platform. By understanding the key activities, you can gain a better understanding of how to plan your implementation and have a starting point for stepping into the vast amount of material available for learning about an RPASCE-based application implementation.

Environment Access

The Oracle Retail Analytics and Planning Service Administrator Action List documents the first critical steps and the timeline for accessing the cloud service environment once the environment access emails are received.

The Service Administrator Action List describes how to set up additional logins for you, the System Integrator (SI), and any other immediate system administration users. Since at this point in the process there is no application setup, you must log into the application Bootstrap domain.

Starter Kit

The Oracle Retail Merchandise Financial Planning Cloud Service Starter Kit Guide is part of the Merchandise Financial Planning Cloud Service documentation set. It documents the steps you must follow in order to install the starter kit. This includes the steps for installing and launching the RPASCE Configuration Tools. You use these tools to define the changes to the base application or to migrate your existing RPAS configuration to the Cloud Edition.

At this point in the process, you may also build a sample domain for verifying that the accurate paths are defined.

Note:

If you are migrating an existing configuration from RPAS to RPASCE, refer to the Oracle Retail Predictive Application Server RPAS to RPASCE Domain Migration Reference Paper found in My Oracle Support (Doc ID: 2492295.1).

Configuration Tools

The Oracle Retail Predictive Application Server Cloud Edition Configuration Tools User Guide is part of the RPASCE documentation set. This extensive guide provides detailed technical information and procedures about all aspects of the configuration.

Initially, you follow the steps to open an existing project. When opening a project, you use the sample configuration provided in the starter kit.

An RPASCE configuration consists of the following key components:

  • Hierarchies: define the possible dimensions of the multi-dimensional cube.

  • Measures: a data point that lies at the intersection of one or more hierarchies.

  • Rules/Rule Sets: define the calculation equation for a measure or set of interrelated measures.

  • Workbook templates: define the workspace for a particular end-user task. A workbook contains a collection of worksheets.

  • Worksheets: a logical collection of measures for the user to review or modify to accomplish a planning task.

  • Taskflow: defines the tasks visible to the user and the associated workbook template.

  • Data Interface: defines the interface data and base intersections of the loaded data.

Measure Naming Conventions

The Measure Manager is used to follow naming conventions. Measure components such as plan version and role are defined. These help you to create groups of measures. Configuration Tools is used to create a matrix of measures using the Role, Version, Metrics, and UOM. Only the measures you select to realize are kept.

Rule Groups and Rules Sets

Each workbook requires a rule set that contains Rule Groups for Load, Calculate, Commit, and Refresh. These rule groups define the calculations that occur when the user performs the related action of loading and building a workspace, re-calculating after edits, and so on.

Here are some basic tips:

  • To load or refresh a measure from the domain, use the .master extension: measure = measure.master.

  • When committing, this is reversed measure.master = measure.

  • Consider how elapsed periods must be treated; typically, they are ignored.

Plug-in Options

Many GA planning applications support pre-defined configuration options using plug-in automation for including or excluding configuration options, such as Wholesale-Franchise or changing the load intersection of actuals. The sample configuration in the Starter Kit includes all the solutions and all plug-in options enabled. If you want to start your configuration for a specific plug-in option, instructions are provided in the Oracle Retail Merchandise Financial Planning Cloud Service Starter Kit Guide appendix “Generating the Configuration for Plug-in Options.”

Batch Control Files

Batch processes can involve loading hierarchies, loading measure data, running batch calculations, reporting plan data from a solution, and so on. All of these activities must be run in a particular sequence. In order for you to define the sequence of activities, RPASCE leverages a framework of batch control files that are simple text files. Within a batch control file, you define the pre-configured tasks to execute. RPASCE Online Administration Tools (OAT) capabilities are then used to schedule and provide parameterized inputs to execute batch activities using the control files.

The following list provides some example batch control files and the purpose for each file. For more details about the structure of the control files and the other control files that are available, see the Oracle Retail Merchandise Financial Planning Cloud Service Implementation Guide.

Table 1-1 Example Batch Control Files

File Name Description

batch_calc_list.txt

Defines the different mace expressions or rule groups to run in a particular order.

batch_loadmeas_list.txt

Defines the different sets or groups of measures that must be loaded together.

batch_exportmeas_list.txt

Defines the different sets of exports, with the file names and list of measures to be exported for each set.

batch_exec_list.txt

Defines a typical daily or weekly batch process, which calls the predefined sets in other control files in a particular order.

batch_oat_list.txt

Defines what batch calc, batch exec, batch load, and batch export tasks are visible in the Online Administration Tools, with user-understandable labels for those tasks.

Validating the Configuration

RPASCE provides tools to help with the configuration process. In addition to a detailed rules function reference guide in the appendix of the Oracle Retail Predictive Application Server Cloud Edition Configuration Tools User Guide, there are also rule writing tips to follow. The Configuration Tools provide the Rule Group Simulator and Comprehensive Workbook Validation is available to help you validate the configuration you have modified.

Note:

The validation tools are an aid. The only way to fully ensure the validity of the configuration is to run it in a real domain.

Dashboard Configuration

The dashboard is backed by a workbook as well as a view configuration file specified in the format of JavaScript Object Notation (JSON). By creating multiple dashboard profiles, you can have multiple dashboard views. Dashboard types are either a standard pre-season or in-season dashboard view or an exception dashboard. An exception dashboard is based on alerts and is the foundation of exception-planning. The Oracle Retail Predictive Application Server Cloud Edition Configuration Tools User Guide explains the relationship between the workbook and JSON file as well as how to define both standard and exception dashboard profiles.

Help File Configuration

Helping the planner to learn and follow the business process is made easier by contextual help. This help is readily available and specific to what you are working on. With contextual help you specify the URL link to information or videos. The context of the information can be generic or as specific as the workspace view. The links you see can change based on your view. Information on the configuration of in-context help is available in the Oracle Retail Predictive Application Server Cloud Edition Implementation Guide.

Customers can use the RPASCE Virtual Machine setup process specified in the Starter Kit to set up an RPASCE environment which sets it up with the UI to validate their configuration. For more information about Virtual Machine setup, see the Oracle Retail Merchandise Financial Planning Cloud Service Starter Kit Guide. Once it is set up, customers can upload their configuration and input files and batch control files to validate their domain.

Interfaces Configuration

Customers within Retail Analytics and Planning (RAP) can use RAP integration to directly share data within the applications in RAP. Planning Data Schema (PDS), which hosts the planning solutions, is also part of RAP and can also readily get foundation data by configuring interfaces to pull the data and schedule to run in the batches. The customer needs to configure interface.cfg which is a free-form text file containing the mapping configured facts in their configuration and available data in RAP integration. For more details about configuring interface.cfg to get data using RAP integration, see the Oracle Retail Predictive Application Server Cloud Edition Implementation Guide.

Testing the Configuration

Testing the configuration before uploading it to the stage environment validates the configuration, the domain build, and the batch script. The user interface can only be validated on the server.

Whether you create your own files or modify the starter files provided, the batch control files must be set up to run the batch. See the Batch Administration chapter in the Oracle Retail Predictive Application Server Cloud Edition Administration Guide to understand the framework for defining and executing batch tasks such as loading a measure set or executing rule calculations in batch. Use the Starter Kit Guide to follow the steps to build a domain in your local Windows environment.

The customer can use the RPASCE Virtual Machine setup process specified in the Starter Kit Guide to set up an RPASCE environment which sets it up with the UI to validate their configuration. For more information about Virtual Machine setup, see the Oracle Retail Merchandise Financial Planning Cloud Service Starter Kit Guide. Once it is set up, the customer can upload their configuration, input files, and batch control files to validate their domain.

Object Storage

Object Storage is used for all file transfer uploads and downloads. Each customer will be provisioned with Object Storage to upload/download files into the cloud service provisioned solution.

The configuration is uploaded to Object Storage to build the domain. For the building of the domain, different sub-paths are used for config, batch_control, and input. For details about how to upload files to Object Storage, see the Object Storage section of the Oracle Retail Predictive Application Server Cloud Edition Implementation Guide.

Building the Domain

Your newly provisioned cloud service is initially set up with a bootstrap configuration that allows you, the implementer, to access the Online Administration Tools (OAT) interface in order to build the application domain. The bootstrap OAT configuration only has tasks required to construct a domain.

In the bootstrap environment:

  1. Navigate to Administration in the tasks panel.

  2. Select Online Admin Tools.

  3. Submit a new admin task.

  4. Select Build Application.

The wizard walks you through selecting the required parameters to supply. The description of these parameters can be found in the Bootstrap Environment section of the Oracle Retail Predictive Application Server Cloud Edition Implementation Guide.

In order to complete the domain creation, a Batch Group is executed that defines the post-build steps to load data and run batch scripts. You can use and modify the post-build steps provided in the sample configuration or create your own steps. 

Batch_exec_list.txt:
# Post-domain-build tasks
postbuild | measload | load_all
postbuild | measload | load_tran
postbuild | calc     | calc_init

batch_loadmeas_list.txt:
# Load All Measures during Domain build
load_all | H | nsls.csv.ovr
load_all | H | rcpt.csv.ovr
load_all | H | rtn.csv.ovr
...

batch_calc_list.txt

# Calc Set for Initial Set Up
calc_init | G | group | Batch_GB
calc_init | L | group | Batch_AggW
...

Complete the domain build steps as they are outlined in the Bootstrap Environment section of the Oracle Retail Predictive Application Server Cloud Edition Implementation Guide.

Scheduling Batch

Daily or weekly batch scheduling is set up through Online Administration Tools (OAT). As noted earlier in this document, the control file batch_exec_list.txt lists the batch tasks and the sequential steps associated with a task. The tasks within this control file are used to schedule a typical daily or weekly batch.

To set up the batch:

  1. Navigate to the Administration task.

  2. Click Online Admin Tools.

  3. Click Submit a New Admin Task.

  4. Select the radio button for Configured Batch Tasks.

  5. Click Run Batch Task Group.

From here you select from the available batch tasks. For more information on the batch tasks provided in the sample configuration, see the Run Batch Task Group section in the Oracle Retail Merchandise Financial Planning Cloud Service Administration Guide.

The wizard walks you through selecting the schedule frequency, start date, and reoccurrence.

Batch also can be scheduled using JOS/POM which in turn can trigger the pre-configured batch tasks in the batch_exec_list.txt batch control file. For more details about MFP Job Flow in JOS/POM and also about how to configure it, see the Oracle Retail Merchandise Financial Planning Cloud Service Implementation Guide.

Data Conversion

Data conversion involves moving historical actuals, hierarchies, and current plan data from the current system of record into the planning application. It is typically one of the most complex tasks in an implementation. Hierarchies are required for building the domain. However, actuals are typically loaded at the same time in the post-build process. In Retail Analytics and Planning (RAP) integration, the customer can use a single point of integration of all applications within RAP. Planning also can get data by configuring interfaces within it. For more details about RAP integration, see the Oracle Retail Merchandise Financial Planning Cloud Service Implementation Guide.

The sample configuration provided in the starter kit matches the Generally Available (GA) template application. The Implementation Guide for the GA template application can be used as a starting point for understanding the integration APIs. By comparing this information to the modification designs that should be available for the implementation, you can identify what modifications or new loads are required.

Special consideration for data conversions include:

  • Beginning of Season (BOS). Many of the planning applications calculate End-of-Period (EOP) inventory and carry that forward to the start of the next period as Beginning-Of-Period (BOP) inventory. At the start of the calendar, there is no EOP to carry forward. The BOS value is used for this purpose.

Loading plan data from legacy systems can be performed with the domain post-build process by modifying the batch control files or separately using the OAT system administration task, Load Measure.

Administrative Setup

The administrative setup involves defining users, their roles, and the associated permissions.

The user setup process begins in Oracle Cloud Infrastructure Identity and Access Management (OCI IAM). The Administration Guide for the GA template application provides step-by-step instructions for navigating OCI IAM. Instructions are also included for the bulk upload of users and user roles.

Users must also be given application privileges. Application privileges are granted by first adding the user to the application. This process is defined in the User Administration chapter of the Oracle Retail Predictive Application Server Cloud Edition Administration Guide.

A user is assigned a user role. User roles are a convenient way to group users who perform similar job functions and are granted the same application permissions. User role permissions can be set for individual positions, such as granting access to specific departments or classes, and workbooks. Individual users can also be granted or denied access to positions and workbooks. In addition, measure access can be overridden for users to make them read-only or deny access completely. The Security Administration Workbook section of the Oracle Retail Predictive Application Server Cloud Edition Administration Guide provides a detailed explanation of how these permissions interact and how to use the Security Administration Workbook to grant or deny permissions.

Finally, included in security administration are settings for user workbook limits and session limits. Workbook limits are a helpful tool to limit space consumption by any single user. Domain session and concurrent user session limits can be helpful to ensure that users can perform their tasks within a reasonable time frame where system demands might be higher than normal.

Going Live

To go live, you must build a fresh domain, which includes running a complete batch and importing the latest actuals and plans. In addition, users, security, and formatting can be migrated from the pre-production environment to the production environment. This is accomplished using the RPASCE Online Administration Tools (OAT), as follows:

  1. Select Submit a New Admin Task.

  2. Select System Admin Task.

  3. Select Format/Users/Security Export Task.

  4. Follow the wizard steps to execute the export process. The archive file FormatSecurityExport.tar.gz is sent to the output directory.

  5. Copy the archive to the production environment Object Storage input directory.

  6. Select Submit a New Admin Task.

  7. Select System Admin Task.

  8. Select Format/Users/Security Import Task.

Enter a task label and choose either importing everything (users, security, and formatting) or importing selected individual components.

Follow the wizard steps to complete the import.

Patching the Domain

To patch the domain, you must find a time when no users are logged into the application. A domain backup must be completed prior to starting the patching process.

To begin, upload the new domain configuration archive into the cloud environment. This is described in the Batch Administration chapter of the Oracle Retail Predictive Application Server Cloud Edition Administration Guide.

When the archive upload is complete, follow the Patching the Application section in the Oracle Retail Merchandise Financial Planning Cloud Service Administration Guide.

Resources