G Appendix: Extensibility

As described in Chapter 2, "Implementation Considerations", apart from configuring the MFP application through the plug-ins, MFP also supports extensibility of the GA configuration for non-Enterprise Edition customers. This appendix describes the rules and restrictions enforced to extend the MFP GA configuration, so as to preserve the customizations in future patches and upgrades.

MFP also provides a mechanism for implementers to extend the MFP Batch process and allows custom rule groups to be executed during the batch.

Supported Customization of the MFP Configuration

The following sections list the customizations that are allowed to the MFP configuration. All the names of the custom realized measure, rule set, rule group, rule, workbook, and worksheet should begin with the prefix c_ or C_.

Rules for Customizing the Hierarchy

The following hierarchy customizations are allowed to the MFP configuration:

Clients are allowed to add a new hierarchy or new dimension into the existing hierarchy. No dimension can be added to the calendar hierarchy that is below day. No change can be made to the MFP internal hierarchies.
Clients are allowed to change the label of existing hierarchies or dimensions.
All the dimension and roll-up order in the product, RHS product, location, and RHS location hierarchy must be preserved in the custom configuration.

Rules for Adding Measures

The following rules apply when adding measures to the MFP configuration:

Clients are allowed to add new custom measures into the custom solution and reference them as an external measure in the existing MFP solution. No new measures should be added to the existing MFP GA solution.
Clients can also add a new custom metric as a major component in the extensible solutions. It is strongly recommended not to mix custom metrics with the MFP metrics.
Custom measures should follow the naming convention and should begin with a C_ or c_ prefix.
Currently, only the GA measures listed in the following tables can be used in custom rules and custom workbooks.

Table G-1 Extensible GA Measures for MFP Retail Cloud Service and MFP Cost Cloud Service

GA Measure	Label
DRDVUnElapB	UnElapsed
DRDVElapB	Elapsed
DRDVElapI	Elapsed Index
MPWPSlsR	Wp Sales R
MPWPSlsU	Wp Sales U
MPWPNSlsR	Wp Net Sales R
MPWPNSlsU	Wp Net Sales U
MPWPNSlsC	Wp Net Sales C
MPWPEOPR	Wp EOP R
MPWPEOPU	Wp EOP U
MPWPEOPC	Wp EOP C
MPWPGMR	Wp GM R
MPWPNGMR	Wp Net GM R
MPWPOTBU	Wp OTB U
MPWPOTBR	Wp OTB R
MPWPOTBC	Wp OTB C
DRTYTranInC	Ty Transfers In C
DRTYTranInR	Ty Transfers In R
DRTYTranInU	Ty Transfers In U
DRTYTranInBC	Ty Transfers In Book C
DRTYTranInBR	Ty Transfers In Book R
DRTYTranInBU	Ty Transfers In Book U
DRTYTranInIC	Ty Transfers In ICT C
DRTYTranInIR	Ty Transfers In ICT R
DRTYTranInIU	Ty Transfers In ICT U
DRTYTranOutC	Ty Transfers Out C
DRTYTranOutR	Ty Transfers Out R
DRTYTranOutU	Ty Transfers Out U
DRTYTranOutBC	Ty Transfers Out Book C
DRTYTranOutBR	Ty Transfers Out Book R
DRTYTranOutBU	Ty Transfers Out Book U
DRTYTranOutIC	Ty Transfers Out ICT C
DRTYTranOutIR	Ty Transfers Out ICT R
DRTYTranOutIU	Ty Transfers Out ICT U

Rules for Adding Custom Rules

The following rules apply when adding custom rules to the MFP configuration:

Custom rule sets, rule groups, and rule names should begin with the C_ or c_ prefix.
Custom rule groups should not include any GA rules.
Custom rules can use the published extensible GA measures listed in the tables above. However, the custom rules cannot modify the value of the GA measure. Hence the extensible GA measure cannot appear on the LHS of a custom rule.

Rules for Workbooks and Worksheets Extensibility

The following rules apply when adding custom rules to the MFP workbooks and worksheets extensibility:

New custom workbook and worksheets names should begin with the C_ or c_ prefix.
Apart from the custom solution, custom workbooks can also be added to the extensible MFP GA solutions.

Rules for Adding Custom Styles

The following rules apply when adding new styles:

Existing styles cannot be modified.
New custom styles can be added with the C_ or c_ prefix.
New custom styles can be only used against new custom measures.

Rules for Adding Custom Real Time Alerts into Existing Workbooks

Perform the following steps when adding custom real-time alerts into existing workbooks:

Note:

These steps have to be performed using RPAS Configuration Tools. Copying, pasting, or direct editing of xml files is prohibited.

To add custom real-time alert into existing workbooks, all measures related to the custom real-time alert need to be added to the workbook.
Create a style for the custom real-time alert in the configuration.
Create a custom real-time alert in an MFP workbook using the measures and style created from the previous steps.
If a real-time alert defined in the custom solution will be used in a GA workbook, the real-time alert measure should be imported as an external measure in the corresponding GA solution.

The MFP plug-in will preserve a custom real-time alert during regeneration.

Adding a Custom Solution

A custom solution is a separate solution within the MFP Configuration. It can be used to accommodate custom workbooks, rules, and alerts to do custom reporting, custom logic, and threshold alerts by using GA measures (based on the extensible GA measures in Table G-1. In addition, measures and alerts defined in the custom solution can be plugged into existing workbooks in the GA solution based on the contexts defined. Clients are allowed to create their own custom solutions by following the rules described above. To use a GA measure in custom workbooks, the GA measure should be imported as an external measure into the custom solution.

Validating the Customized Configuration

The script, mfp_config_validation.ksh, is provided to allow the customer or implementer to validate that the customizations conform to the rules outlined above.

This script can be run on Windows with the MFP Cloud Service Starter Kit.

For example, if the custom configuration is in C:\Oracle\configurations\mfprcs (replace mfprcs with mfpccs for MFP Cost Cloud Service) and the updated batch_control files are copied to C:\Oracle\configurations\batch_control_cust, then the script can be called from a Cygwin zsh shell:

$RPAS_HOME/bin/mfp_config_validation.ksh -c
/cygdrive/c/Oracle/configurations/mfprcs/mfprcs.xml -b
/cygdrive/c/Oracle/configurations/batch_control_cust

Note:

If there are no changes to the batch control files, there is no need to use the -b option.

Successful Run of the Validation Script

If all the validations pass, it will output the following message:

Example G-1 Message for Successful Run of the Validation Script

09:04:47 : INFORMATION : mfp_config_validation.ksh[0] - mfp_config_validation.ksh completed.
09:04:47 : INFORMATION : mfp_config_validation.ksh[0] - Program completed successfully.
09:04:47 : INFORMATION : mfp_config_validation.ksh[0] - Exiting script with code: 0

Unsuccessful Run of the Validation Script

If all the validations do not pass, it will output the following message:

Note:

The bold line shows where the details of the validation failure are in the log. (In the actual log, this line is not bold.)

Example G-2 Message for Unsuccessful Run of the Validation Script

09:15:12 : INFORMATION : mfp_config_validation.ksh[0] - For details of validation, look in '/cygdrive/d/retek/logs/2017-07-18/mfp_config_validation.091506.1/mfp_ config_validation.log'.
09:15:12 : INFORMATION : mfp_config_validation.ksh[0] - _call executing command 'execplug-inTask.shMFP:com.retek.labs.MFP.plug-in.installer.MFPConfigurationValidation/cygdrive/c/Oracle/configurations/GA/mfprcs/mfprcs.xml/cygdrive/c/Oracle/configurations/mfprcs'
09:15:17 : INFORMATION : mfp_config_validation.ksh[0] - _call of command'execplug-inTask.shMFP:com.retek.labs.MFP.plug-in.installer.MFPConfigurationValidation/cygdrive/c/Oracle/configurations/GA/mfprcs/mfprcs.xml/cygdrive/c/Oracle/configurationsmfprcs' complete
09:15:17 : ERROR : mfp_config_validation.ksh[0] - Nonzero exit status code.
09:15:17 : INFORMATION : mfp_config_validation.ksh[0] - Exiting script with code:9

Hiding Components of the GA Configuration

As part of extensibility, MFP provides a mechanism wherein the implementer can hide certain components of the GA configuration by editing a property file. The property file is a simple text file named extend_app.properties and is located inside the plug-in directory of the configuration.

For example, mfprcs\plug-ins\extend_app.properties. The format of the file is shown as: Stage|Component|Action|Value

For example, Customization | Worksheet | Hide | MT_TB01_WS01

Each line consists of four fields separated by the | character. The value field can contain a comma separated list of values. Any line that begins with a # character is considered a comment line and is ignored. A sample file is included in the plug-ins directory of the GA configuration for reference.

The only action that can be performed on the GA configuration components is Hide.

The names of the Taskflow entities can be found in the taskflow.xml file located in the configuration directory.

The various GA configuration components that can be hidden are listed in the following table:

Component	Description
Activity	Perform the action (for example, Hide) on the specified Taskflow activity. The value field is the taskflow activity name.
Task	Perform the action (for example, Hide) on the specified Taskflow task. The value field is the taskflow task name.
Step	Perform the action (for example, Hide) on the specified Taskflow step. The value field is the taskflow step name.
Worksheet	Perform the action (for example, Hide) on the specified worksheet. The value field is the worksheet name.
Realtime Alert	Perform the action (for example, Hide) on the specified Real Time Alert. The value field is the real time alert name.

Rules for Changes to PDS Integration Configuration

The following rules apply for changes to the Integration Configuration (RGBU_RDM.xml).

All allowed changes should be marked as custom in the Integration Configuration as allowed by the tools. Merge/Validate of the Build/Patch step during the PDS Build or Patch process will ignore certain changes or fail if following rules are not followed:

GA Shared Hierarchies can neither be removed nor modified. Adding new dimensions to GA hierarchies in PDS Integration Configuration is also not allowed.
GA Fact groups or GA Facts can neither be removed nor modified.
GA Domain name can neither be removed nor modified.
GA Integration Mappings should neither be removed nor modified.
The following GA Integration configuration changes are allowed:
- New Custom hierarchies can be added. If a new hierarchy is added, use the hierarchy order number above 2000 to avoid overlapping with any GA hierarchies that can be added later.
- New Custom facts group and facts can be added.
- New Integration Mappings added for custom facts.

Customizing the MFP Batch Process

This section describes how to customize the MFP GA batch process to meet the business needs of the retailer. Details on the MFP GA batch process are described in the Oracle Retail Merchandise Financial Planning Cloud Service and Oracle Retail Merchandise Financial Planning Enterprise Edition Cloud Service Administration Guide. The Configured Batch tasks have the following tasks related to batch control:

Retrieve Batch Control File - allows the current batch control files to be retrieved for inspection and modification.
Update Batch Control File - after inspecting the current batch control files, the implementer can edit the batch control files to customize the batch process.

Details on the preceding two tasks are described in the Oracle Retail Merchandise Financial Planning Cloud Service and Oracle Retail Merchandise Financial Planning Enterprise Edition Cloud Service Administration Guide.

The MFP Batch process is based on the RPAS Enterprise Edition Batch Framework, which makes use of a set of control files. Table G-2 lists the MFP Batch control files that can be customized.

Table G-2 Customizable MFP Batch Control Files

Control File	Description
batch_exec_list.txt	This is the controller and entry point for all the other services, specifying groups of services to be run in a specific order.
batch_calc_list.txt	This control file groups all the calc services that need to run using mace.
batch_refresh_list.txt	This control file groups all Workbook refresh rule groups.
batch_rebuild_list.txt	This control file groups all Workbook segments that need to be rebuilt in batch.
batch_loadmeas_list.txt	This control file groups measures that need to be loaded into the domain using the measure load service.
batch_exportmeas_list.txt	This control file groups measures that need to be exported out of the domain using the export measure service.
batch_xform_list.txt	This control file handles the transform file service to perform file transformations to support simple integration capabilities.
batch_oat_list.txt	This file lists the configured batch tasks that appear in the OAT drop down list.

The individual control files, including batch_exec_list.txt, can be overridden to customize the batch flow. Each control file uses a set name to control a set of actions. If the override control file uses the same set name as used in GA, the batch task using that set name will use the entries from the override control file. During patches and upgrades, the override control files will be preserved. More details on customizing the batch control files are described in the Oracle Retail Predictive Application Server Cloud Edition Implementation Guide.

The following table describes the behavior of the customized OAT tasks if the customer uploaded their override control files and they differ from the GA task:

E - Set Name Exists
NE - Set Name Does Not Exist

GA Base Task	GA OAT Task	Customer Base Task	Customer OAT Task	Behavior
E	E	E	E (New Label)	Shows new label in the customer OAT.
E	E	E	NE	Since the custom OAT does not exist, it shows the GA label in the drop down. But since the GA set name is overridden in the custom batch, the custom set name will be executed.
E	E	NE	E (New Label)	Shows the label in the customer OAT (New Label).
E	E	NE	NE	Shows the label in the GA OAT.
NE	NE	E	E (New Label)	Shows the label in the customer OAT (New Label).
E	NE	E	E	Hidden in the customer OAT (New Label). Since GA explicitly hides that task, it will not be visible even if the customer used it.

Custom Hooks and Boolean Scalar Measures for Flow Control

There are two ways to customize the batch control files:

Custom Hooks
Boolean Scalar Measures for Flow Control

The custom hooks are an optional batch set executed by GA batch control files. The implementer can define the contents of these batch sets in the customized batch control file that is located in the <domain>/batch_control_cust. If these hooks are not defined, the batch process skips these hooks. If they are defined, its contents are executed.

MFP also defines a list of Boolean Scalar Measures in the domain to control if certain GA defined batch sets can be skipped or not. The following tables list the Custom Hooks and Boolean Scalar Measures.

Custom Hooks

The following table describes the Custom Hooks available in the batch process.

Table G-3 Custom Hooks in the Batch Process

Hook	Description
hook_postbuild	This hook is added at the end of the postbuild batch which runs after the initial domain build.
hook_postpatch	This hook is added at the end of the service patch process which runs after the service patch.
hook_batch_daily_pre	This hook is added before the daily batch process.
hook_batch_daily_post	This hook is added at the end of daily batch process before the dashboard build.
hook_batch_weekly_pre	This hook is added before the weekly batch process.
hook_batch_weekly_post	This hook is added at the end of the weekly batch process before the workbook refresh and segment build.
hook_batch_rms_pre	This hook is added before the batch process specific to RMF CS integration.
hook_batch_rms_post	This hook is added at the end of the batch process specific to RMF CS integration.
hook_batch_non_rms_pre	This hook is added before the batch process specific to non- RMF CS integration.
hook_batch_non_rms_post	This hook is added at the end of the batch process specific to non-RMF CS integration.

Additional hooks are also used for the JOS/POM schedule. For more details, see Appendix I, "Appendix: Batch Schedule in JOS/POM".

Boolean Scalar Measures for Flow Control

The following table describes the Boolean Scalar measures.

Table G-4 Boolean Scalar Measures

Boolean Scalar Measure	Description
drdvrmsb	This measure is defaulted to false. Set it to true if MFP is integrated with RMF CS.
drdvbdib	This measure is defaulted to false. Set it to true if BDI is used for the integration of hierarchy and transaction data.
drdvexpdb	This measure is defaulted to true. If set to false, it will skip exporting the standard exports in the daily batch.
drdvexpwb	This measure is defaulted to true. If set to false, it will skip exporting the standard exports in the weekly batch.

MFP Batch Control File Customization Guidelines

Follow these guidelines for MFP Batch Control File customization:

The file batch_oat_list.txt is the only batch control file in which customers can overwrite the GA set names (such as exec, calc).
For all other batch control files, avoid overwriting the GA set names. GA batch control files have provided various hooks for the batch process. For additional custom steps, try to put them into the hooks.
The GA batch control files have provided a mechanism to skip certain GA steps using the Boolean scalar measure that can be set in the domain. For example, drdvexpwb will allow the skip of standard exports in the weekly batch. To skip the GA steps, use this mechanism instead of overwriting GA set names.
For the GA hierarchy that is unused in your implementation such as the currency hierarchy, provide an empty hierarchy file. For unused GA measures, there is no need to provide the data file. RPAS CE is able to skip it if no files were provided.
For ease of maintenance, all custom batch set names or step names should be prefixed with c_

Example

Following is an example of the custom batch_exec_list.txt, batch_calc_list.txt,
batch_ loadmeas_list.txt, and batch_exportmeas_list.txt files.

In this example, the following modification were added to batch_weekly process:

New Custom Hierarchy and measure data are loaded before the weekly batch.
Additional batch calc and exports after the weekly batch.

Batch Control Samples

The following sections show samples of the batch control processes.

batch_exec_list.txt

# Load a custom hierarchy, measure before weekly batch
hook_batch_weekly_pre |hierload |suph~0~N
hook_batch_weekly_pre |measload |c_load_vndr

                # Run Batch calc and new custom exports after end of weekly batch
hook_batch_weekly_post |calc |c_calc_vndr
hook_batch_weekly_post |exportmeasure |c_exp_vndr

batch_calc_list.txt

# Run newly added custom calc rule group in batch
c_calc_vndr | G | GROUP | c_batch_agg_vndr

batch_loadmeas.txt

# Load custom measure
c_load_vndr|M |c_drtyvndrfndr

batch_exportmeas.txt

# Export custom measure
c_exp_vndr|O|vendo_plan.csv.dat
c_exp_vndr|X|storsclsweek
c_exp_vndr|F|c_exportmask
c_exp_vndr|S|ftp
c_exp_vndr|M|c_mpcpvndrplan

Custom Batch Control Validation

The extensible / custom batch control files need to follow the guidelines previously listed so as to future proof the retailer. That means the retailer should receive software updates without breaking the existing customizations. To ensure that the batch control file guidelines are adhered to, a batch control validation module has been added.

The mfp_config_validation script has an optional parameter -b <parent directory of batch control files> which will validate the batch control files.

Batch control validation rules:

Apart from the batch_oat_list, none of the set names in the other batch control files can be overridden. That is, GA set names cannot be used in custom batch control files.
None of the custom batch control files can call the GA set names.
The batch_calc_list can only specify custom rule group names. It cannot specify expressions and GA rule group names.
The batch_loadmeas_list can specify measures newly added custom measures.
The batch_exportmeas_list can specify custom measures or published GA measures.
All custom set names should have a prefix of c_.

Note that the batch control validation is called automatically during a domain build or patch. It is also called when the batch control files are uploaded using the Upload Batch Control files from OAT.

Customizing the MFP Dashboard

The MFP Dashboard gets the data from the regular dashboard workbook template like any other workbook segments to define the measures used in metric tiles that are shown in the dashboard. The MFP Dashboard also can be customized to extend using the same extensibility rules for regular workbooks for adding new measures into that dashboard workbook (pl_db). The customer can then update the MFP Dashboard json file to include the newly added custom measures to show as tiles in the MFP Dashboard.

Following are the steps for customizing the MFP Dashboard:

Update MFP Configuration to include the required new custom measures and rules to include those measures in the existing dashboard template (pl_db) in the MFP Configuration within regular extensibility framework. Patch the domain with the new updated configuration.
Download the MFP dashboard json file (mfprcsDashboardSettings.json for MFP Retail or mfpccsDashboardSettings.json for MFP Cost) from the Starter kit or directly from the customer-provisioned environment by running the Online Admin Tool task Configured Batch Tasks -> Manage JSON Files -> Retrieve JSON files to FTP, which will download the JSON file into the SFTP location.
Open the dashboard json file using the RPAS Configuration Tools -> Utilities -> Deployment Tool and selecting the Open option under dashBoardSettings.json.
It should open the dashboard json file in edit mode. The customer can then edit the dashboard to add the newly added measures into their required profiles. They can also add new profiles or change profiles, but can only use the measures available in the dashboard workbook. For more information on working with json file using RPAS Configuration Tools, see the Oracle Retail Predictive Application Server Cloud Edition Configuration Tools User Guide.
Once the json file is updated, it can be uploaded into the MFP environment after zipping the file, uploading the file to the SFTP location, and running the Online Admin Tool task Configured Batch Tasks -> Manage JSON Files > Update JSON files from FTP. Successful completion of the task will copy the file to the required location under the application domain.
After uploading, rebuild the dashboard to view the updated dashboard.
The entire process can be validated in the Virtual machine, before trying to upload the completed json file into the customer environment.