Oracle Retail Predictive Application Server Administration

Oracle® Retail Predictive Application Server
Administration Guide for the Classic Client
Release 13.4
December 2012
Oracle® Retail Predictive Application Server Administration Guide for the Classic Client, Release 13.4
Copyright © 2012, Oracle and/or its affiliates. All rights reserved.
Primary Author:
Judith Meskill
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,
any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users
are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and
agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on
the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to
the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle
Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your
access to or use of third-party content, products, or services.
Value-Added Reseller (VAR) Language
Oracle Retail VAR Applications
The following restrictions and provisions only apply to the programs referred to in this section and licensed
to you. You acknowledge that the programs may contain third party software (VAR applications) licensed to
Oracle. Depending upon your product and its version number, the VAR applications may include:
(i) the MicroStrategy Components developed and licensed by MicroStrategy Services Corporation
(MicroStrategy) of McLean, Virginia to Oracle and imbedded in the MicroStrategy for Oracle Retail Data
Warehouse and MicroStrategy for Oracle Retail Planning & Optimization applications.
(ii) the Wavelink component developed and licensed by Wavelink Corporation (Wavelink) of Kirkland,
Washington, to Oracle and imbedded in Oracle Retail Mobile Store Inventory Management.
(iii) the software component known as Access Via™ licensed by Access Via of Seattle, Washington, and
imbedded in Oracle Retail Signs and Oracle Retail Labels and Tags.
(iv) the software component known as Adobe Flex™ licensed by Adobe Systems Incorporated of San Jose,
California, and imbedded in Oracle Retail Promotion Planning & Optimization application.
You acknowledge and confirm that Oracle grants you use of only the object code of the VAR Applications.
Oracle will not deliver source code to the VAR Applications to you. Notwithstanding any other term or
condition of the agreement and this ordering document, you shall not cause or permit alteration of any VAR
Applications. For purposes of this section, "alteration" refers to all alterations, translations, upgrades,
enhancements, customizations or modifications of all or any portion of the VAR Applications including all
reconfigurations, reassembly or reverse assembly, re-engineering or reverse engineering and recompilations
or reverse compilations of the VAR Applications or any derivatives of the VAR Applications. You
acknowledge that it shall be a breach of the agreement to utilize the relationship, and/or confidential
information of the VAR Applications for purposes of competitive discovery.
The VAR Applications contain trade secrets of Oracle and Oracle's licensors and Customer shall not attempt,
cause, or permit the alteration, decompilation, reverse engineering, disassembly or other reduction of the
VAR Applications to a human perceivable form. Oracle reserves the right to replace, with functional
equivalent software, any of the VAR Applications in future releases of the applicable program.
Contents
Send Us Your Comments ...................................................................................................................... xvii
Preface ............................................................................................................................................................... xix
1 Introduction
Administrator Overview .........................................................................................................................
Basic Concepts of RPAS ..........................................................................................................................
Multidimensionality ..........................................................................................................................
Hierarchies ..........................................................................................................................................
Measures..............................................................................................................................................
Domains and Workbooks .................................................................................................................
Measure Data...............................................................................................................................
Administrative Workbooks and Wizards ............................................................................................
2
1-1
1-1
1-2
1-2
1-2
1-2
1-3
1-4
Building and Upgrading Domains
Building a Domain................................................................................................................................... 2-1
Prerequisites........................................................................................................................................ 2-1
Client-Side Procedures ...................................................................................................................... 2-1
Zip the Configuration Project Folder ....................................................................................... 2-2
Server-Side Procedures ..................................................................................................................... 2-2
Unzip the Configuration File .................................................................................................... 2-2
Verify the Environment Variable Settings .............................................................................. 2-2
Get the Input Files Ready .......................................................................................................... 2-3
Building the Domain Manually or Through a Command-Line Interface..................................... 2-3
rpasInstall ............................................................................................................................................ 2-3
rpasInstall Usage......................................................................................................................... 2-3
Validate Domain Build Results ........................................................................................................ 2-5
After Building the Domain .................................................................................................................... 2-5
Upgrading and Patching Domains.................................................................................................. 2-5
Upgrading From Any Release of RPAS Prior to 13.3 ................................................................... 2-5
Domain Conversion........................................................................................................................... 2-6
Domain Preparation Before Conversion ................................................................................. 2-6
Setting up Domain Conversion Parameters............................................................................ 2-9
Running the Domain Conversion.......................................................................................... 2-10
Post-Conversion Processing ................................................................................................... 2-10
v
Upgrading From RPAS 13.3 or Later ...........................................................................................
Updating Domain Content ............................................................................................................
Hierarchies ................................................................................................................................
Measure Properties ..................................................................................................................
Rule Groups ..............................................................................................................................
Workbooks ................................................................................................................................
Upgrade Configurations ................................................................................................................
Command-line Support for Configuration Upgrading......................................................
Upgrade Application Configurations ...................................................................................
convertDomain ................................................................................................................................
convertDomain Usage.............................................................................................................
convertDomain -suggestDimBitSize ............................................................................................
Usage for -suggestDimBitSize................................................................................................
upgradeDomain ..............................................................................................................................
upgradeDomain Usage ...........................................................................................................
fixDomain ...............................................................................................................................................
fixDomain Usage.............................................................................................................................
2-12
2-13
2-13
2-13
2-14
2-14
2-14
2-15
2-16
2-16
2-17
2-19
2-20
2-20
2-20
2-21
2-22
3 Domain Administration
Configuring the Classic Client - eConfigure ......................................................................................
eConfigure Menu Bar ........................................................................................................................
eConfigure Main View ......................................................................................................................
Advanced Settings Dialog .........................................................................................................
Domain Daemon ......................................................................................................................................
DomainDaemon Usage .....................................................................................................................
Starting the DomainDaemon............................................................................................................
Monitoring the DomainDaemon......................................................................................................
Stopping the DomainDaemon..........................................................................................................
Losing a Client-Server Connection.......................................................................................................
Graceful Termination of the Existing Session ................................................................................
Autosave of Workbooks....................................................................................................................
3-1
3-1
3-2
3-3
3-4
3-4
3-5
3-6
3-6
3-6
3-6
3-7
4 SSL
Introduction...............................................................................................................................................
One-Way SSL.............................................................................................................................................
Creating a Self-Signed Root Certificate...........................................................................................
Configuring the RPAS Server...........................................................................................................
Setting Up the Key Store ............................................................................................................
Starting the Domain Daemon....................................................................................................
Configuring the Classic Client .........................................................................................................
Script for Creating Self-Signed Wallets...........................................................................................
Usage for createSSLWallets.sh ..................................................................................................
User Input ....................................................................................................................................
Output ..........................................................................................................................................
Error Handling ............................................................................................................................
RPAS Web Launch .............................................................................................................................
SSL Without Authentication ..................................................................................................................
vi
4-1
4-1
4-2
4-3
4-3
4-5
4-5
4-7
4-7
4-7
4-7
4-7
4-7
4-8
RPAS Server Configuration .............................................................................................................. 4-9
Disabling SSL ........................................................................................................................................... 4-9
5 User Maintenance
Access the User Administration Tab..................................................................................................... 5-2
Add User .................................................................................................................................................... 5-3
Add User Group ....................................................................................................................................... 5-5
Delete User ................................................................................................................................................ 5-6
Delete User Group ................................................................................................................................... 5-7
Edit User..................................................................................................................................................... 5-8
Managing Users - usermgr Utility...................................................................................................... 5-10
usermgr Usage................................................................................................................................. 5-10
XML Schema .................................................................................................................................... 5-12
Use Cases.......................................................................................................................................... 5-14
Exporting from an Existing Domain ..................................................................................... 5-14
Importing into a Domain ........................................................................................................ 5-14
Converting Between XML and Database ............................................................................. 5-15
6 System Administration
Auto Workbook Maintenance Wizard.................................................................................................. 6-2
Add a Workbook to the Auto Build Queue ................................................................................... 6-2
Delete a Workbook from the Auto Build Queue ........................................................................... 6-4
Edit Workbook Settings .................................................................................................................... 6-4
Workbook Batch Category Management ............................................................................................. 6-5
Workbook Batch Category Management Wizard ......................................................................... 6-5
Adding a Category............................................................................................................................. 6-6
Deleting a Category ........................................................................................................................... 6-7
Changing a Category Label .............................................................................................................. 6-8
Hierarchy Maintenance Workbook....................................................................................................... 6-9
Hierarchy Maintenance Example .................................................................................................... 6-9
Hierarchy Maintenance Wizard.................................................................................................... 6-10
Hierarchy Maintenance Worksheet.............................................................................................. 6-10
Access Hierarchy Maintenance ..................................................................................................... 6-12
Maintain a User-Defined Dimension within a Hierarchy......................................................... 6-12
Password Policy Administration Workbook.................................................................................... 6-13
Security Administration Workbook .................................................................................................. 6-15
Security Overview........................................................................................................................... 6-15
User Logon Security ................................................................................................................ 6-15
Measure Level Security ........................................................................................................... 6-15
Position Level Security............................................................................................................ 6-16
Workbook Security .................................................................................................................. 6-17
Security Administration Workbook ............................................................................................. 6-18
Workbook Template Rights Worksheet ............................................................................... 6-19
Workbook Template Measure Rights Worksheet ............................................................... 6-19
Measure Rights Worksheet..................................................................................................... 6-20
Dimension Modification Rights Worksheet......................................................................... 6-20
vii
Position Level Security Worksheets ......................................................................................
Workbook Template Limits Worksheets..............................................................................
Max Domain Session Limit Worksheet ................................................................................
Max User Session Limit Worksheet ......................................................................................
Using the Security Administration Workbook ...........................................................................
Access Security Administration.............................................................................................
Set or Modify User Access to Workbook Templates ..........................................................
Set Measure Availability for Workbook Templates............................................................
Assign or Restrict User Access to Measures ........................................................................
Change User Ability to Modify Dimensions .......................................................................
Set or Modify Access to Positions..........................................................................................
Limit the Number of Workbooks that a User Can Save.....................................................
Set or Modify the Maximum Domain Session Limit ..........................................................
Set or Modify the Maximum User Session Limit ................................................................
Measure Analysis Workbook..............................................................................................................
Building a Measure Analysis Workbook.....................................................................................
Measure Analysis Worksheet........................................................................................................
Review and Edit Sales or Other Registered Measure Data.......................................................
6-21
6-21
6-21
6-21
6-22
6-22
6-22
6-22
6-23
6-23
6-23
6-24
6-24
6-24
6-25
6-25
6-26
6-26
7 Hierarchy Management
Loading Hierarchies - loadHier ............................................................................................................. 7-1
loadHier Usage ................................................................................................................................... 7-3
loadHier Notes ................................................................................................................................... 7-4
Position Label Translation ................................................................................................................ 7-5
Integer Indexing ....................................................................................................................................... 7-6
Changing the Bit Size......................................................................................................................... 7-8
Reindexing Domains -reindexDomain ................................................................................................ 7-9
reindexDomain Usage .................................................................................................................... 7-10
ReindexDomain Usage: Reindex ........................................................................................... 7-10
ReindexDomain Usage: Analysis .......................................................................................... 7-11
ReindexDomain Usage: Domain Properties ........................................................................ 7-12
When to Reindex ............................................................................................................................. 7-13
Run Reports .............................................................................................................................. 7-14
How to Reindex a Dimension ....................................................................................................... 7-16
Reindex Entire Domain as Needed ....................................................................................... 7-16
Reindex Entire Domain with Force Option.......................................................................... 7-16
Reindex Dimensions................................................................................................................ 7-16
Prepending Calendar Dimensions ....................................................................................... 7-16
Reindex Domain Examples............................................................................................................ 7-18
Condition 1: Change of Bit Size ............................................................................................. 7-18
Condition 2: Using the -force Option.................................................................................... 7-18
Condition 3: Fragmentation Checks...................................................................................... 7-19
Optimizing Domains -optimizeDomain .......................................................................................... 7-20
optimizeDomain Usage.................................................................................................................. 7-21
Usage Examples ....................................................................................................................... 7-22
Adding New Dimensions to Hierarchies ......................................................................................... 7-23
Exporting Measure Data ................................................................................................................ 7-23
viii
Exporting Hierarchy Data..............................................................................................................
Purging Hierarchy Data .................................................................................................................
Adding New Dimensions ..............................................................................................................
Reloading Formal Hierarchy Data................................................................................................
Informalizing DPM Positions ........................................................................................................
Reloading Measure Data................................................................................................................
Adding New Hierarchy Dimensions Sample Script ..................................................................
Transferring Data ............................................................................................................................
Masks .........................................................................................................................................
transferData Usage ..................................................................................................................
Scenarios....................................................................................................................................
FilterHier Utility....................................................................................................................................
filterHier Usage ...............................................................................................................................
filterHier Notes................................................................................................................................
Error Conditions..............................................................................................................................
Position Repartitioning........................................................................................................................
Loading RDF and Curve Parameters after Repartitioning .......................................................
Syntax ........................................................................................................................................
Reconfiguring Partitions of a Global Domain
- reconfigGlobalDomainPartitions ....................................................................................................
reconfigGlobalDomainPartitions Usage ......................................................................................
Using an Input File..........................................................................................................................
Notes, Assumptions, and Limitations..........................................................................................
Renaming Positions - renamePositions ............................................................................................
renamePositions Usage ..................................................................................................................
Setting Properties for Dimensions -dimensionMgr .......................................................................
dimensionMgr Usage .....................................................................................................................
Changing the Label of a Dimension .............................................................................................
Exporting Hierarchy Data - exportHier.............................................................................................
exportHier Usage ............................................................................................................................
Informal Position Manager .................................................................................................................
InformalPositionMgr Usage ..........................................................................................................
Basic Operations: Informalize, Formalize, Remove ..................................................................
Error Handling .........................................................................................................................
Create Informal Positions in Bulk.................................................................................................
Example 1: Create Informal Positions on the STYL Dimension........................................
Example 2: Create Informal Positions on the SZ12 Dimension.........................................
Position Naming Convention.................................................................................................
Data Slice Copying..........................................................................................................................
Merge Informal Positions to Formal Positions ....................................................................
Managing Position Lists as PQDs - pqdMgr ...................................................................................
pqdMgr Usage .................................................................................................................................
pqdMgr Notes..................................................................................................................................
7-24
7-24
7-24
7-25
7-25
7-25
7-26
7-28
7-29
7-30
7-30
7-31
7-31
7-32
7-32
7-33
7-33
7-33
7-34
7-35
7-36
7-37
7-37
7-37
7-39
7-39
7-40
7-41
7-41
7-42
7-42
7-42
7-43
7-44
7-46
7-46
7-47
7-48
7-49
7-50
7-51
7-51
8 Data Management
Loading Measure Data - loadmeasure.................................................................................................. 8-1
Load File Names and Load Behavior .............................................................................................. 8-2
ix
Loading Multiple Measures from One File .................................................................................... 8-4
CSV Files ...................................................................................................................................... 8-4
Fixed Width Files ........................................................................................................................ 8-4
Loading Data from Below the Base Intersection of the Measures .............................................. 8-4
Staging Measure Loads ..................................................................................................................... 8-5
Running Pre-Load or Post-Load Scripts ......................................................................................... 8-5
Purging Old Measure Data............................................................................................................... 8-5
Behavior in a Global Domain Environment................................................................................... 8-6
loadmeasure Usage............................................................................................................................ 8-6
Loading Image Paths for Positions .................................................................................................. 8-9
Exporting Measure Data - exportMeasure........................................................................................... 8-9
exportMeasure Usage ........................................................................................................................ 8-9
Exporting Measure Data - exportData ............................................................................................... 8-12
exportData Usage............................................................................................................................ 8-13
-useLoadFormat Parameter .................................................................................................... 8-15
Mapping Data Between Domains - mapData .................................................................................. 8-16
mapdata Usage ................................................................................................................................ 8-16
Moving Data Between Arrays - updateArray .................................................................................. 8-17
updateArray Usage......................................................................................................................... 8-17
Scan Domain Data - scanDomain ...................................................................................................... 8-18
scanDomain Usage.......................................................................................................................... 8-19
Repair Domain Metadata - fixDomain.............................................................................................. 8-20
9 Operational Utilities
Find Alerts - alertmgr Utility ................................................................................................................. 9-1
alertmgr Usage ................................................................................................................................... 9-2
Copying Domains - copyDomain Utility............................................................................................. 9-3
copyDomain Usage............................................................................................................................ 9-3
copyDomain: Format of the XML Configuration File ........................................................... 9-5
Move a Domain - moveDomain Utility ............................................................................................... 9-6
moveDomain Usage........................................................................................................................... 9-6
moveDomain: Format of the XML Configuration File .......................................................... 9-7
Assumptions and Requirements .............................................................................................. 9-7
Minimum Space Requirement .................................................................................................. 9-8
Setting Miscellaneous Domain Properties - domainprop Utility................................................... 9-8
domainprop Usage............................................................................................................................. 9-8
Available Properties ................................................................................................................... 9-8
Calculation Engine - mace Utility ...................................................................................................... 9-10
mace Usage....................................................................................................................................... 9-11
Managing the Workbook Batch Queue - wbbatch Utility............................................................. 9-13
wbbatch Usage................................................................................................................................. 9-14
Workbook Manager - wbmgr Utility ................................................................................................. 9-16
wbmgr Usage................................................................................................................................... 9-16
Register Measure - regmeasure Utility.............................................................................................. 9-17
regmeasure Usage ........................................................................................................................... 9-17
Register Token Measure - regTokenMeasure Utility ..................................................................... 9-23
regTokenMeasure Usage................................................................................................................ 9-24
x
Batch Plug-In Tasks: execPluginTask.sh ........................................................................................... 9-24
execPluginTask.sh usage................................................................................................................ 9-25
10 Informational Utilities
Retrieving Domain Information - domaininfo Utility...................................................................
domaininfo Usage ...........................................................................................................................
Checking the Validity of a Domain - checkDomain Utility..........................................................
checkDomain Usage .......................................................................................................................
Determining RPAS Server Version - rpasversion Utility ..............................................................
rpasversion Usage ...........................................................................................................................
List Contents of a Database - listDb Utility .....................................................................................
listDb Usage .....................................................................................................................................
Printing Data from Arrays - printArray Utility ...............................................................................
printArray Usage ............................................................................................................................
Printing Data from Measures - printmeasure Utility .....................................................................
printmeasure Usage........................................................................................................................
10-1
10-1
10-3
10-3
10-4
10-4
10-4
10-4
10-4
10-4
10-6
10-6
11 Internationalization
Translation ..............................................................................................................................................
Translation Administration .................................................................................................................
Translation Administration Workbook .......................................................................................
Hierarchy Labels Worksheet ..................................................................................................
Dimension Labels Worksheet ................................................................................................
Workbook Template Group Labels Worksheet...................................................................
Workbook Template Labels Worksheet ...............................................................................
Measure Labels Worksheet.....................................................................................................
Measure Descriptions Worksheet..........................................................................................
User Group Labels Worksheet ...............................................................................................
Message Labels Worksheet.....................................................................................................
RGRP Labels Worksheet .........................................................................................................
11-1
11-2
11-4
11-4
11-5
11-5
11-5
11-5
11-5
11-5
11-5
11-5
12 Commit as Soon as Possible
Using Commit ASAP ............................................................................................................................
Managing the Workbook Queue - showWorkbookQueues..........................................................
showWorkbookQueue Usage........................................................................................................
Commit ASAP Settings - configCommitAsap.................................................................................
configCommitAsap Usage .............................................................................................................
Logging and Technical Information .............................................................................................
12-1
12-2
12-2
12-3
12-3
12-4
13 Batch Processes and RPAS Utilities
CSV File Format.....................................................................................................................................
RPAS Utilities Logging Options ........................................................................................................
Log Levels ........................................................................................................................................
Utilities with Standard Logging....................................................................................................
Scripts ........................................................................................................................................
13-1
13-2
13-2
13-3
13-3
xi
Utilities with Multi-Process Logging ...........................................................................................
Utilities with Special Logging .......................................................................................................
Utilities and Database Locks .........................................................................................................
Using Shell Scripts to Run Batch Processes.....................................................................................
A Sample Shell Script .....................................................................................................................
Common Information and Parameters for RPAS Utilities............................................................
Configuration Tools Log Files .......................................................................................................
RPAS Intraday Enabler.........................................................................................................................
ride Usage.......................................................................................................................................
Scenarios .........................................................................................................................................
Scenario 1 ................................................................................................................................
Scenario 2 ................................................................................................................................
Scenario 3 ................................................................................................................................
Scenario 4 ................................................................................................................................
Scenario 5 ................................................................................................................................
Scenario 6 ................................................................................................................................
Domain Lock Status Utility - domainStatus..............................................................................
domainStatus Usage ..............................................................................................................
13-4
13-5
13-6
13-7
13-7
13-7
13-8
13-8
13-11
13-11
13-12
13-12
13-13
13-13
13-14
13-15
13-15
13-15
14 RPAS ODBC/JDBC Driver
ODBC Configuration............................................................................................................................
Defining the ODBC Server Configuration Settings....................................................................
Add RPAS ODBC Manager in the Management Console .................................................
Configure Using the ODBC Manager ...................................................................................
Import the Configuration Changes .....................................................................................
Defining the ODBC Client Configuration for Windows .........................................................
Starting the RPAS ODBC Server Process .......................................................................................
Testing the Connection Using Interactive SQL.........................................................................
ODBC Client Configuration for UNIX ...........................................................................................
Client Configuration .....................................................................................................................
Testing the Connection.................................................................................................................
Installing and Using the RPAS JDBC Driver.................................................................................
Updating Environment Variables for the JDBC Driver on Windows ...................................
Updating Environment Variables for JDBC Driver on UNIX/Linux....................................
Using the RPAS JDBC Driver ......................................................................................................
Enabling Spy for RPAS JDBC Driver .........................................................................................
Using the jdbcisql Utility Provided with RPAS JDBC Driver ................................................
Using Oracle SQL Developer ......................................................................................................
Using Oracle JDeveloper..............................................................................................................
Using a Java Program ...................................................................................................................
Running the Program ............................................................................................................
Data Query............................................................................................................................................
Limitations .....................................................................................................................................
Contention...............................................................................................................................
Workbook Queries.................................................................................................................
Metadata .........................................................................................................................................
Fact and Dimension Tables..........................................................................................................
xii
14-2
14-2
14-3
14-9
14-14
14-15
14-19
14-19
14-20
14-20
14-21
14-22
14-22
14-23
14-23
14-24
14-25
14-25
14-26
14-26
14-28
14-28
14-28
14-28
14-28
14-29
14-30
Measure Security in the ODBC Driver ...........................................................................................
Use Cases...............................................................................................................................................
Using Metadata Tables to Explore the Structure of a Domain or a Workbook ...................
Querying Fact Data .......................................................................................................................
Connecting to a Workbook ..........................................................................................................
Requesting Additional Aggregate Tables..................................................................................
Clients....................................................................................................................................................
Oracle Business Intelligence Enterprise Edition (OBIEE) .......................................................
Configuring the ODBC Client for OBIEE ...........................................................................
Connecting OBIEE to an RPAS Domain.............................................................................
Microsoft Access............................................................................................................................
JDeveloper ......................................................................................................................................
XML Publisher...............................................................................................................................
Interactive SQL (ISQL) Utility .....................................................................................................
Supported and Unsupported SQL Functions ................................................................................
Supported SQL Functions............................................................................................................
Numeric Functions ................................................................................................................
String Functions .....................................................................................................................
Time / Date Functions ..........................................................................................................
System Functions ...................................................................................................................
Aggregate Functions..............................................................................................................
Other Functions......................................................................................................................
Unsupported SQL Functions.......................................................................................................
Handling of NULLS...............................................................................................................
Schema Information...............................................................................................................
Data Definition Language (DDL) ........................................................................................
Insert ........................................................................................................................................
SELECT Syntax.......................................................................................................................
Value Expressions ..................................................................................................................
Value Functions......................................................................................................................
Date/Time Functions ............................................................................................................
Advanced Value Expressions...............................................................................................
Row Value Constructor.........................................................................................................
Predicates ................................................................................................................................
Join Operators.........................................................................................................................
14-31
14-32
14-32
14-33
14-34
14-34
14-34
14-35
14-35
14-36
14-36
14-37
14-38
14-39
14-39
14-39
14-40
14-42
14-46
14-50
14-50
14-51
14-57
14-57
14-57
14-57
14-57
14-57
14-57
14-58
14-58
14-58
14-59
14-59
14-59
15 Publishing Measure Change Events
Configuring Subjects and Measures for Monitoring.....................................................................
Configuring the RPAS JMS Publisher ..............................................................................................
Command Line ................................................................................................................................
Configuration Settings....................................................................................................................
General Settings .......................................................................................................................
Vendor-Specific Settings .........................................................................................................
File Based JNDI Object Store ..................................................................................................
LDAP Based JNDI Object Store .............................................................................................
Configuring the RPAS JMS Subscriber ............................................................................................
Command Line ................................................................................................................................
15-2
15-3
15-4
15-5
15-5
15-6
15-6
15-6
15-7
15-7
xiii
Configuration Settings.................................................................................................................... 15-8
16 In-Context Launch
Launching RPAS....................................................................................................................................
Issuing a Launch Request from a Web Page ...............................................................................
Embedding an RWL Applet on a Web Page........................................................................
Using JavaScript with the RWL Applet ................................................................................
User Authentication.................................................................................................................
Deploying In-Context Launch..............................................................................................
Use Cases.................................................................................................................................
RPAS Launch Context Format ....................................................................................................
Client Settings.........................................................................................................................
Server Settings ........................................................................................................................
Domain Settings .....................................................................................................................
Workbook Settings.................................................................................................................
XML Schema ...........................................................................................................................
Open Workbook ............................................................................................................................
Specifications ..........................................................................................................................
Examples .................................................................................................................................
Build Workbook ............................................................................................................................
Specifications ..........................................................................................................................
Example ...................................................................................................................................
buildWorkbookContext Utility ...................................................................................................
buildWorkbookContext Usage ............................................................................................
16-1
16-2
16-3
16-4
16-8
16-10
16-10
16-11
16-12
16-12
16-12
16-13
16-13
16-17
16-17
16-18
16-19
16-19
16-22
16-24
16-24
A Appendix: Curve Administration Guide
curvevalidate ............................................................................................................................................
curvevalidate Usage..........................................................................................................................
curvebatch .................................................................................................................................................
curvebatch Usage ..............................................................................................................................
A-1
A-1
A-3
A-3
B Appendix: RPAS Test Driver
Support ......................................................................................................................................................
Introduction..............................................................................................................................................
Audience.............................................................................................................................................
Finding Required Information ........................................................................................................
Compatibility .....................................................................................................................................
Interface.....................................................................................................................................................
XML Requests ..........................................................................................................................................
Connection Messages .......................................................................................................................
<Logon> ......................................................................................................................................
<Logoff> ......................................................................................................................................
Wizard Messages...............................................................................................................................
<WizardInitialize>.....................................................................................................................
<GetNextWizardDialog>..........................................................................................................
<GetWizardLayout>..................................................................................................................
xiv
B-1
B-1
B-1
B-1
B-2
B-2
B-4
B-4
B-4
B-4
B-4
B-4
B-4
B-5
<SelectPositions> .......................................................................................................................
<SetWizardData>.......................................................................................................................
<WizardFinish>..........................................................................................................................
Workbook Messages .........................................................................................................................
<OpenWorkbook> .....................................................................................................................
<Fetch> ........................................................................................................................................
<SetValues> ................................................................................................................................
<CommitWorkbook> ................................................................................................................
<RefreshWorkbook> .................................................................................................................
<MenuEvent> .............................................................................................................................
<CreatePOPMeasure>...............................................................................................................
<SaveWorkbook>.....................................................................................................................
<CloseWorkbook> ...................................................................................................................
RTD use with HP LoadRunner...........................................................................................................
Prerequisites...........................................................................................................................................
Header File..............................................................................................................................................
lr_rtd.h ..............................................................................................................................................
LoadRunner Scripting ..........................................................................................................................
Script Settings ..................................................................................................................................
Script Sections ..................................................................................................................................
Script Implementation ....................................................................................................................
Script Section: vuser_init.........................................................................................................
Script Section: Action (simple test)........................................................................................
Script section: Action (real-world).........................................................................................
Considerations for Scenario Use ...................................................................................................
B-5
B-5
B-6
B-7
B-7
B-7
B-8
B-8
B-9
B-9
B-9
B-10
B-10
B-11
B-11
B-11
B-11
B-12
B-12
B-12
B-12
B-12
B-13
B-13
B-14
C Appendix: RPAS Test Automation
Introduction..............................................................................................................................................
Usage..........................................................................................................................................................
Writing Test Cases ...................................................................................................................................
Example .....................................................................................................................................................
Output........................................................................................................................................................
Schema.......................................................................................................................................................
1. Top Level Parent Tag....................................................................................................................
1.1 testscript ................................................................................................................................
1.2 testsuite..................................................................................................................................
1.3 testcase...................................................................................................................................
1.4 setup.......................................................................................................................................
1.5 teardown ...............................................................................................................................
2. Generic Tags...................................................................................................................................
2.1 Attribute ................................................................................................................................
2.2 Description............................................................................................................................
2.3 Fail ..........................................................................................................................................
2.4 key ..........................................................................................................................................
2.5 rpas-today .............................................................................................................................
2.6 shell ........................................................................................................................................
2.7 register-measure...................................................................................................................
C-1
C-1
C-2
C-3
C-5
C-7
C-7
C-7
C-7
C-7
C-7
C-7
C-7
C-7
C-8
C-8
C-8
C-8
C-8
C-8
xv
2.8 unregister-measure .............................................................................................................. C-9
3. Workbook Operation Tags .......................................................................................................... C-9
3.1 Workbook Wizard Operations........................................................................................... C-9
3.2 Workbook Operations ....................................................................................................... C-12
3.3 Workbook Assertions ........................................................................................................ C-13
3.4 Workbook Data Edit Operations ..................................................................................... C-22
4. Domain Operation Tags ............................................................................................................. C-24
4.1 Assertions............................................................................................................................ C-24
4.2 Domain Data Edit Operations.......................................................................................... C-32
D Appendix: Environment Variables
Required Settings....................................................................................................................................
Database Settings ....................................................................................................................................
RPAS_CACHE...................................................................................................................................
RPAS_PAGE_SIZE............................................................................................................................
RPAS_PAGE_SPLIT_PERCENTAGE ............................................................................................
RPAS_LOCK_TIMEOUT ................................................................................................................
RPAS_REQUEST_TIMEOUT ..........................................................................................................
RPAS_USER_MODE.........................................................................................................................
Log Settings ..............................................................................................................................................
RPAS_LOG_BACKUPS ...................................................................................................................
RPAS_LOG_LEVEL ..........................................................................................................................
RPAS_LOG_PATH ...........................................................................................................................
Profiling Logging ....................................................................................................................................
RPAS_PROFILING_ENABLE .........................................................................................................
RPAS_PROFILING_PATH ..............................................................................................................
Date and Time Setting............................................................................................................................
RPAS_TODAY ...................................................................................................................................
RPAS_TODAY_STATIC...................................................................................................................
Numeric Precision ...................................................................................................................................
RPAS_INCAGGPRC.........................................................................................................................
epsilon.................................................................................................................................................
RPAS_PROCESSES.................................................................................................................................
LDR_CNTRL=NAMEDSHLIB=RPASZONE ....................................................................................
xvi
D-2
D-2
D-2
D-3
D-3
D-3
D-4
D-4
D-5
D-5
D-5
D-5
D-6
D-6
D-6
D-6
D-6
D-6
D-7
D-7
D-7
D-7
D-8
Send Us Your Comments
Oracle Retail Predictive Application Server Administration Guide for the Classic
Client, Release 13.4
Oracle welcomes customers' comments and suggestions on the quality and usefulness
of this document.
Your feedback is important, and helps us to best meet your needs as a user of our
products. For example:
■
Are the implementation steps correct and complete?
■
Did you understand the context of the procedures?
■
Did you find any errors in the information?
■
Does the structure of the information help you with your tasks?
■
Do you need different information or graphics? If so, where, and in what format?
■
Are the examples correct? Do you need more examples?
If you find any errors or have any other suggestions for improvement, then please tell
us your name, the name of the company who has licensed our products, the title and
part number of the documentation and the chapter, section, and page number (if
available).
Before sending us your comments, you might like to check
that you have the latest version of the document and if any concerns
are already addressed. To do this, access the Online Documentation
available on the Oracle Technology Network Web site. It contains the
most current Documentation Library plus all documents revised or
released recently.
Note:
Send your comments to us using the electronic mail address: retail-doc_us@oracle.com
Please give your name, address, electronic mail address, and telephone number
(optional).
If you need assistance with Oracle software, then please contact your support
representative or Oracle Support Services.
If you require training or instruction in using Oracle software, then please contact
your Oracle local office and inquire about our Oracle University offerings. A list of
Oracle offices is available on our Web site at http://www.oracle.com.
xvii
xviii
Preface
Oracle Retail Administration Guides are designed so that you can view and
understand the application's behind-the-scenes processing, including such information
as the following:
■
Key system administration configuration settings
■
Technical architecture
■
Functional integration dataflow across the enterprise
■
Batch processing
Audience
This document is intended for the users and administrators of Oracle Retail Predictive
Application Server. This may include merchandisers, buyers, and business analysts.
Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation
accessible to all users, including users that are disabled. To that end, our
documentation includes features that make information available to users of assistive
technology. This documentation is available in HTML format, and contains markup to
facilitate access by the disabled community. Accessibility standards will continue to
evolve over time, and Oracle is actively engaged with other market-leading
technology vendors to address technical obstacles so that our documentation can be
accessible to all of our customers. For information about Oracle's commitment to
accessibility, visit the Oracle Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The
conventions for writing code require that closing braces should appear on an
otherwise empty line; however, some screen readers may not always read a line of text
that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or
organizations that Oracle does not own or control. Oracle neither evaluates nor makes
any representations regarding the accessibility of these Web sites.
xix
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For
information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are
hearing impaired.
Related Documents
For more information, see the following documents in the Oracle Retail Predictive
Application Server Release 13.4 documentation set:
■
Oracle Retail Predictive Application Server Administration Guide for the Fusion Client
■
Oracle Retail Predictive Application Server Configuration Tools User Guide
■
Oracle Retail Predictive Application Server Installation Guide
■
Oracle Retail Predictive Application Server Licensing Information
■
Oracle Retail Predictive Application Server Release Notes
■
Oracle Retail Predictive Application Server User Guide for the Classic Client
■
Oracle Retail Predictive Application Server User Guide for the Fusion Client
Customer Support
To contact Oracle Customer Support, access My Oracle Support at the following URL:
https://support.oracle.com
When contacting Customer Support, please provide the following:
■
Product version and program/module name
■
Functional and technical description of the problem (include business impact)
■
Detailed step-by-step instructions to re-create
■
Exact error message received
■
Screen shots of each step you take
Review Patch Documentation
When you install the application for the first time, you install either a base release (for
example, 13.4) or a later patch release (for example, 13.4.1). If you are installing the
base release, additional patch, and bundled hot fix releases, read the documentation
for all releases that have occurred since the base release before you begin installation.
Documentation for patch and bundled hot fix releases can contain critical information
related to the base release, as well as information about code changes since the base
release.
xx
Oracle Retail Documentation on the Oracle Technology Network
Documentation is packaged with each Oracle Retail product release. Oracle Retail
product documentation is also available on the following Web site:
http://www.oracle.com/technology/documentation/oracle_retail.html
(Data Model documents are not available through Oracle Technology Network. These
documents are packaged with released code, or you can obtain them through My
Oracle Support.)
Documentation should be available on this Web site within a month after a product
release.
Conventions
The following text conventions are used in this document:
Convention
Meaning
boldface
Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic
Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace
Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
xxi
xxii
1
Introduction
1
This guide is for administrators of the RPAS Server and the RPAS Classic Client.
Administrator Overview
After the RPAS Server and Classic Client have been installed, administrators must set
up the RPAS Classic Client and complete several administration activities before they
can begin using RPAS and RPAS applications. The activities include the following:
■
Domain Administration
■
User Maintenance
■
System Administration
■
Hierarchy Management
■
Data Management
■
Translation Administration
Before you start any of these activities, you should understand the basics of RPAS:
domains, workbooks, worksheets, hierarchies, and measures.
Basic Concepts of RPAS
Retail Predictive Application Server (RPAS) is a configurable platform with a proven
scalability for developing multidimensional forecasting and planning based solutions.
This platform provides capabilities such as a multidimensional database structure,
batch and online processing, a configurable slice-and-dice user interface, a
sophisticated configurable calculation engine, user security and utility functions such
as importing and exporting, all on a highly scalable technical environment that can be
deployed on a variety of hardware.
This section introduces you to the following RPAS concepts:
■
Multidimensionality
■
Hierarchies
■
Measures
■
Domains and Workbooks
Introduction 1
Basic Concepts of RPAS
Multidimensionality
In RPAS, information is stored and represented based on the multidimensional
framework. In a multidimensional database system, data is presented as a
multidimensional array, where each individual data value is contained within a cell
accessible by multiple indexes.
Multidimensional database systems are a complementary technology to entity
relational systems and achieve performance levels above the relational database
systems. Applications that run on RPAS identify data through dimensional
relationships. In RPAS, dimensions are called hierarchies. Hierarchies are qualities of
an item (such as a product, location, or time) or components of a dimension that define
the structure and roll up within the dimension.
Hierarchies
Hierarchies describe the top-to-bottom relationship between the levels or positions of
the hierarchies in RPAS. They reflect the hierarchies set up at your business and being
used by the merchandising solutions.
RPAS supports many alternative hierarchies that provide different roll ups and help
analyze the data from a different perspective.
Measures
Measures represent the events or measurements that are recorded, while the positions
in the dimensions provide a context for the measurement. Measures are defined based
on the business rules set in the application. The dimensionality of a measure is
configured through the definition of its base intersection, which is the collection of
levels (one per appropriate dimension) defining the lowest level at which the
information is stored for the measure.
Measure names are completely configurable and typically named using a convention
that identifies each component and the meaning of the measure.
Domains and Workbooks
RPAS stores information in a persistent multidimensional data cache that is optimized
for large volumes and dimensional or time series data access requirements, typically
required by multidimensional solutions. This central repository is called a domain.
The domain also includes central definitions of metadata for the solution and provides
a single update point.
When you use an RPAS solution, you interact with the solution through a personal
data repository called a workbook. A workbook contains the subset of the data (and
metadata) from the domain and its scope is constrained by the access rights available
to a user. Workbooks are stored on the RPAS server, and can be built using an online
wizard process or scheduled to be built in a batch process automatically. Workbooks
are made up of one or more worksheets. These worksheets display the hierarchy and
measure data of the domain.
Although the data and metadata in the workbook are copied from the domain, the
data remains independent of the domain.
2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Basic Concepts of RPAS
Domains can be built in one of two methods:
■
■
Simple domain - This is the traditional, stand-alone domain that has no visibility
to other domains.
Global domain - This is a domain environment that contains two or more local
domains (or sub-domains) and a master domain that has visibility to all local
domains that are part of that environment.
A global domain is a type of domain structure that provides users with the ability to
view data from multiple domains and to administer common activities of an RPAS
domain and solution.
Using a global domain environment has two primary functional benefits. The first
feature allows users to have a global view of data in workbooks. Users can build
workbooks with data from local domains, refresh global workbook data from local
domains, save global workbooks, and commit the data from global workbooks to the
individual local domains.
Local domains are typically organized, or partitioned, along organizational structures
that reflect user roles and responsibilities. Most users only work within the local
domains that contain their area of responsibilities, and they may not need to be aware
of the global domain environment. For performance and user contention reasons,
global domain usage should be limited to relatively infrequent processes that require
data from multiple local domains.
The other primary feature of global domain is centralized configuration and
administration. Most of the mechanisms that are required to build and administer a
domain have been centralized and they need only be run in the master domain, which
either propagates data to the local domains or stores the data centrally so that the local
domains reference it in the master domain.
For a global domain environment to function properly, all local domains
must be structurally identical.
Note:
Measure Data
In a global domain environment, measure data can be physically stored in two
different ways:
■
Across the local domains
■
In the master domain
Measure data that is stored in local domains is split across domains based on a
pre-determined level of a given hierarchy. This level is defined during the
configuration process, and it is referred to as the partition level.
The base intersection of a measure (for instance, what dimensions a measure contains)
determines whether data is stored in the local domains or in the master domain. The
data is stored in the master domain if the base intersection of a measure is above the
partition level or if it does not contain the hierarchy on which the global domain
environment is partitioned. This type of measure is referred to as a global domain
measure or a higher base intersection measure.
Consider a global domain environment where the partition-level is based on the
Department dimension in the Product hierarchy. Data for measures that have a base
intersection in the Product hierarchy at or below Department are stored in the local
domain based on the Department to which the underlying position in the Product
hierarchy belongs. Other hierarchies are irrelevant for this discussion.
Introduction 3
Administrative Workbooks and Wizards
However, measures that have a higher base intersection in the Product hierarchy than
Department (for instance, Division) or measures that do not contain the Product
hierarchy (such as a measure based at Store-Week) cannot be split across the local
domains. These measures will reside in the master domain and will be accessed from
there when these measures are required in workbooks.
All measures are registered in the master domain, and they are automatically
registered in all local domains. RPAS automatically determines where the measure
needs to be stored by comparing the base intersection of the measure against the
designated partition-level of the global domain environment. The physical locations of
the measure data are invisible to the user after the measure has been registered.
Administrative Workbooks and Wizards
Using the administration workbooks, designated employees manage other employees'
use of the Oracle Retail Predictive Solutions. System administrators use the
administration workbooks to perform the following:
■
Set up and maintain users and user groups.
■
Manage user access to specific workbook templates and individual measures.
■
■
Edit the contents of translation tables to support multiple-language use of the
application.
Specify the type, frequency, and format of workbooks in the automatic build
queue.
If a solution is built in a global domain environment, most
administrative activities can only be performed in the master domain.
This applies to RPAS administrative workbook templates and wizards
as well as RPAS utilities that are run on the backend against the
domain. See each workbook or workbook wizard section in this guide
for details about the domain access.
Note:
4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
2
2
Building and Upgrading Domains
This chapter describes how to build and upgrade domains.
Building a Domain
After a fully defined configuration is created, an RPAS domain can be installed. Since
building an RPAS domain is a manual process, it is expected that this process is
supported by UNIX administration if installing the domain on a UNIX platform. If the
domain is being installed on Windows servers for prototyping and demonstration
purposes, it can be built using the RPAS Configuration Tools GUI installer.
Prerequisites
The following are the prerequisites for building a domain:
■
Installation of RPAS on the server that will store the domains.
■
Installation of the Configuration Tools on the server that will store the domains.
■
A configuration built using the Configuration Tools.
■
■
A collection of hierarchy input files that contain positions for the domain. A
hierarchy data file (name.dat) is required for each defined hierarchy.
Cygwin installed (for prototyping and demonstration on Windows server only).
Client-Side Procedures
The following client-side procedures must be completed to build a domain.
To begin the domain build process, a configuration project built using the
Configuration Tools is required. This can be a packaged template or a configuration
created with the customer's specific hierarchies, measures, and workbooks. If using a
new configuration, be sure to note the path where the configuration is saved on the
local disk.
The remainder of this section assumes that the domains are
being built on a different server than Windows while the
configuration is created on the Windows platform. If the domain is
being built on the same server as the configuration, the steps
regarding adding the configuration to the zip file and transferring to a
different server can be eliminated.
Note:
Building and Upgrading Domains
2-1
Building a Domain
Zip the Configuration Project Folder
1.
Find the location where the configuration project is saved.
2.
Using Windows Explorer, go to the path of the configuration project.
3.
Right-click the Configuration folder, and select Add to Zip. Package the entire
contents of the project beginning with the configuration project root folder such
that the zip file will include all solutions. It is important to zip the entire
configuration project for the entire directory structure and not just the specific .xml
files. Do not change the name of the configuration project folder or alter the
contents of the folder in any way.
In the example below, TPGA is the configuration selected to create the TPGA.zip.
Figure 2–1 Zipping the Configuration Project Folder
4.
Using FTP, transfer the .zip file over to the server in binary mode. This can be
placed in the home directory for now.
Server-Side Procedures
The following server-side procedures must be completed to build a domain.
Though the RPAS Configuration Tools are supported only on
the Windows platforms, the installation tools are supported on all
platforms. However, they require Java 1.6. Ensure that the server
being used for the domain install has the correct version of Java.
Note:
Unzip the Configuration File
1.
Find the location where to save the configuration project file.
Always put an updated configuration project in a new
directory path. Do not overwrite an existing configuration project.
Note:
2.
Move the <Configuration Project>.zip file to this location.
3.
Unzip the <Configuration Project>.zip file using the UNIX command:
unzip -a <Configuration Project>.zip
4.
Do not change the directory name for the configuration project or alter the
contents in any way.
Verify the Environment Variable Settings
Prior to this step, RPAS and the Configuration Tools should be installed on the server
that will store the domains. During that process, the necessary environment variables
for RPAS and the Configuration Tools should be defined. Refer to the Appendix:
Environment Variables if the environment variables below have not been set up.
2-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Building the Domain Manually or Through a Command-Line Interface
Log in to the server. Use the commands below to verify the environment settings:
echo
echo
echo
echo
$RPAS_HOME
$RIDE_HOME
$JAVA_HOME
$PATH
The path for the RPAS_HOME variable may change with each
new RPAS release.
Note:
If any changes are made to the environment variable settings, remember to exit and
restart the UNIX session in order to execute the corrected .profile. This step is very
important before continuing with the remaining steps.
Get the Input Files Ready
1.
Designate a directory for the location of the input files, and move the files into this
directory.
As a recommendation, use the directory name to_rpas as a
standard for the location of input files. At a minimum, the hierarchy
files (product, location, and calendar hierarchy files) are needed to
build the domain. At this time, a calendar file must be loaded.
Note:
2.
If necessary, rename the hierarchy files to match the name of the configured
hierarchies. The files need to end in either .dat or .csv.dat. For example, a file for a
configured product hierarchy named prod in the Configuration Tools should be
either prod.dat prod.csv.dat. When using the .dat extension, the format of the files
must match the hierarchy configuration specified using the Configuration Tools. If
using the .csv.dat extension, the files will contain fields that are comma separated.
See the Loading Hierarchies - loadHier section for more details.
Building the Domain Manually or Through a Command-Line Interface
Run the rpasInstall utility to build the domain. This executable is located in the
path to $RIDE_HOME/bin.
rpasInstall
This section provides the details required for the upgrade of rpasInstall.
rpasInstall Usage
rpasInstall <arguments>
The following table provides descriptions of the arguments used by the rpasInstall
utility.
Building and Upgrading Domains
2-3
Building the Domain Manually or Through a Command-Line Interface
Table 2–1
Arguments Used by the rpasInstall Utility
Argument
Description
[-fullinstall |
-patchinstall |
-testinstall]
Required argument. Indicates the type of installation to be
performed, where:
■
■
■
-fullinstall - Builds a full domain and loads the
hierarchy data files.
-patchinstall - Patches an existing domain. Updates or
unregisters/registers measures that have changed (as
necessary).
-testinstall - Used for testing only. Only generates
configuration files.
-ch config_home
Required argument. Path to the directory containing the
configuration file.
-cn config_name
Required argument. The name of the configuration.
-in input_home
Required argument. Path that includes the directory containing
the input files for the domain to be created.
If this directory includes a users.db file, then the users and
groups within that file are added upon domain creation. For
more information, see Managing Users - usermgr Utility.
-log log_name
Required argument. Path that includes the name of the log file
to be created or updated.
-configdir config_
directory
The path to the directory containing the xml files used by RPAS.
This is a required argument if the user wants to supply
globaldomainconfig.xml or calendar.xml.
-dh domain_home
The path to directory in which the domain will be created. Use
if and only if a globaldomainconfig.xml is not used.
-p dim_name
The partitioning dimension. Use if and only if global domain is
being implemented without the use of globaldomainconfig.xml.
-rf function_name
The filename of the function to be registered. This pairing may
be repeated for multiple functions. This argument is not
required if there are no functions to be registered.
-updatestyles
Imports configured style information into the domain. This
option is automatically set in a full install. Failure to use this
flag in a patch install will result in changes to configured styles
not being imported into the domain.
Notes: When you build a domain for the first time, an installs
directory is created inside the domain. The installs directory is
essential for the patch process and should not be removed, moved, or
renamed.
When you send in an issue to Oracle Retail Customer Support, if
asked to provide a domain, be sure to provide the installs directory as
well. The following information should be provided in order to help
Customer Support better diagnose the issue:
■
The configuration
■
The script used to run the rpasInstall script
■
The domain
■
The log output file
2-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
Validate Domain Build Results
After the domain build process is complete, the logfile should be reviewed to verify
that the process executed successfully. Search for the words "ERROR," "FAILURE," and
"exception" inside the logfile. The end of the logfile should look similar to the output
below:
Time: 58.451
COMPLETE
After Building the Domain
After building the domain, the domain can be accessed by the RPAS Classic Client.
Building a domain creates the shell of the domain. All
measures, rules, and workbooks are created, but the measures are not
populated. Measures are populated with the loadmeasure utility. For
more information, see Loading Measure Data - loadmeasure.
Note:
In order to connect to a domain, the domain information must be set with the RPAS
EConfigure utility and the RPAS DomainDaemon must be running. See the RPAS
Installation Guide for details on setting up the domain information. See the Domain
Daemon section for information.
Before you can log into the new domain, you must create at least one user with the
usermgr utility. After you have created one user, you can use the Add User workbook
to create others. For more information about the usermgr utility and creating users, see
the User Maintenance chapter.
After logging into the domain and creating the appropriate users, ensure that the
appropriate permissions to workbooks and measures are set. See the Security
Administration Workbook section for more information.
Upgrading and Patching Domains
RPAS supports the upgrade of RPAS 11.0.x, 11.1.x, and 12.x environments to RPAS
13.x.
See the solution-specific installation and
implementation/operations guides for potential solution upgrade
limitations.
Note:
For details on upgrading to this release of RPAS from any release of RPAS prior to 13.3,
see Upgrading From Any Release of RPAS Prior to 13.3.
For details on upgrading to this release of RPAS from RPAS 13.3 or later, see
Upgrading From RPAS 13.3 or Later.
Upgrading From Any Release of RPAS Prior to 13.3
If you are upgrading to the current release of RPAS from any release prior to RPAS
13.3, complete the following steps.
You must first upgrade the domain to the latest 13.2.3 hotfix prior to starting this
upgrade process.
Building and Upgrading Domains
2-5
After Building the Domain
To upgrade to the latest RPAS 13.2.3 hot fix, see the 13.2.3
RPAS Administration Guide for the Classic Client, section "Upgrading
and Patching Domains." Note that it is optional to perform Step 8 in
that section. Step 8 states that you should run the rpasInstall
utility with the -patchinstall argument. This is not necessary if
you are upgrading to this release because you will run that utility and
argument at the end of this section.
Note:
Domain Conversion
In RPAS 13.3, a new methodology called Integer Indexing was introduced to simplify
the management of multidimensional data in an RPAS domain. Integer indexing aims
at eliminating a lot of inefficiencies in the addition, removal, and reclassification of
positions in a hierarchy and improving the performance of hierarchy operations.
Since integer indexing uses different internal data structures to manage the hierarchy,
a pre-13.3 domain must be converted to the new format before it can be recognized by
the newer version of RPAS. This conversion is accomplished by using the
convertDomain utility.
Domain conversion is an elaborate and complex process that runs on the assumption
that the source domain is in a good state free of system level inconsistencies. In reality,
an existing domain may be in an undesirable state due to various reasons. This can
cause the domain conversion process to fail.
The information in this chapter can help you when upgrading to RPAS 13.3 or later. It
provides general guidelines for RPAS domain conversion. It covers the preparation of
the domain, setting up the conversion parameters, and carrying out the conversion
and post-conversion processing.
Domain Preparation Before Conversion
The diagram below shows an overview of the domain preparation that is necessary
before running domain conversion. All these utilities must be run under the RPAS
13.2.3 hotfix version 13.2.3.36 or later.
2-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
Figure 2–2 Overview of Domain Preparation
The procedure is as follows:
1.
Upgrade the domain to the latest 13.2.3 hot fix.
RPAS supports the upgrade of RPAS 12.x environments to RPAS 13.x. If the
domain is not currently on the latest 13.2.3 hot fix, it must be upgraded to that hot
fix first before upgrading to 13.3.
To upgrade to the latest RPAS 13.2.3 hot fix, see the 13.2.3 version of the RPAS
Administration Guide for the Classic Client, section"Upgrading and Patching
Domains" on page 2-5. Note that it is optional to perform Step 8 in that section.
Step 8 states that you should run the rpasInstall utility with the -patchinstall
argument. This is not necessary if you are upgrading to 13.3 because you will run
that utility and argument at the end of this section.
In addition, refer to the solution-specific Installation Guide, Implementation
Guide, and Operations Guide, as appropriate, for potential solution upgrade
limitations.
2.
Run scanDomain to repair array corruption.
The scanDomain utility can be used for repairing data corruption in an RPAS
database. Data corruption can occur if an external program modifies the RPAS
database files or an unforeseen defect occurs in the processes using the RPAS
database.
To run the utility from the command line, do the following:
scanDomain -d domainPath -repairCorruption -processes N
Building and Upgrading Domains
2-7
After Building the Domain
For more information about scanDomain, see the 13.2.3 release of the RPAS
Administration Guide for the Classic Client.
3.
Run fixDomain to detect metadata errors.
The Fix Domain utility is a new tool used to detect and fix data inconsistencies in a
domain. It supports a few different types of "tasks" to analyze different areas of
data in the domain. Task "RepairMetadata" is used to detect and repair metadata
inconsistencies.
To run the utility from the command line, do the following:
fixDomain -d domainPath -task RepairMetadata
By default, this utility only reports errors without making changes to the domain.
All errors are reported to standard output, which can be directed to a file.
4.
Run fixDomain to fix metadata errors.
Run fixDomain again in the commit mode to actually fix the metadata errors in the
domain.
To run the utility from the command line, do the following:
fixDomain -d domainPath -task RepairMetadata -commitChanges
Some metadata discrepancies can be too severe to fix. For example, discrepancies
between the system arrays dim_hier and hierinfo cannot be fixed by the utility. It
is recommended that you run fixDomain in report mode (without the
-commitChanges flag) again to detect any remaining errors. Contact RPAS
technical support if there are still errors.
Caution: Note that fixDomain may remove measures from the
domain if the metadata for those measures are corrupted. This may
prevent some workbooks from being built. If this happens, the
missing measures should be re-registered in the domain.
5.
Run fixDomain to check and rebuild change arrays.
Change arrays are system arrays used by the reshapeArrays utility. They should
be rebuilt in case they are out of sync with other domain data, which can cause the
failure or partial failure of the reshapeArrays.
To run the utility from the command line, do the following:
fixDomain -d domainPath -task RepairChangeArrays -commitChanges
6.
Run reshapeArrays to fix dimension inconsistencies.
This cleans up potential dimension inconsistencies between data arrays and
dimension dictionaries.
To run the utility from the command line, do the following:
reshapeArrays -d domainPath -registered -force -processes N
7.
Run scanDomain to generate a list of likely unused databases.
An existing RPAS domain can accumulate a lot of unused databases during the
course of its history. If those databases are not excluded from the domain
conversion process, at a minimum they can slow down the conversion
considerably, and, worse yet, they can cause the conversion to fail if any of the
2-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
data arrays in them is corrupt. The scanDomain utility has been enhanced to list
all likely unused databases of the domain. Best efforts have been applied to
generate a complete and accurate list. However, some databases may have been
created by custom RPAS extension libraries or third party plug-ins and can be
listed as unused by mistake. This list should be examined and corrected if
necessary.
To run this utility from the command line, do the following:
scanDomain -d domainPath -listUnusedData outputFile
Setting up Domain Conversion Parameters
The convertDomain utility can take three configuration input files: a hierarchy
configuration file, an optional global domain configuration file, and an optional
database exclusion file. The diagram below shows an overview of setting up these
files. All utilities should be run under RPAS 13.3 hotfix version 13.3.0.17 or later, RPAS
13.3.1 hotfix version 13.3.1.5 or later, or RPAS 13.4 or later.
Figure 2–3 Setting Up Domain Conversion Parameters
The procedure is as follows:
1.
Run convertDomain to generate a suggested bit size for each user dimension.
To run the utility from the command line, do the following:
convertDomain -src domainPath -suggestDimBitSize outputFile
See the "convertDomain"section for more information on using the
suggestDimBitSize option.
2.
Run ConfigTools to upgrade the domain configuration and to set the bit sizes.
Use the RPAS Configuration Tools to upgrade the 13.2.3.x domain configuration to
13.3, setting the bit size for each dimension. (Bit size configuration has an impact
Building and Upgrading Domains
2-9
After Building the Domain
on performance. See the "Defining Dimension Properties" section in the RPAS
Configuration Tools User Guide for instructions on setting the bit size and reindex
threshold.)
At this point, no additional changes should be made to the configuration; those
changes must be processed separately at a later stage in the process. Solutions that
include plug-ins that are normally run as part of the domain upgrade process will
also be handled later.
3.
Export the hierarchy.xml file from the updated configuration.
This file can be created by running the hierarchy.xml report from within the Report
Generator of the RPAS Configuration Tools.
4.
Construct the database exclusion file (optional).
An existing domain may contain a lot of stale or obsolete databases in it that can
hinder the domain conversion progress. During the domain preparation, the
scanDomain utility can be used to generate a list of likely unused databases. After
confirmation, these databases can be put in an XML file that can be named
exclusionList.xml.
See "convertDomain" on page 2-16 for more information on the use of exclusion
lists.
5.
Construct the global domain XML configuration file (optional).
If you are converting a global domain, and not all local domains reside under the
global domain path, then an XML configuration must be constructed to specify the
source and destination path for each local domain.
See "convertDomain" on page 2-16 for more information on domain.xml
configuration files.
Running the Domain Conversion
Once the domain has been prepared and all input parameters have been generated, the
domain can be converted using the convertDomain utility. This utility will create a
new integer indexing domain rather than updating the existing pre-integer indexing
domain. This new domain can then be used to finish the upgrade process.
See "convertDomain" on page 2-16 for more information on using the convertDomain
utility.
Post-Conversion Processing
After the domain has been successfully converted to integer indexing, some
post-conversion processing steps, as shown in the following diagram, are required to
bring the domain up to date.
2-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
Figure 2–4 Post-Conversion Processing
To run post-conversion processing, do the following:
1.
Run fixDomain to fix unlinked arrays.
If any arrays are listed in the unlinkListFile during the domain conversion, they
must be fixed by running the fixDomain utility. The "FixArrays" task fixes
unlinked arrays that contain one or more dimensions that are not linked to the
dimension registry.
See "fixDomain" on page 2-21 for more information on fixing unlinked arrays.
2.
Upgrade the domain to the current RPAS version.
The upgradeDomain utility is used to upgrade just the RPAS version of the
domain. It does not update the configuration or any other aspects of the domain
itself. Refer to "upgradeDomain" on page 2-20 for more information.
3.
Upgrade the domain configuration.
Run the new version of the Configuration Tools to upgrade existing configurations
to the latest version. Those changes should be made to the configuration modified
in the Step 2 of the "Setting up Domain Conversion Parameters". Refer to"Upgrade
Configurations" on page 2-14 for more information.
4.
Patch the domain.
Running the patch installation through rpasInstall over the converted domain is
required even if there are no configuration updates. Refer to "rpasInstall" on
page 2-3 for more information.
Building and Upgrading Domains 2-11
After Building the Domain
Upgrading From RPAS 13.3 or Later
If you are upgrading to the current release of RPAS from RPAS 13.3 or later, complete
the following steps.
Figure 2–5 shows an overview of the upgrade and patching process. The detailed steps
are shown below the figure.
Figure 2–5 Upgrade Process from RPAS 13.3.x
1.
Acquire the latest 13.4.0.x RPAS release and install the following components:
■
RPAS Server
■
RPAS Client (Classic or Fusion)
■
RPAS Configuration Tools
If using rsp_manager to install an RPAS 13.3.x patch, the
-no_domain option should be used.
Note:
2.
Run the upgradeDomain utility to complete the conversion of the domain to the
current release. See the upgradeDomain section for more information.
3.
Make any additional configuration changes to the domain (such as the
re-execution of plug-ins for applications that require the plug-ins to be run and
applied through a patch install as part of an upgrade).
4.
If any additional changes were made to the domain in step 3, those changes
should now be applied to the upgraded domain. To apply these changes, run the
rpasInstall utility with the -patchinstall argument. See the rpasInstall
section for more information.
2-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
Notes: After running the upgradeDomain utility, the patch
installation (through rpasInstall) must be run over the domain
even if there are no configuration updates. This is done to ensure that
configuration within the domain is synchronized with any changes
made as the result of the RPAS and Configuration Tools upgrade.
When using the -updatestyles flag, deleting existing styles is not
necessary.
Updating Domain Content
When moving to a new version of RPAS and RPAS solutions, you can also update the
content of the domain. For example, the content of workbooks can be modified or the
business logic represented by a rule group can be updated.
To update the domain content, make the desired changes in the configuration using
the RPAS Configuration Tools. Then, when you run the -rpasInstall utility with
the -patchinstall argument, the changes are applied to the domain.
The sections below specify the restrictions and special cases for updating hierarchies,
measures, rule groups, and workbooks.
Hierarchies
When patching a domain, new hierarchies can be added. A hierarchy file must be
present in the input directory specified in the call to rpasInstall for that hierarchy to be
added.
Although a new hierarchy can be added, the order of the
existing hierarchies cannot be changed. However, the order of the new
hierarchy can be between or after existing hierarchies.
Note:
Patching a domain upgrades some, but not all, hierarchy and dimension attributes. For
existing hierarchies, only the security dimension is updated. For dimensions, the
following attributes are updated: user-defined dimensions, labels, and the state of
image support (enabled or disabled). In addition, a dimension can have DPM support
and translation support enabled but not disabled. You can also change the bit size and
reindex threshold of an existing dimension (see Reindexing Domains -reindexDomain)
as well as add or rename dimensions (see Adding New Dimensions).
Patching a domain does not patch changes to the hierarchy purge age, or change the
multi-language setting for a domain.
If updating the hierarchy purge age inside an existing domain,
use the loadHier utility in batch mode to update the current settings.
See the Loading Hierarchies - loadHier section for more information.
Note:
Measure Properties
Certain measure properties cannot be modified without un-registering and
re-registering the measures, which results in the loss of measure data. The measure
properties that are able to be modified without being reregistered are listed in the
Register Measure - regmeasure Utility section. If all of the measure properties that are
changed are able to be modified without reregistration, the measure data will not be
lost in the domain during the patch process.
Building and Upgrading Domains 2-13
After Building the Domain
If even one of the measure properties that change is not able to be modified without
reregistration, the patch process results in the un-registration and re-registration of the
measure. Therefore, the data that was in the domain for that measure before the patch
process will not be there after the patch process is complete. For more information, see
the Register Measure - regmeasure Utility section.
Rule Groups
As part of the patch installation process, rule groups can be deleted, created, or
modified with no restrictions. During the patching process, the rule sets, rule groups,
and rules are completely rebuilt.
Workbooks
As part of the patch installation process, workbooks can be deleted, created, or
modified with no restrictions.
If you remove a template from the configuration and then
patch the domain, the formatting for that template will be deleted.
Note:
Upgrade Configurations
After the RPAS Configuration Tools have been installed and the domains have been
upgraded, you may need to upgrade existing configurations to version 13 or the latest
version 13 patch.
Configuration upgrade is not always required. When it is
required, the Configuration Tools automatically notifies you that a
configuration upgrade is needed.
Note:
1.
Launch the new version of the Configuration Tools.
2.
Open the existing configuration by selecting Open from the File menu.
3.
Select the configuration and click OK.
4.
A message box appears prompting you to convert the configuration. Click Yes.
Figure 2–6 Converting the Configuration
5.
The Backup Location message box appears. Click OK to continue.
2-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
Figure 2–7 Choosing the Backup Location
6.
The administrator must now specify a location to store the backup of the current
(non-upgraded) configuration. Use the browser to identify a location and enter the
back-up configuration name. The backup may be stored in the same location as the
configuration being upgraded only if the name of the backup is changed from its
original name.
The Successful Conversion dialog box appears if the configuration was converted
without any issues.
Figure 2–8 Confirmation of Conversion
7.
The upgraded configuration will now be open in the Configuration Tools. Changes
can now be made to the configuration. Note that if changes are made the domain
must be updated through the normal patch install process.
Note: If upgrading RDF, Grade, or Curve, see Upgrade Application
Configurations for additional steps to complete the application
upgrade.
Command-line Support for Configuration Upgrading
The RPAS Configuration Tools also provides command-line support to upgrade
configurations. The Configuration Converter is a standalone utility that converts a
configuration that was originally created and saved in a prior release of the
Configuration Tools. Only configurations created in a prior major release need to be
converted. Configurations saved in previous versions of the same major release, but in
different minor releases, do not need to be converted. See the RPAS Configuration Tools
Guide for more information on using the Configuration Converter (RpasConverter.exe)
through the command-line.
Note: If upgrading RDF, Grade, or Curve, see Upgrade Application
Configurations for additional steps to complete the application
upgrade.
Building and Upgrading Domains 2-15
After Building the Domain
Upgrade Application Configurations
Applications such as RDF, Curve, and Grade are configured using a plug-in
architecture in the RPAS Configuration Tools. This architecture allows for the
automation of most configuration activities for the solution. The plug-in requests
specific information from the configuration administrator and the solution
auto-generation tool automatically generates the solution configuration. Prior to each
patch or upgrade to a major release, the auto-generation tool should be executed to
ensure the solution configuration is updated with the base configuration changes for
the application.
Updating the solution configuration for each application should be done in the
following order:
1.
Curve
2.
RDF
3.
RDF Clone
4.
Promote
5.
Grade
See the RDF, Curve, or Grade Configuration Guides for more information on the
auto-generation process for each application.
convertDomain
The convertDomain utility creates a new domain that has all the dimensions and
measure arrays converted to integer-indexed arrays.
The conversion process creates a new domain based on the source domain provided.
Since a new domain is created from the domain and does not replace the source
domain, the source domain remains unaffected.
Because you are creating a second domain, you must have
enough space for the original source domain and the new converted
domain. Since workbooks are not converted, you only need the
amount of space the source domain uses, minus the space that the
workbooks in the source domain use.
Note:
The convertDomain utility copies all information specific to the domain at the time of
conversion. It does not copy any custom information such as shell scripts, which exist
under the domain root. Such information must be manually copied.
The convertDomain utility blindly copies the following:
■
config (to master domain only)
■
input
■
installs
■
output
■
repos
■
scripts
■
fusionClient
■
WizardPQD
2-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
The data directory is recreated base on the source domain. Only databases (.db) are
converted, excluding the following:
■
changearray.db
■
shadow.db
■
styles.db
■
hmaint.db (which is completely rebuilt separately)
■
measdata.db (also rebuilt separately)
■
master_staging.db (use only for loadhier)
■
alitemp*.db
You can also use an exclusion list to exclude more databases from the conversion.
If files exist in the data directory but are not a database, they are not copied.
The users directory is recreated without all workbooks. Therefore, for all users’
directory structures will only contain the <username>.db and <username>.db.lck files.
The styles directory is copied conditionally. Only style files listed in #workbook.xml
are copied. Any arrays that exist in that directory are ignored.
If your domain contains files or directories that are not copied (based on the
information above), those files and directories must be manually copied to the
converted domain.
The convertDomain utility can be run multiple times if
needed. Data already converted will be skipped for the second and
each subsequent run.
Note:
convertDomain Usage
convertDomain
[-src srcDomain -dest destDomain | -xmlConfigFile XMLConfigFile]
-xmlHierFile PathToHierarchy.xml [-exclude exclusionList.xml] -genUnlinkedList
unlinkedListFile -maxProcesses count
To use the convertDomain utility, perform the following steps:
1.
Provide a pair of source/destination domain paths using the -src and -dest
arguments. Or, supply an XMLConfig file.
■
■
■
If you use -src and -dest arguments to specify the source and destination
domain paths, the local domain path must be under the global domain path.
If converting a global domain, and not all local domains reside under the
global domain path, then you must use the -xmlConfigFile argument to
specify the source and destination path for each local domain.
The XMLConfigFile should follow this syntax:
Building and Upgrading Domains 2-17
After Building the Domain
<rpas>
<globaldomain>
<srcPath>/path/to/13.2.3/domain</srcPath>
<dstPath>/path/to/13.3.0/destination</dstPath>
<subdomain>
<srcPath>/path/to/13.2.3/local/domain/0</srcPath>
<dstPath>/path/to/13.3.0/destination/local/domain/0</dstPath>
</subdomain>
...
</globaldomain>
</rpas>
2.
Use the -xmlHierFile to specify the path to the hierarchy.xml file that is
exported from the upgraded configuration, including new BitSize attribute for
each dimension.
3.
If it is desired, the -exclude argument may be used to specify databases that
should be excluded from the conversion process. The databases specified in the
exclusionList.xml document will not be recreated in the new integer indexing
domain. The exclusionList.xml should use the following format. Note that if the
path is an absolute path (starting with a slash "/"), it refers to only one directory. If
it is a relative path, it applies to the master domain and all local domains in a
global domain environment.
<rpas>
<convertDomain option="exclude">
<path>relative/path/to/database1.db</path>
<path>relative/path/to/database2.db</path>
<path>/absolute/path/to/database.db</path>
…
</convertDomain>
</rpas>
4.
Under certain conditions, an array in a pre-integer indexing domain can become
corrupted such that the embedded dimension information of the array does not
match the dimension information contained in the dimension dictionary of the
domain. These arrays are called unlinked arrays. When convertDomain is run
with the -genUnlinkedList argument, it creates a file in the specified location
containing any arrays in which this corruption has occurred. The fixDomain utility
can then be used to bring these unlinked arrays into conformity with the domain.
See "fixDomain" on page 2-21 for more information on restoring unlinked arrays.
5.
Use the -maxProcesses argument to specify the number of processes can be
used.
The following table provides descriptions of the arguments used by the
convertDomain utility.
Table 2–2
Arguments Used by the convertdomain Utility
Argument
Description
-src srcDomain
Specifies the path to the source domain being converted.
-dest destDomain
Specifies the path to the destination domain.
-xmlConfigFile
XMLConfigFile
If you are converting a global domain and not all local domains
reside under the global domain path, use this argument to
specify the source and destination paths for each local domain.
2-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
After Building the Domain
Table 2–2 (Cont.) Arguments Used by the convertdomain Utility
Argument
Description
-xmlHierFile
PathToHierarchy.xml
Specifies the path to the hierarchy.xml file that is exported from
the upgraded configuration. This file should include the new
BitSize attribute for each dimension.
-exclude exclusionList.xml
Excludes the databases listed in the specified file from the
conversion process.
-genUnlinkedList
unlinkedListFile
Creates a file in the specified location containing the names of
arrays whose embedded dimension information does not match
the dimension dictionary of the domain. These arrays can then
be corrected using the fixDomain utility.
-maxProcesses count
If specified, some parts of convertDomain will run in parallel,
meaning that it will use a maximum of the defined processes,
which are specified by count.
Note: upgradeDomain is not called by this process. It must be
called separately. This allows the user to specify additional parameters
to upgradeDomain. Once the domain has been converted and
upgraded, it is ready for use.
convertDomain -suggestDimBitSize
The convertDomain utility can also be used to analyze a pre-integer indexing domain
in order to suggest appropriate values for the bitSize attributes of the dimensions in
that domain.
The convertDomain utility enumerates all non-system dimensions in the source
domain, calculates a suitable bit size based on the current number of positions
(including unused buffer positions) within the domain, and prints them out in a table
format. It then calculates the key size for each of the data arrays for all measures,
based on those dimension bit sizes. If the key size is above 64 bit for any measure, it
will print out the measure with a warning message so that the user can consider a
lower bit size for any of the dimensions in the array.
The algorithm for suggesting the bit size is to find the number of bits that can fit twice
the number of positions currently in the dimension, starting with 2 bits. The results of
the analysis are output to a file. Below is an example of this output:
Hierarchy
Dimension
Size
BitSize
Capacity
DPM-Enabled
clnd
day
3647
13
8192
No
clnd
week
522
11
2048
No
loc
str
22
6
64
Yes
loc
dstr
12
5
32
No
prod
sku
488
10
1024
Yes
prod
stco
258
10
1024
Yes
Building and Upgrading Domains 2-19
After Building the Domain
The following measures have a key size greater than 64 bits.
For better performance, it is recommended to reduce the bit size of
one or more dimensions in the base intersection of these measures so
that the key size is within 64 bits.
Note:
Measure Name
Base Intersection
Key Size
ACT
www_xxx_yyy_zzzz
67
Usage for -suggestDimBitSize
convertDomain -src domainPath -suggestDimBitSize outputFile
The following table provides descriptions of the arguments used by the
convertDomain utility with -suggestDimBitSize.
Table 2–3
Arguments Used by the convertDomain Utility with suggestDimBitSize
Argument
Description
-src domainPath
Path to the domain being analyzed.
-suggestDimBitSize
outputFile
Location in which to create output file containing bitSize
recommendations.
upgradeDomain
The upgradeDomain utility is used to upgrade just the RPAS version of the domain. It
does not update the configuration or any other aspects of the domain itself.
upgradeDomain Usage
upgradeDomain -d domainPath [OPTIONS]
The following table provides descriptions of the arguments used by the
upgradeDomain utility.
Table 2–4
Arguments Used by the upgradedomain Utility
Argument
Description
-d path
Path to the domain being upgraded.
-verbose
Optional parameter to show the detail about each change that is
applied to the domain.
-n
Optional parameter to report which changes would be applied
without applying the changes.
-purgeWorkbooks
Optional parameter that purges all existing workbooks and
clears the workbook batch queue.
-ignoreSharedNames
Allow upgrade even if dimensions and hierarchies share names.
-apptag
Indicate the application and version associated with this
upgrade. Parameter must be APP:VERSION.
2-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
fixDomain
Note: An administrator can also run the domaininfo utility to
verify the upgrade process as shown below.
domaininfo -d pathtodomain -domainversion
fixDomain
The fixDomain utility is used to repair many types of corruption that can occur within
an RPAS domain. This utility can be used to perform a number of tasks, which are
described below. In all cases, fixDomain can execute in two modes. The default mode
is to perform an examination to detect problems. The second mode, which is
performed if the -commitChanges argument is passed in the call to fixDomain, is to
take action to correct problems that are detected.
Remove inconsistent measure attributes
It is possible for inconsistencies in measure attributes between the master and local
domains of a global domain to interfere with operations performed by RPAS. By
executing fixDomain with the CleanMeasureAttrs task, users can analyze a domain for
such discrepancies and correct them by removing attributes that appear in only a
subset of the domains.
Remove partially unregistered measures
It is possible for the process of measure un-registration to exit without completely
removing the measure from all local domains of a global domain. By executing
fixDomain with the CleanMeasure task, users can analyze a domain for partially
unregistered measures and correct them by completing the un-registration process and
completely removing these measures from the domain.
Repair discrepancies in hierarchy information
It is possible, in integer-indexing domains, for the hierarchy and dimension
information of an array to become out of synch with the information of the domain. It
is also possible for this information to become out of synch between the local domains
of a global domain. By executing fixDomain with the RepairHiearchy task, users can
analyze a domain for desynchronized dimension information and correct it when
found by updating arrays or local domains with the dimension information of the
master domain.
Repair unlinked arrays
In pre-integer indexing domains, there may be discrepancies between the dimension
information in an array and the dimension information of the domain. When these
corrupted domains are converted to integer indexing, these arrays are converted to
rely on internal dimension information and cannot be resolved against the dimension
information of the domain. By executing fixDomain with the FixArrays task, users can
analyze a domain to detect these unlinked arrays and correct them by rebuilding the
array using the dimension information of the domain.
Repair metadata inconsistencies
System dimensions and related metadata define the basic structure of a domain. Any
discrepancies within them can cause serious problems during domain operations. By
executing fixDomain with the RepairMetadata task, users can analyze a domain for
any discrepancies in system dimensions. Depending on the type of information that
contains a discrepancy, fixDomain may or may not be able to resolve the issue.
Building and Upgrading Domains 2-21
fixDomain
Hierarchy and Dimension information.
In general, this type of discrepancy is a result of a domain that did not build correctly.
Due to the severity of this type of problem, fixDomain cannot resolve such issues.
Measure information.
It is possible for measure information to appear in some but not all the metadata
arrays of a domain. Depending on which arrays do contain information about a
measure, fixDomain may be able to correct the problem. Otherwise, the measures with
incomplete information will be removed from the domain and must be re-registered.
Workbook information.
It is possible for information about workbooks, workbook templates, and workbook
template groups to appear in some but not all of the metadata arrays of the domain.
Depending on which arrays do contain information about the workbook, template or
group, fixDomain may be able to correct the problem. Otherwise, the workbooks,
templates or groups with incomplete information will be removed from the domain
and must be re-registered.
User information
It is possible for information about RPAS users and user groups to appear in some but
not all of the metadata arrays of the domain. Depending on which arrays do contain
information about the user or group, fixDomain may be able to correct the problem.
Otherwise, the user or group will be removed and must be re-registered.
The RepairMetadata task is only supported in versions of
13.2.3.x after 13.2.3.36. It cannot be used in RPAS version 13.3 and
later. It is described here to support the upgrade and conversion
process. See"Upgrading From Any Release of RPAS Prior to 13.3" on
page 2-5 for more information on the convertDomain process.
Note:
Repair corrupted change arrays
In pre-integer indexing domains, it is possible for change arrays to become out of
synch with the measure metadata of a domain. By executing fixDomain with the
RepairChangeArrays task, users can analyze a domain for any discrepancies between
change arrays and measure metadata and repair them, based on the measure metadata
of the domain.
The RepairChangeArrays task is only supported in versions of
13.2.3.x after 13.2.3.36. It cannot be used in RPAS version 13.3 and
later. It is described here to support the upgrade and conversion
process. See "Upgrading From Any Release of RPAS Prior to 13.3" on
page 2-5 for more information on the convertDomain process.
Note:
fixDomain Usage
The following arguments are used with fixDomain:
fixDomain -d pathToDomain -task CleanMeasure [-commitChanges] [-loglevel level]
fixDomain -d pathToDomain -task RepairHierarchy -hier hierName [-commitChanges]
[-loglevel level]
fixDomain -d pathToDomain -task FixArrays [-db dbName | -array arrayName]
[-commitChanges] [-loglevel level]
fixDomain -d pathToDomain -task RepairMetadata [-dim dimName] [-commitChanges]
[-loglevel level]
2-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
fixDomain
fixDomain -d pathToDomain -task RepairChangeArrays [-commitChanges] [-loglevel
level]
The following table provides descriptions of the arguments used by the fixDomain
utility.
Table 2–5
Arguments Used by the fixDomain Utility
Argument
Description
-d pathToDomain
The location of the domain begin repaired.
-d CleanMeasureAttrs
Detects and removes measure attributes that do not exist in
master and all local domains of a global domain.
-task CleanMeasure
Detects partially unregistered measures and completes their
un-registration.
-task RepairHierarchy Detects and repairs inconsistencies in hierarchy information in
arrays within master and local domains of a global domain.
-hier hierName
Used in conjunction with the Repair Hierarchy task. Specifies
the hierarchy to correct within arrays.
-task FixArrays
Detects and corrects unlinked arrays.
-db dbName
Used in conjunction with the FixArrays task. Specifies the
database to examine or repair. The FixArrays task requires the
use of either the -db or the -array argument, but not both.
-array arrayName
Used in conjunction with the FixArrays task. Specifies the array
to examine or repair. The FixArrays task requires the use of
either the -db or the -array argument, but not both.
-task RepairMetadata
Detects and repairs metadata discrepancies in system
dimensions. Note: the RepairMetadata task is supported only
in versions of 13.2.3.x after 13.2.3.36. It cannot be used in RPAS
version 13.3 and later.
-dim dimName
Used in conjunction with the RepairMetadata task. Specifies the
system dimension to examine or repair. This is an optional
argument. If not supplied, fixDomain will examine all system
dimensions.
-task
RepairChangeArrays
Detects problems in change arrays within the domain and
repairs them by relying on the measure metadata of the domain.
Note: the RepairChangeArrays task is supported only in
versions of 13.2.3.x after 13.2.3.36. It cannot be used in RPAS
versions 13.3 and later.
-commitChanges
If the -commitChanges argument is not supplied to any call of
fixDomain, it will only examine the domain and report detected
problems. fixDomain only modifies the domain to repair
changes if the -commitChanges argument is specified.
-loglevel level
Sets the logging verbosity level. Supports use of all, profile,
debug, audit, information, warning, error and none as values of
level.
Building and Upgrading Domains 2-23
fixDomain
2-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
3
Domain Administration
3
This chapter describes domain administration tasks such as configuring the Classic
Client and using domainDaemon.
Configuring the Classic Client - eConfigure
This section provides instructions for configuring the RPAS Classic Client with the
eConfigure utility on a local computer using a Microsoft Windows operating system.
The eConfigure utility is a Windows application that configures the client-server
communication for RPAS. EConfigure lets you specify communication parameters and
produces a file that is used as input to the client. These files must be in FCF
(Foundation Configuration File) format/extension. The files contain the necessary
information for the client to start up the communication with the server. These files
can be stored on the client machine or on the network.
When the client is executed, a file named Foundation.FCF is expected in the same
directory. If the file has a different name or if it is stored somewhere on the network,
the path to this file must be passed in as an argument to the client.
EConfigure consists of a menu bar, a main view, and the advanced settings dialog
window. Passwords saved in the FCF file are encrypted. To launch EConfigure,
double-click the EConfigure.exe file, which is by default located in the root directory of
the RPAS Classic Client.
eConfigure Menu Bar
The files produced by EConfigure may contain multiple connections. Each connection
will be specific for a server with certain communication settings. Connections need to
have unique descriptions, and they can be added and deleted using the menu bar.
Figure 3–1 eConfigure Menu Bar
Domain Administration
3-1
Configuring the Classic Client - eConfigure
eConfigure Main View
The main view has the basic connection parameters, as shown in Figure 3–2.
Figure 3–2 eConfigure Utility
■
■
■
■
■
■
Database Server: The hostname or the IP address of the server, for example,
atldev03 or 10.2.1.23. This value should be localhost when running the RPAS
Server on a Windows machine.
Daemon Port: The port number on which the domain daemon is listening. This
must be an integer between 1025 and 65535 (for example, 55278).
Oracle Wallet for SSL: The Oracle Wallet stores the SSL credentials. You must
provide the path where the wallet is stored. This information is only required if
one-way SSL is used. If SSL is disabled or if anonymous SSL is being used, then
the wallet is not required. For more information, see Chapter 4, "SSL."
Domain: The name of the domain that is displayed to the user when logging in.
Select a domain from the list or type the name of a new domain and click Add
Domain. You can delete a domain from the list by selecting it and then clicking
Delete Domain.
Domain Path: The full path to the directory containing the domain, for example,
/root/testenv/domain/Sample_Project
User: Provide the user ID if you do not want to force the user to provide it when
logging in. The user ID must be defined in the associated domain. Note that the
password cannot be entered here. The user must enter the password manually
each time the RPAS client starts the connection.
3-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Configuring the Classic Client - eConfigure
Advanced Settings Dialog
Click the Advanced button shown in Figure 3–3 to access the Advanced Settings
dialog window.
Figure 3–3 Advanced Settings Dialog
■
■
User: The database user that is used by the client if a domain specific user has not
been entered, for example, adm.
Database Port Range Start and End: Port range is used to specify the range of ports
on which the RPAS Server processes is started by the DomainDaemon (the
rpasDbServer processes). The port Start and port End fields are the lower and
upper limits of this range respectively.
These fields must be integers between 1025 and 65535, which are also the default
values if values are not specified, for example, Start: 40000, End: 45000.
■
■
■
Compression Threshold: The number of bytes above which client and server are
using compression. Only advanced users should manipulate this number.
Web Tunneling: The configuration of Web tunneling.
Proxy Settings: The configuration of the RPAS Classic Client to support a proxy
server is not completed in this utility.
Domain Administration
3-3
Domain Daemon
Domain Daemon
The RPAS DomainDaemon is a process that is used to enable the communication
channel between RPAS Clients and RPAS domains.
The DomainDaemon runs on the server side and waits for requests from RPAS Clients
on a given port. After DomainDaemon receives a request from a client, it starts a
server process that the client connects to. From this point, the client and server
communicate directly. The system administrators may choose to have one single
DomainDaemon process for all of the users, or they may choose to have separate
processes per domain, per enterprise, and so on.
The DomainDaemon is installed in the [RPASDIR]/bin directory. [RPASDIR] stands
for the full path to the directory where the RPAS Server is installed.
On rare occasions, the Domain Daemon can throw the
following exception when SSL is enabled: Failed to initialize Oracle
SSL environment (nzerror 43120: NZERROR_LX_ERROR).
Note:
It is caused by an unmatched language setting of the operating
system. Setting the environment variable NLS_LANG using the
following command before starting the Domain Daemon will resolve
this problem.
export NLS_LANG=AMERICAN
DomainDaemon Usage
The following table provides descriptions of the arguments used by the
DomainDaemon utility.
Table 3–1
DomainDaemon Arguments
Argument
Description
-version
Prints the RPAS version, revision, and build information of the
utility.
-start
Starts a DomainDaemon on the specified port.
-port portNum
The portNum must be between 1025 and 65535 (inclusive). If
portNum is set to auto, it will find any free port.
-loglevel
This option enables additional logging.
Note: The -debug option has been deprecated. Instead of using
-debug, please use -loglevel to add additional logging.
-timeout milliseconds
Specifies the number of milliseconds to wait for the server to
start. A value of -1 means no timeout.
-server
serverProgramName
Specifies the name of the RPAS database server program.
Defaults to RpasDbServer.
-no_auto_add
Disables the registering of domains in response to client
requests to start a RPAS database server.
-stop
Stops the DomainDaemon on the specified port.
-ping
Reports the status of a DomainDaemon process.
-showDomains
Shows all domains managed by this daemon.
-add pathToDomain
Adds the specified domain to the list of domains managed by a
DomainDaemon.
3-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Domain Daemon
Table 3–1 (Cont.) DomainDaemon Arguments
Argument
Description
-activate pathToDomain
Reactivates a previously deactivated domain. Specify the port
number and the complete path to the domain.
-deactivate
pathToDomain
Marks a domain as temporarily unavailable. Deactivating a
domain also terminates all user sessions in that domain. A
message will be displayed in the client to notify users when this
occurs. Domains are most commonly deactivated before
beginning a routine nightly/weekly batch process. This ensures
that no users make updates to the system during these
processes. Specify the port number and the complete path to the
domain.
-remove pathToDomain
Removes the specified domain from the list of domains
managed by a DomainDaemon.
-showActiveServers
Shows all active server processes. Specifying a port number is
required.
For each active server, the DomainDaemon shows the process
ID, domain, and user ID.
-stopActiveServers
Stops all active servers. Specify a port number and a process ID.
-stopServer processId
Stops the server using the specified processed.
-stopUser userId
Stops the server using the specified userId.
-ssl
Specifies whether the messages exchanged between the Classic
Client and the RPAS database server are encrypted using a
password generated during the initial SSL handshake.
Here are the options for SSL:
0 - Disables SSL support. This option provides no authentication
and no encryption.
1 - This option provides one-way authentication and encrypted
data transfer.
3 - This option provides encrypted data transfer without
authentication.
-wallet
Specifies the location of the server wallet folder. The wallet
contains the RPAS server's private key and certificate and the
client's certificate. This is optional; it depends on which SSL
option you are using.
Format -wallet file:<path to the server wallet folder>
Example: -wallet file:d:\wallets\server [on Windows]
on Unix: -wallet file:/u00/admin/wallets/server
Starting the DomainDaemon
To start the DomainDaemon, execute the DomainDaemon utility. The port number
where the DomainDaemon will be running must be passed in as an argument. The
port number must be between 1025 and 65535. If auto is specified instead of a number,
the DomainDaemon is started on any available port.
Issuing the following command from a UNIX shell starts a DomainDaemon on port
55278:
DomainDaemon -port 55278 -start
If the command is successful, the DomainDaemon returns the following message:
Daemon listening on port ’55278’.
Domain Administration
3-5
Losing a Client-Server Connection
The proper environment variables must be set in order to
execute the DomainDaemon. See the Verify the Environment Variable
Settings for more information about setting RPAS_HOME and
updating the PATH variable.
Note:
Monitoring the DomainDaemon
The -ping argument can be used to see whether a DomainDaemon is active. The port
number must also be passed as an argument. If the DomainDaemon is active on the
port, a message will be printed, and the script will return true. Otherwise, the script
will return false.
DomainDaemon -port 55278 -ping
DomainDaemon on port 55278 is alive.
Stopping the DomainDaemon
Use the -stop argument to stop the DomainDaemon running on a given port.
DomainDaemon -port 55278 -stop
Losing a Client-Server Connection
The connection between the RPAS Client and the RPAS Server can be lost for any
number of reasons, but most commonly when the user's computer crashes or the
network connection is lost.
If an RPAS Client-Server connection is lost, the user's work is guaranteed to be saved
up to the last calculation; all deferred calculations are lost. Upon subsequent login, the
user can access either the last version of the original workbook explicitly saved by the
user or the auto-saved version of the workbook that was being worked on when the
connection was lost.
If the user tries to log in after recently losing the connection or from a different
instance of the RPAS client, the user is prompted to either terminate all existing
sessions and start a new session, or start a new concurrent user session. If the user
chooses to terminate the existing session, the RPAS server gracefully terminates the
existing session and then logs the user in and starts up a new session.
Graceful Termination of the Existing Session
If a connection has been lost and the previous session has not timed out or a session
for the user is running from a different instance of the RPAS client, the user can use the
RPAS client to gracefully terminate the existing session and log in to a new session.
Graceful termination includes the completion of any pending processes and custom
menu or rule group processing in the existing session, followed with an auto-save of
the workbook and subsequent termination of the server process.
Graceful termination of an existing session could take an arbitrarily long time. This
time is equal to the sum of the time taken to complete any running calculations and
then save the workbook.
When the RPAS server times out waiting on a request from the RPAS Client, it
gracefully terminates, irrespective of whether the user tried to log in again.
3-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Losing a Client-Server Connection
If for any reason the client server connection is lost before the new login occurs, RPAS
asks users if they want to resume the previous session or terminate it and start a new
one. However, it will not start another session for the user until the user regains
connectivity and tries to log in again.
There is a limit on the number of login sessions per user. By default, the maximum
number of concurrent login sessions per user is five. This limit can be altered by an
administrator using the Security Administration workbook.
Autosave of Workbooks
When an RPAS Server session terminates automatically, either due to re-login or a
server timeout, it auto-saves the workbook that is currently open by the session. An
auto-saved workbook includes all of the user's work up to the last calculation. If the
user had some pending calculations, that is, edits were made in the client but
calculation was not performed, all the edits are lost.
When a workbook is auto-saved, the original workbook is kept in the same state it was
in the last time it was explicitly saved by the user. A new workbook is created for the
user with the name of the original workbook suffixed with '_autosave' and added to
the user's Most Recently Used list. Upon subsequent login, the user can view both the
original workbook and auto-saved workbook in the workbook list.
RPAS administrators can impose a limit on the number of workbooks a user can create
for a particular workbook template. When such a limit has been imposed, the
auto-save feature allows the user to exceed that limit by one. This allows the user to
operate at the limit without the fear of losing any work because of a connection failure
or computer crash. However, when the limit is exceeded due to an auto-save, the
auto-save feature is disabled for the user for the workbook template on which the limit
has been imposed. The auto-save feature is disabled until the user deletes one or more
of the workbooks for that template in order to bring the user at or below the limit. It is
not required that the user delete the original or the auto-saved workbook. After the
user is back at or below the limit, the auto-save feature is automatically enabled. Note
that if a user exceeds the limit, the RPAS Client will inform the user of this situation
every time the user attempts to open a workbook for the given template.
Domain Administration
3-7
Losing a Client-Server Connection
3-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
4
SSL
4
Secure Socket Layer (SSL), a protocol for securing network connections, is used by
RPAS to provide secure communication between RPAS client and server processes.
RPAS Classic Client supports one-way SSL and SSL without authentication.
This chapter contains the following:
■
Introduction
■
One-Way SSL
■
SSL Without Authentication
■
Disabling SSL
Introduction
In order to use SSL with RPAS, you must configure both the server and the client. For
one-way and two-way SSL, this involves setting up key stores and trust stores used to
manage certificates. The key store contains a private key and its corresponding public
certificate chain. The trust store contains trusted public certificates and certificate
chains. SSL without authentication does not require digital certificates on either the
client side or the server side.
In order to enable the use of SSL on RPAS, you must use the Domain Daemon to set up
the SSL type and the Oracle wallet location (which is optional for certain SSL types).
Oracle Wallet is managed by a command line utility called orapki, which is included in
the RPAS installation.
A Certificate Authority (CA) certificate is the public certificate from the CA that issues
the server certificate.
One-Way SSL
In one-way SSL, the client asks to verify the identity of the server. The server does not
ask to identify the client, but does require application-level authentication.
SSL 4-1
One-Way SSL
Figure 4–1 RPAS One-Way SSL Configuration
One-way SSL only authenticates the server on the client side. Only the server needs to
have a key store for its private key and digital certificate. RPAS server uses Oracle
Wallet for this purpose.
The trust store on the client side is an Oracle wallet for the Classic Client. The trust
store needs to contain the server CA certificate so that the client can recognize and
authenticate the server certificate.
Creating a Self-Signed Root Certificate
A self-signed root certificate can be used instead of a third-party CA certificate (for
example, for testing).The same root certificate can be used to generate both server and
client certificates.
Under cygwin environment on Windows, the path of the
wallet must be in Windows format, not cygwin format. For example, it
must be C:/wallets/root, not /cygdrive/c/wallets/root.
Note:
To create a self-signed root certificate, complete the following steps:
1.
Create an Oracle wallet.
orapki wallet create -wallet {root_wallet_directory} -pwd {root_wallet_
password}
Example:
orapki wallet create -wallet C:/wallets/root -pwd rootpass1
2.
Generate a private key and a self-signed root certificate.
orapki wallet add -wallet {root_wallet_directory} -keysize {key_len} -dn {root_
dn} -self_signed -validity {validity_days} -pwd {root_wallet_password}.
4-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
One-Way SSL
Example:
orapki wallet add -wallet C:/wallets/root -keysize 2048 -dn "cn=rpas_qa_
ca,dc=us,dc=oracle,dc=com" -self_signed -validity 3650 -pwd rootpass1
3.
Export the root certificate chain to a file for later use.
orapki wallet export_trust_chain -wallet {root_wallet_directory} -certchain
{root_cert_chain_file} -dn {root_dn} -pwd {root_wallet_password}.
Example:
orapki wallet export_trust_chain -wallet C:/wallets/root -certchain
C:/wallets/root_chain.txt -dn "cn=rpas_qa_ca,dc=us,dc=oracle,dc=com" -pwd
rootpass1
Configuring the RPAS Server
To configure the RPAS server for one-way SSL, you must set up a key store and then
start the Domain Daemon.
Setting Up the Key Store
To set up the key store, complete the following steps:
1.
Create an Oracle wallet with auto login. This type of wallet can be read without a
password. The default file permissions for the wall are 0300 (accessible by owner
only).
orapki wallet create -wallet {server_wallet_directory} -auto_login -pwd
{server_wallet_password}
Example:
orapki wallet create -wallet C:/wallets/server -auto_login -pwd serverpass1
2.
Generate a private key.
orapki wallet add -wallet {server_wallet_directory} -keysize {key_len} -dn
{server_dn} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -keysize 2048 -dn "cn=rpas_qa_
server,dc=us,dc=oracle,dc=com" -pwd serverpass1
3.
Export a certificate request.
orapki wallet export -wallet {server_wallet_directory} -dn {server_dn} -request
{server_cert_req_file} -pwd {server_wallet_password}
Example:
orapki wallet export -wallet C:/wallets/server -dn "cn=rpas_qa_
server,dc=us,dc=oracle,dc=com" -request C:/wallets/server_cert_req.txt -pwd
serverpass1
4.
The certificate request must be digitally signed before it can be used. If the
deployment of the RPAS Fusion client and the RPAS server are both under the
control of the customer, then a self-signed SSL certificate may be used as the
signer. Otherwise, the certificate request must be sent out for signing by a
well-known certificate authority.
SSL 4-3
One-Way SSL
A self-signed SSL certificate used in this manner may be referred to as a
self-signed root certificate or as a private certificate authority.
This is the method for creating a self-signed root certificate:
1.
Generate a private key for the root certificate:
orapki wallet add -wallet {root_wallet_directory} -keysize {key_len} -dn
{root_dn} -self_signed -validity {validity_days} -pwd {root_wallet_
password}
Example:
orapki wallet add -wallet C:/wallets/root -keysize 1024 -dn
"cn=root,dc=us,dc=example,dc=com" -self_signed -validity 3650 -pwd
rootpass1
2.
Export the root certificate chain to a file:
orapki wallet export_trust_chain -wallet {root_wallet_directory} -certchain
{root_cert_chain_file} -dn {root_dn} -pwd {root_wallet_password}
Example:
orapki wallet export_trust_chain -wallet C:/wallets/root -certchain
C:/wallets/root_chain.txt -dn "cn=root,dc=us,dc=example,dc=com" -pwd
rootpass1
In the above example, the file containing the root certificate chain is
c:/wallets/root_chain.txt.
5.
If using an external root certificate, create the server certificate signed by a
third-party CA. (Alternatively, see step 6.) To do this, send the server certificate
request file ({server_cert_req_file}) to the CA. The CA sends back a
certificate ({server_certificate_file}) for the server, along with the public
certificate ({root_cert_chain_file}) of the CA.
6.
If using a self-signed root certificate, the server certificate file is signed as follows:
orapki cert create -wallet {root_wallet_directory} -request {server_cert_req_
file} -cert {server_certificate_file} -validity {validity_days} -pwd {root_
wallet_password}
Example:
orapki cert create -wallet C:/wallets/root -request C:/wallets/server_cert_
req.txt -cert C:/wallets/server_cert.txt -validity 3650 -pwd rootpass1
The file c:/wallets/server_cert.txt is the signed server certificate, in the form of a
file.
7.
Import the CA into the server wallet. Note that the public certificate chain may
contain more than one certificate. In such cases, the certificates must be imported
one by one, starting at the top of the chain.
orapki wallet add -wallet {server_wallet_directory} -trusted_cert -cert {root_
cert_chain_file} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -trusted_cert -cert
C:/wallets/root_chain.txt -pwd serverpass1
4-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
One-Way SSL
8.
Import the server certificate into the wallet.
orapki wallet add -wallet {server_wallet_directory} -user_cert -cert {server_
certificate_file} -pwd {server_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/server -user_cert -cert C:/wallets/server_
cert.txt -pwd serverpass1
Starting the Domain Daemon
To start the domain Daemon using one-way SSL, execute the following command,
where <walletLocation> is the absolute path to the directory of the Oracle wallet.
DomainDaemon -port portNum -ssl 1 -wallet file:<walletLocation> -start
Configuring the Classic Client
To configure the Classic Client for one-way SSL, you must set up a trust store. To do
this, create an Oracle wallet on the client. Then, import the CA into the wallet. Since
the trust store does not contain any private keys, it can be shared by all Classic Clients.
It can either be copied to every client machine or placed in a shared network location
that is accessible by the client machines.
Once you have set up the trust store, you must configure the Classic Client connection
so that the wallet can be used by the client.
1.
Create an Oracle wallet with auto login.
orapki wallet create -wallet {client_wallet_directory} -auto_login -pwd
{client_wallet_password}
Example:
orapki wallet create -wallet C:/wallets/client -auto_login -pwd clientpass1
2.
Import the CA from the server into the wallet. Note that the public certificate
chain may contain more than one certificate. In such cases, the certificates must be
imported one by one, starting at the top of the chain.
orapki wallet add -wallet {client_wallet_directory} -trusted_cert -cert {root_
cert_chain_file} -pwd {client_wallet_password}
Example:
orapki wallet add -wallet C:/wallets/client -trusted_cert -cert
C:/wallets/root_chain.txt -pwd clientpass1
3.
Configure the Classic Client connection by entering the path for the location of the
wallet into the Oracle Wallet for SSL dialog box, which is part of the EConfigure
configuration utility (shown in Figure 4–2).
The wallet can be a directory on a local drive or on a network computer.
Examples:
A wallet on the C drive: C:/wallets/client.
A wallet on a shared directory called "shared" of a server called "server123::
//server123/shared/wallets/clients.
SSL 4-5
One-Way SSL
Figure 4–2 EConfigure Utility
Use the following dialog box to browse for the wallet location.
Figure 4–3 Select Oracle Wallet Location Dialog Box
Once this configuration is complete, you can start the Classic Client as usual. It
automatically detects the SSL type and uses the wallet specified in the connection
configuration (Step 3 above).
When you are using SSL, you see a secure lock icon on the status bar at the bottom of
the client window.
4-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
One-Way SSL
Script for Creating Self-Signed Wallets
The createSSLWallets.sh script is provided to automate the creation of Oracle wallets
for self-signed certificates. The script creates both server and client wallets for RPAS
server and classic client.
Usage for createSSLWallets.sh
The createSSLWallets.sh script is an interactive one that prompts the user for inputs. It
does not take any command line arguments. The shell to start the script must have
access to the orapki utility that is deployed under the bin directory of RPAS home.
User Input
The script requires the following user input:
The directory for the wallets
This is the location for the wallets. A directory named "rpaswallets" is created to store
all wallets under this given directory. If a directory "rpaswallets" already exists, the
script will stop and ask the user to remove that directory. This is to ensure that some
old stale wallets do not become mixed up with the new wallets.
By default, the current directory is used if not given.
Organization name
The user is asked to enter an organization name that is used as part of the DN
(Distinguished Name) of the certificate identities.
By default, the organization name is "My Company, Inc.".
The passwords for root wallet, server wallet, and client wallet
Each password must be entered twice. Basic validation is done to ensure that the user
has entered matched passwords and that the password is not empty.
Output
The script displays every step it takes to create the wallets and certificates. There are
totally 17 steps. The orapki command line for each step is displayed with password
masked out. The output of the orapki command is displayed to the user and thus any
error message from orapki is also displayed.
If the script finishes successfully, it will display the locations of the root wallet, server
wallet, and client wallet. Since RPAS Domain Daemon only takes absolute path for the
wallet, these locations will show as absolute paths.
Error Handling
The script checks the output of every orapki command and stops when it encounters
an error. Appropriate error message are displayed to the user.
RPAS Web Launch
To use RPAS Web Launch with one-way SSL support, you must specify the location of
the wallet in the field labeled Oracle Wallet for SSL. Since this domain configuration is
shared by all users, a network location must be used for the wallet or the wallet must
reside at the same location across all client PCs.
SSL 4-7
SSL Without Authentication
Figure 4–4 RPAS Web Launch for Classic Client
The wallet location can also be specified in the <Client> section of the XML file used
for In-context Launch, in the setting called sslWalletLocation. For example:
<Client>
<version>13.3.1</version>
<sslWalletLocation>//ntserver02/shared/wallets/client</sslWalletLocation>
</Client>
SSL Without Authentication
SSL without authentication (also known as anonymous SSL) does not require a digital
certificate on either the client side or the server side.
An anonymous Diffie-Hellman (DH) key exchange protocol is used to generate and
exchange a secret session key for use in the encryption and decryption of the traffic to
achieve confidentiality.
No additional configuration is needed for RPAS Classic Client. It automatically
recognizes the type of SSL and chooses the corresponding cipher suite.
SSL without authentication is considered to be a security risk. If you are using SSL
without authentication, you will see the following warning message regarding this
risk:
Warning: The client/server network communication is using SSL without
authentication, which is prone to man-in-the-middle attacks.
4-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Disabling SSL
RPAS Server Configuration
Use the following command to start the Domain Daemon using SSL without
authentication:
DomainDaemon -port portNum -ssl 3 -start
Disabling SSL
Disabling SSL is not recommended. If you disable SSL, your
network communication is not secure.
Note:
To start the Domain Daemon with SSL disabled, use the following command:
DomainDaemon -port portNum -ssl 0 -start
You see the following warning message:
Warning: The client/server network communication is not protected by SSL.
When SSL is disabled, you see an unlock icon on the status bar at the bottom of the
client window.
SSL 4-9
Disabling SSL
4-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
5
User Maintenance
5
User administration is the process by which administrators add or delete authorized
system users, create or delete user groups, and edit user profiles. These tasks are
performed through completion wizards on the User Administration tab.
The following user administration procedures are discussed in this chapter:
■
Add User
■
Add User Group
■
Delete User
■
Delete User Group
■
Edit User
These procedures can be performed through the RPAS Classic Client by accessing the
User Administration tab in the New Workbook window (Figure 5–1).
In addition, the usermgr utility is also described in this chapter. This utility allows you
to manage users and users groups through a command line interface. For more
information, see the Managing Users - usermgr Utility section.
After users and user groups are set up, access permissions to workbook templates and
measures within workbooks can be assigned through the Security Administration
workbook. The Security Administration workbook also supports modification of the
label, default workbook template, and admin status associated with individual users.
User Maintenance
5-1
Access the User Administration Tab
Access the User Administration Tab
User administration workbooks are available only in a master domain of a global
domain environment. To access the User Administration workbooks:
1.
Select New from the File menu. The New dialog box appears.
2.
Select the User Administration tab.
Figure 5–1 User Administration Tab in New Workbook Window
5-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Add User
Add User
To add a user, perform the following steps:
1.
From the File menu, select New.
2.
Click the User Administration tab.
3.
Select Add User and click OK.
4.
The Add User Wizard appears.
Figure 5–2 Add User Wizard
Enter relevant information in the following fields:
■
User name - Type the user name that the user will use for logging on.
Note: Each user name must begin with a letter and contain only
alphanumeric characters and underscores. It cannot have spaces. User
names are case-sensitive.
■
■
User label - Type a label that describes the user (for example, the user's full
name). This identifying label appears in various locations throughout the
application. For example, labels appear on the Open dialog box to identify the
owner of a given workbook, and on some worksheets to specify which user
performed a task.
Default group - Select the user group to which the user will belong.
User Maintenance
5-3
Add User
■
5.
Other groups - If a user will belong to more than one group, select the
additional groups from the list in the Other groups field.
■
Password - Type a password for the user.
■
Password Verification - Type the same password.
If the user should have Admin status, check the Administrator box.
Admin status enables users to perform the Format menu
option Save Format/Admin, which creates new system-wide default
styles for workbook templates. If unsure whether a user should be
granted this ability, note that a user's Admin status can later be
modified on the Users worksheet of the User and Template
Administration workbook.
Note:
Granting users Admin status gives them access to all
workbook templates, but it does not automatically give them access to
all workbooks.
Note:
6.
If the user must change his or her password when logging on for the first time,
check the Force Password Change box.
7.
Check the Lock User Account box to temporarily disable the user's account.
8.
Click Finish to add the new user to the database.
Workbook template and measure access rights can now be assigned to the user. To do
so, access the User and Template Administration workbook. For more information, see
the Security Administration Workbook section.
5-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Add User Group
Add User Group
User groups provide an intermediate level of security to workbooks that were created
and saved by specific users. When new users are assigned to the system, they must be
assigned to existing user groups. User groups should consist of individuals with
similar job functions or responsibilities. In the Oracle Retail Predictive Planning Suite,
the user group corresponds to the user's planning role.
1.
Select New from the File menu.
2.
Click the User Administration tab.
3.
Select Add User Group and click OK.
4.
The Add User Group Wizard appears.
Figure 5–3 Add User Group Wizard
Enter information in the following fields:
■
In the Group Name field, type a name for the group.
Each group name must begin with a letter and contain only
alphanumeric characters and underscores. It cannot have spaces. User
group names are case-sensitive.
Note:
■
5.
In the Group Label field, type a descriptive label for the group. This label is
displayed when referring to the group throughout RPAS.
Click Finish to add the user group to the database.
User Maintenance
5-5
Delete User
Delete User
If a user profile is no longer needed, it should be deleted from the system in order to
maintain system security.
1.
From the File menu, select New.
2.
Click the User Administration tab.
3.
Select Delete User and click OK.
4.
The Delete User Wizard appears. The user names and labels for all users appear.
Select the name of the user to delete.
Figure 5–4 Delete User Wizard
5.
Click Finish to delete the user from the system.
5-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Delete User Group
Delete User Group
If a user group no longer exists, the group should be deleted from the system as soon
as possible to maintain system security.
Before you can delete a user group, all users must be removed
from the group. For each user in the group, you must either delete the
user or change the default user group assignment for the user.
Note:
1.
From the File menu, select New.
2.
Click the User Administration tab.
3.
Select Delete User Group and click OK.
4.
The Delete User Group Wizard appears. Select the user group to delete.
Figure 5–5 Delete User Group Wizard
5.
Click Finish to delete the user group from the system.
User Maintenance
5-7
Edit User
Edit User
To edit a user’s profile, perform the following steps:
1.
From the File menu, select New.
2.
Click the User Administration tab.
3.
Select Edit User and click OK.
4.
The Edit User Wizard appears. The User ID field displays the user names and
labels for all users. Select the user to edit and click Next.
Figure 5–6 Edit User Wizard
5-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Edit User
5.
The Edit User Wizard appears. Make the necessary changes to the user's profile.
You can change everything except the User Name. See "Add User" for details.
Figure 5–7 Edit User Wizard, Page 2
6.
Click Finish to save the changes.
User Maintenance
5-9
Managing Users - usermgr Utility
Managing Users - usermgr Utility
Use the usermgr utility to add and remove users and groups, copy user and group
information to other domains, edit user and group information, and convert that
information from XML files to database files and vice versa.
With the usermgr utility, you can create user and administrator accounts using the addGroup command. This allows you to add many accounts at once. When you create
accounts, you must supply a temporary password that is used for all user accounts
and a temporary password that is used for all administrator accounts. These
temporary passwords expire the first time the user or administrator logs in.
Note that you can only create temporary passwords; you cannot create real ones. This
is in order to protect the security of the user and administrator accounts. For the same
reasons, the default accounts "adm" and "usr" are no longer available.
To create users and groups, you must create a database file called users.db, which
contains user and group information. After you have created and imported the
users.db file into RPAS, it contains all user, administrator, and group information,
including the true passwords for each account. This file is an encrypted binary file that
you cannot edit.
To edit any account information, you must convert the database file to an XML file
using the -convertDbToXml command. This creates an editable XML file that
contains all the information in the user.db file except for the true passwords of the
accounts. Again, this is to ensure the security and safety of the account information.
After you edit the XML file with the changes you need to make, you must convert it
back to a database file in order to import it into RPAS. To convert it, use the convertXmlToDb command.
After the users.db file is created, it can be shared across multiple domains. To
automatically import the user, administrator, and group information every time a
domain is created, place the users.db file in the rpasInstall input directory of the
domain.
usermgr Usage
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
usermgr
-d domainPath -add [userName] -label [label] -group [groupName] {-admin}
-d domainPath -addGroup [groupName] -label [label]
-d domainPath -remove [userName]
-d domainPath -removeLabel [label]
-d domainPath -removeGroup [groupName]
-d domainPath -list
-d domainPath -print -user [userName]
-d domainPath -print -group [groupName]
-d domainPath -importDb {-replace}
-d domainPath -exportXml [path]
-d domainPath -exportDb [path]
-d domainPath -lock [userName]
-d domainPath -unlock [userName]
-convertXmlToDb -src [pathToXml] -dest [pathToDb]
-convertDbToXml -src [pathToDb] -dest [pathToXml]
Note: -convertDbToXml and -convertXmlToDb do not require a
domain.
5-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Managing Users - usermgr Utility
The following table provides descriptions of the arguments used by the usermgr
utility.
Table 5–1
Arguments Used by the usermgr Utility
Argument
Description
-d domainPath
Specifies the path to a domain to add, remove, or get
information about a user.
-add userName
Use this argument to add a user with a specified name.
Use the other arguments specified in the usage to add those
attributes for that user.
This prompts you to enter the temporary password for the user.
-label label
Use this argument to specify the label of the user or group to
add to the domain.
Use this argument with -add and -addGroup.
-group grp
Use this argument to specify the user group of the user to add to
the domain.
-admin
Use this argument to specify that the user to add to the domain
has administrative rights.
-addGroup groupName
Use this argument to add a group with a specified name.
Use -label to specify the label for the group.
-remove userName
Use this argument to remove the user with the specified name
from the domain.
-removeLabel label
Use this argument to remove all users with this label.
-removeGroup
groupName
Use this argument to remove a group with this groupName.
-list
Use this argument to list all the users registered to the specified
domain.
-print
Use this argument to print the specified user or group
information.
-user username
Use this argument to specify the user name in the specified
domain to print.
This argument is only applicable to -print option.
-group groupname
Use this argument to specify the group in the specified domain
name to print.
This argument is only applicable to -print option.
-importDb
Use the argument to import the database. The database must be
located in the domain's input directory. The database is time
stamped and moved to the processed directory upon successful
completion.
Existing user are skipped unless -replace is used.
-replace
Use this argument to update existing users when using importDb.
The user label, groups that user belongs to, admin status, and
account lock status is updated. Password information is not
affected by the update.
-lock userName
Use this argument to lock the specified user. This prevents the
user from logging in the domain.
-unlock userName
Use this argument to unlock the specified user. This allows the
user to log in the domain.
User Maintenance 5-11
Managing Users - usermgr Utility
Table 5–1 (Cont.) Arguments Used by the usermgr Utility
Argument
Description
-exportXml path
Use this argument to create an XML file that contains all users
and groups in the selected domain. Passwords and password
histories are not exported.
-exportDb path
Use this argument to create a database that contains all users
and groups in the selected domain. This prompts you for new
temporary passwords for admin and user accounts.
-convertDbToXml
Use this argument to convert a user database to a user XML file.
Passwords are not included in the conversion.
-convertXmlToDb
Use this argument to convert a user XML file to a user database.
This prompts you for temporary passwords for admin and user
accounts.
-src path
Use this argument to specify the source file used in
-convertDbToXml and -convertXmlToDb.
-dest path
Use this argument to specify the destination file used in
-convertDbToXml and -convertXmlToDb.
XML Schema
The XML schema contains information for all groups and users that are imported into
the domain. Since this file can be edited, it does not contain any password information.
Each group and user contains an XML attribute with the group or user name as well as
the following inner tags:
Table 5–2
XML Schema
Outer Tag
Inner Tag
Description
GROUP
LABEL
The group's label.
USER
LABEL
The user's label.
USER
DFLT_GRP
The user's default group.
USER
OTHER_GRPS
A comma-separated list that
contains all other groups
that the user is associated
with.
USER
ADMIN
If this value contains T, this
user is an admin.
USER
LOCKED
If this value contains T, the
user is locked when the file
is imported.
Note:
All XML tags must be in all caps.
5-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Managing Users - usermgr Utility
Below is a sample users.xml file.
Figure 5–8 Sample users.xml File
User Maintenance 5-13
Managing Users - usermgr Utility
Use Cases
Below is a list of common use cases for the XML and database files.
Exporting from an Existing Domain
You can export from an existing domain using -exportDb or -exportXml. Exporting is
useful for sharing users with another domain or for creating backups.
Use -exportXml if you need to edit the users or groups. This can be used when you are
making bulk updates that apply to many users or groups. After you have made
changes to the file, you must convert it back to a database by using the convertXmlToDb and then import the updated file using -importDb -replace.
Use -exportDb if you do not need to edit the users or groups. This method produces a
binary file that is ready for import.
Importing into a Domain
You can import existing users.db by using -importDb. Importing is useful for bulk
insertion or updates of users and groups.
By default, existing users and groups are skipped. However, if -replace is used,
existing users are updated with the following information: user label, groups that the
users belong to, admin status, and account lock status. Group labels are updated for
existing groups.
Password information for existing users is not affected by the update. New users
receive temporary passwords that are stored in users.db.
Note that new users may not be created if the following conditions exist:
■
A group already exists with the user name.
■
If the user's default group does not exist.
New groups are skipped if the following conditions exist:
■
A user already exists with the group name.
If a users.db is placed inside the rpasInstall input folder, the
users within that file are automatically imported upon domain
creation.
Note:
5-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Managing Users - usermgr Utility
Converting Between XML and Database
Since only users.xml can be edited and only users.db can be imported, it is necessary
to convert between the two formats when you need to edit and import users and
groups. For example, if you are creating users for the first time, you must first create
those users an XML file. Then you must convert that XML file to a database file using
-convertXmlToDb in order import the file. If you have an existing users.db that you
need to edit, convert it to xml using -convertDbToXml.
When converting from an XML to a database file, the following validation rules apply:
■
The file must be a properly formatted XML file, otherwise the operation fails.
■
Groups and users without a NAME attribute are skipped.
■
■
Duplicate groups and users are skipped. Duplicate groups and users are those that
share the same NAME attribute of an existing group or user within the same XML
file. For instance, a new group called Sales cannot be created if a user or group
named Sales already exists.
Users without a DFLT_GRP field are skipped.
If a user or group is skipped, a warning is logged. Since
warnings are not included in the default log level, you should run this
utility with warnings visible.
Note:
User Maintenance 5-15
Managing Users - usermgr Utility
5-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
6
System Administration
6
This chapter describes the following system administration workbooks and wizards:
■
Auto Workbook Maintenance Wizard
■
Workbook Batch Category Management
■
Hierarchy Maintenance Workbook
■
Password Policy Administration Workbook
■
Security Administration Workbook
■
Measure Analysis Workbook
These workbooks and wizards are found in the Administration tab and Analysis tab of
the New workbook window.
Figure 6–1 System Administration Workbooks and Wizards
Note: The Alert Manager Wizard is described in the RPAS User Guide
for the Classic Client. The Translation Administration workbook is
described in the Internationalization chapter.
System Administration 6-1
Auto Workbook Maintenance Wizard
When working with a global domain, some administration workbooks are available
only in the master domain. These workbooks are the following:
■
Hierarchy Maintenance
■
Password Policy Administration
■
Security Administration
■
Translation Administration
■
Workbook Batch Category Management
All other administration workbooks are available in both the local and master
domains.
Auto Workbook Maintenance Wizard
The Workbook Auto Build feature allows users to have workbooks built by the wbmgr
utility. Workbooks built in this way are added to the auto build queue. When
workbooks are built in this manner, users are spared the processing time of making
selections in the wizard and waiting for the workbook to build. The Workbook Auto
Build feature works through the Auto Workbook Maintenance Wizard.
Add a Workbook to the Auto Build Queue
Workbooks in this queue are designated to be built automatically on a specified
regular basis as part of the nightly batch run.
1.
Select New from the File menu.
2.
The New workbook window appears. Select the Administration tab.
3.
Select Auto Workbook Maintenance and click OK.
4.
The next wizard page appears. Select Add a Workbook and click Next.
5.
Select a workbook template type, and click Next.
6.
Select an owner for the workbook, and click Next.
6-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Auto Workbook Maintenance Wizard
7.
The last page of the wizard appears.
Figure 6–2 Auto Workbook Maintenance Wizard
Enter the following information:
■
■
■
■
■
■
8.
Build Label: A relevant name for the auto workbook build.
Build frequency (in days): The frequency that the workbook should be build
in days.
Next Build Date: The next date that the workbook should be built.
Category: Select the category of workbooks that this workbook should be
assigned to. For more information about categories, see the Workbook Batch
Category Management section.
Saved Access: The level of access for this workbook. Choose User, Group, or
World.
Group: Select the group that owns the workbook.
Click Next to initialize the wizard for the workbook template selected in step 5.
The choices made are saved under the name specified for the Build Label.
System Administration 6-3
Auto Workbook Maintenance Wizard
Delete a Workbook from the Auto Build Queue
To delete a workbook from the Auto Build Queue, perform the following steps:
1.
Select New from the File menu.
2.
The New workbook window appears. Select the Administration tab.
3.
Select Auto Workbook Maintenance and click OK.
4.
The next wizard page appears. Select Delete Workbooks and click Next.
5.
Select the workbook or workbooks to delete from the auto build queue.
6.
Click Finish to delete the workbooks from the Auto Workbook Build queue.
Edit Workbook Settings
To edit the settings of an auto build workbook, perform the following steps:
1.
Select New from the File menu.
2.
The New workbook window appears. Select the Administration tab.
3.
Select Auto Workbook Maintenance and click OK.
4.
The next wizard page appears. Select Edit Workbook Settings and click Next.
5.
Select OK and click Finish to build the Auto Workbook Maintenance workbook.
6.
The Edit Auto Workbook Settings worksheet opens. Edit the settings as necessary.
When finished, save and commit the workbook.
Figure 6–3 Edit Auto Workbook Settings Worksheet
6-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Workbook Batch Category Management
Workbook Batch Category Management
A category is defined as a group of related workbooks for batch processing purposes.
As an administrator, you can create new categories that auto workbook queue entries
and batch workbook refresh entries can be assigned to. Each entry can be assigned to
only one category. By default, each entry is assigned to a master category called
Default. If a category is deleted, the entries assigned to that category are reassigned to
the Default category.
When setting up auto workbooks, users can assign a category to an auto workbook
and then run the build of a category that a group of entries have been assigned to. This
is useful because it allows users to build only the workbooks they need to work with.
These categories can also be used when entering workbooks into the refresh queue
with the wbbatch utility. Similar to building workbooks, users can refresh select
workbooks based on the defined category. These categories are created with the
Workbook Batch Category Management wizard or with the wbbatch utility. For more
information about the assignment of categories, see the Auto Workbook Maintenance
Wizard and Managing the Workbook Batch Queue - wbbatch Utility sections.
In a global domain, the workbook batch category collection is global and stored in the
master domain. It is shared by all local domains.
Workbook Batch Category Management Wizard
The Workbook Batch Category Management wizard allows users to add and delete
categories as well as edit the labels of the categories. To access this wizard, perform the
following steps:
1.
Click the New icon in the toolbar or the New option in the File menu. The New
workbook window opens.
2.
Select Workbook Batch Category Management and click OK.
Figure 6–4 Workbook Batch Category Management Wizard
The Workbook Batch Category Management Wizard opens.
System Administration 6-5
Workbook Batch Category Management
Adding a Category
To add a category, select Add Category and enter a name and label for the category.
■
■
Name: The category name is restricted to standard alphanumeric characters. It
cannot contain spaces. This name is used when specifying the category in the
wbbatch utility. After a category has been created, this name cannot be changed.
Label: The category label is displayed on the workbook template wizard pages. It
can be in any language and can contain spaces. Category labels are case sensitive
and must be unique.
After you have entered a name and label, click Finish. The category is created.
Figure 6–5 Adding a Category
6-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Workbook Batch Category Management
Deleting a Category
To delete a category, select Delete Category and select the category you want to delete
from the list. Click Finish.
Figure 6–6 Deleting a Category
System Administration 6-7
Workbook Batch Category Management
Changing a Category Label
To change the category label, select Change Category Label. Select the label you want
to change and enter the new one. Click Finish.
Note:
Category names cannot be changed.
Figure 6–7 Changing a Category Label
6-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Hierarchy Maintenance Workbook
Hierarchy Maintenance Workbook
Oracle Retail Predictive Solutions provide the ability to set up and maintain usernamed and user-defined dimensions within hierarchies. Hierarchy Maintenance is the
means by which custom-created dimensions within a hierarchy can be established and
maintained through the application interface to meet individual business needs.
When Oracle Retail Predictive Solutions are installed, implementation scripts define
the dimensions and hierarchical structures specific to the customer's organization. For
example, the system can be built to recognize that SKUs roll up into styles, styles roll
up into product classes, and so on within the product hierarchy. Occasionally, you
might want to group products according to some ad hoc personal design to suit a
particular business need. You can group arbitrary items in a hierarchy to use in
functions such as forecasting, replenishment, and measure analysis. These userdefined groupings act as normal dimensional levels. In other words, they allow the
user to roll data up from lower levels of aggregation along the hierarchical paths that
you define.
For example, suppose experience has shown that the accuracy of forecasts for your top
50 products (A products) reflects the relative accuracy of all forecasts. Therefore, you
would like to group elements within a user-defined dimension as the top 50 products
by designating them 'A Products.' Then, when you select products in a wizard or look
at data in a worksheet, you can change the rollup to your user-defined dimension to
see your top 50 products grouped together.
Your collection of 50 products may comprise elements from a
wide range of product classes or departments, and your grouping
scheme may have little to do with the normal dimensional
relationships of these items in the product hierarchy.
Note:
The group of items you designate as 'A Products' may change over
time as consumer preferences change. From this example, you see that
user-defined dimensions can be used to create any ad hoc groupings
to provide additional support in analyzing, selecting, or summarizing
data in Demand Forecasting. The Hierarchy Maintenance interface
allows you to change the nature of the groupings as required.
The number and names of user-definable dimensions are set by your
company when an RPAS-based solution is initially installed. The
positions within each dimension and their associated labels can be
altered and maintained through the hierarchy maintenance process.
Remember that any hierarchy in RPAS can have user-defined dimensions within it as
long as they are set by your company at the time of installation. The following
examples refer to the Product hierarchy, but other hierarchies can be maintained in the
same way.
Hierarchy Maintenance Example
Suppose you want to designate SKUs in your product hierarchy as either A, B, or C
products so that you can group these items together when you view information, such
as forecasting, replenishment, or measure analysis reports.
To do this, you need to maintain a user-defined dimension that will allow you to map
the SKUs to the various positions of your classification scheme (A, B, or C). The userdefined dimension used in the following example is named Product Status. To
maintain this user-defined dimension, use the Hierarchy Maintenance Wizard.
System Administration 6-9
Hierarchy Maintenance Workbook
Hierarchy Maintenance Wizard
The first step in maintaining hierarchies is to access the Hierarchy Maintenance
Wizard. In this wizard, select the SKUs that will be mapped to the various positions of
the user-defined dimension. Responses to prompts in the wizard are used to format a
new Hierarchy Maintenance workbook.
Hierarchy Maintenance Worksheet
The Hierarchy Maintenance worksheet displays the position assignment fields for the
selected custom dimension. Edit the cells associated with the custom dimension as
required.
Returning to the example dimension Product Status, you want to classify each selected
SKU in your workbook as an A Product, a B Product, or a C Product. This example
provides only three positions, or values, in the Product Status dimension; however,
you can enter any character string in an individual SKU's Product Status cell. This new
string will be treated as a separate user-defined grouping. If this is the first time a
particular SKU has been mapped to the Product Status dimension, the label assigned
to that SKU will not yet be defined. The Product Status field is automatically filled
with 'Unassigned.'
Assign labels to each product with regard to the Product Status dimension. In
Figure 6–8, products that were previously unassigned are now designated as A, B, or C
products.
Figure 6–8 Hierarchy Maintenance Worksheet
Note: The Oracle Retail Predictive Solutions system is case-sensitive
when a new position name (label) is entered in the Hierarchy
Maintenance workbook. After the workbook is committed, the typing
of the group name is not case-sensitive. For example, "B Product" can
later be entered as "b product" after the "B Product" group label has
been committed.
After making the A, B, or C Product designations for the selected SKUs, you must
commit the workbook for any changes to take effect.
6-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Hierarchy Maintenance Workbook
For this example, labels have now been assigned to the various positions within the
Product Status dimension, and selected products in the product hierarchy have been
classified with regard to the custom dimension. Demand Forecasting treats Product
Status, a user-defined dimension, as a normal dimensional level within the product
hierarchy.
Figure 6–9 displays the results when you access a quick menu in a wizard and change
the rollup to the Product Status dimension. The products shown here are classified
according to the position values (A Product, B Product, or C Product) that were
assigned while maintaining the Product Status dimension.
Figure 6–9 Product Status Dimension Results
System Administration 6-11
Hierarchy Maintenance Workbook
Access Hierarchy Maintenance
1.
Select Open from the File menu to bypass the Hierarchy Maintenance wizard, and
open an existing Hierarchy Maintenance workbook, or select New from the File
menu.
2.
Select the Administration tab to display the list of Administration templates.
3.
Select Hierarchy Maintenance and click OK.
4.
Select the hierarchy to specify a user-defined dimension (for example, Product or
Location). Only the hierarchies that have been set up to contain user-defined
dimensions are represented here. Click Next.
5.
Select the user-defined dimension to be updated. The number and names of
available custom dimensions are set at installation. Click Next.
6.
On the Available side of the selection wizard, choose the items to be mapped to
positions within the custom dimension.
7.
Click the right arrow button to move them to the Selected side.
8.
After all items to appear in your workbook have been selected, click Finish.
Maintain a User-Defined Dimension within a Hierarchy
Use this procedure to assign product or location items to custom-defined positions
within a specialized dimension. Custom-created dimensions are distinct from those in
the standard hierarchical roll-ups configured in the system implementation. You can
use these dimensions as you would normal Demand Forecasting levels, aggregating
data along these new hierarchical paths.
1.
Select New from the File menu.
2.
Select the Administration tab to display the list of Administration templates.
3.
Select Hierarchy Maintenance. Click OK.
4.
Select the hierarchy to specify a user-defined dimension (for example, Product or
Location). Only the hierarchies that have been set up to contain user-defined
dimensions are represented here. Click Next.
5.
Select the user-defined dimension to be updated. The number and names of
available custom dimensions are set at installation. Click Next.
6.
On the Available side of the selection wizard, choose the items to be mapped to
positions within the custom dimension.
7.
After all items to appear in your workbook have been selected, click Finish.
8.
The Hierarchy Maintenance workbook is displayed. In the position assignment
field for the custom dimension, assign a value to each product or location position
in the workbook. Enter any text string in a cell. Each unique string will be treated
as a separate user-defined position within the custom dimension.
9.
Select Commit Now from the File menu to commit the changes to the master
database. You can also save the workbook by selecting Save from the File menu.
10. To close the workbook, select Close from the File menu.
6-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Password Policy Administration Workbook
Password Policy Administration Workbook
Using the Password Policy Measures Settings worksheet, administrators can configure
password complexity and settings in order to ensure the account security of users and
other administrators. With this worksheet, administrators can set the required
password complexity, the number of allowable password attempts, the expiration time
of a password, and the length of time a user is locked out of the system after failed
password attempts. The measures used to control these settings are described in the
table below.
The requirements set in the workbook are automatically
applied when the user logs in. If a user's password does not meet the
requirements, the user is prompted to change it.
Note:
Figure 6–10 Password Policy Measures Settings
Table 6–1
Password Policy Measures
Measure
Description
Allowable Values
Default Value
Password Attempts
The number of consecutive failed
login attempts (due to an invalid
password) before the account is
locked.
Choose from the
set values in the
pick list: 0, 1, 2, …,
10
5
Choose 0 if you do not want to
lock the account.
Password Expiration
Time
The number of days that a
password is valid for an account.
After the time passes, the user can
to log in, but is prompted to enter
a new password.
1 or greater
90 (days)
Password Fail Delay
The number of seconds the server
waits before replying to the client
that a login failed (due to an
invalid password).
0 to 600 seconds
1 second
System Administration 6-13
Password Policy Administration Workbook
Table 6–1 (Cont.) Password Policy Measures
Measure
Description
Allowable Values
Default Value
Password Failure
Lockout Time for
Administrators
The amount of time that an
administrator account is locked
after consecutive failed login
attempts. After this time passes,
the account is unlocked and the
administrator can attempt to login
again.
Choose from the
set values in the
pick list: 15 min,
30 min, 1 hour, 1
day
15 minutes
Password Failure
Lockout Time for
Users
The amount of time that a user
account is locked after
consecutive failed login attempts.
After this time passes, the account
is unlocked and the user can
attempt to login again.
Choose from the
set values in the
pick list: 0, 15 min,
30 min, 1 hour, 1
day
15 minutes
Password Minimum
Length
The minimum number of
characters that a password can
contain. (The maximum number
of characters is 31.)
1 to 31
6
Password Requires
Mixed Case
If this measure is set to true, then
the password must contain both a
lowercase and an uppercase letter.
(Passwords must always contain a
letter.)
True, false
True
Password Requires
Number
If this measure is set to true, then
the password must contain a
numeric digit.
True, false
True
Password Requires
Symbol
If this measure is set to true, then
the password must contain a nonalphanumeric character.
True, false
False
Password Reuse
Time
The number of days that must
pass before a password can be
reused for an account.
0 to 10,000 days.
365 days
Choose 0 if you do
not want to
unlock the
account.
Select 0 to place
no restrictions on
reusing
passwords.
6-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Security Administration Workbook
Security Administration Workbook
The security model in RPAS includes workbook templates, workbooks, measures, and
positions. The levels of security are defined as measure level, position level, and
workbook level.
Security Overview
This section provides the basic information on the security model in RPAS.
User Logon Security
User accounts can be marked as locked by the domain administrator. This prevents the
user from logging on with the RPAS Client. The account remains locked until the
administrator re-enables the account. Account lockouts can be set or cleared by the
domain administrator by using the User Management utility or the Edit User
workbook.
Accounts may be configured to automatically lock out after a certain number of failed
logon attempts. A domain administrator can configure the number of failed logon
attempts and the duration of the lockout using the Password Policy Administration
workbook.
Accounts may be marked as requiring the user to change the password. When this is
set, users will be prompted to change their password the next time they logon. Users
will not be able to proceed using the RPAS client unless they successfully change their
password. This is useful for brand new accounts that are created with a stock
password. The domain administrator can set or clear this setting using the User
Management utility or the Edit User workbook.
Password expiration may be enabled for the domain. The domain administrator may
set the number of days after which passwords expire. After this time passes, users
will be prompted to change their password the next time the logon. Users will not be
able to proceed using the RPAS client unless they successfully change their password.
A password reuse time can be set for the domain. This is often used in combination
with password expiration to ensure users do not change their password to a recently
used password after one expires. The domain administrator may set the minimum
number of days that may pass before users can reuse a previous password using the
Password Policy Administration workbook.
Measure Level Security
Measures have access rights; which are read-write, read-only, or denied. Measures that
are read-write or read-only may be selected in the extra measures and insert measure
dialogs. RPAS ensures that read-only measures are not editable by the user and the
presence of read-only measures does not affect the ability to commit a workbook.
Measure security can be specified and changed through the Security Administration
workbook. The Measure Rights worksheet allows Read Only, Deny, or Read/Write
access to a measure to be specified for each user.
A workbook template can override the security of a measure, but it can only narrow
the security of that measure. For example, a measure could have read-write access for
a user and a template could specify that all users have read-only access to the measure
when a workbook is built. However, if the measure security was read-only, the
template could not expand the security of that measure to read-write. Measures that
are explicitly made read-only by a workbook template will not be expanded to readwrite access by RPAS.
System Administration 6-15
Security Administration Workbook
Note: See the RPAS User Guide for the Classic Client from more
information on the Measure Analysis workbook.
Position Level Security
Position Level Security allows access control for dimensions on a position-by-position
basis. This capability is completely optional. If position level security is not explicitly
defined and configured, all users in a domain have access to all positions in all
hierarchies. After position level security is defined, access to a position can be granted
or denied for individual users, users in a group, or for all users.
Position level security can be defined at levels (dimensions) at or above base (such as
class in the product hierarchy) in any hierarchy other than calendar. As positions are
added at a level/dimension lower in the hierarchy than where the position level
security is maintained, access to those positions is automatically granted if a user has
access to the parent position. In other words, if security is maintained at the subclass
level, users are automatically granted access to all the SKUs in a given subclass if they
have access to that subclass. This includes those added after security was established.
Exactly one dimension in each hierarchy can be defined as the security dimension for
the hierarchy. If a security dimension is defined for the hierarchy, all dimensions in the
hierarchy have position level security enabled, but position security is set at or above
the designated dimension. For instance, if the class dimension is designated as the
security dimension, an administrator can maintain access to positions in the class
dimension or at any level above class. To specify the security dimension for a
hierarchy, use the RPAS Configuration Tools or the hierarchyMgr utility.
After a security dimension is defined for a hierarchy, all users in the domain default to
having access to all positions in any dimension in the hierarchy. Additionally, users
automatically have access to newly added positions to a domain. Worksheets in the
Security Administration workbook are used to control position access for individual
users, user groups, or all users (referred to as world or default access). There are three
worksheets in this workbook for each hierarchy with a defined security dimension.
The default worksheet controls access to positions for all users (for instance, Prod
Security Default); one worksheet controls access to positions by user group (for
instance, Prod Security Group); and the last worksheet controls access to positions by
individual users (for instance, Prod Security User).
Access must be granted at all levels for a user to have access to a position. This means
that a position must have a value of true at the levels default/world, group, and user.
The following table demonstrates how access is granted or denied based on all
combinations of settings:
Table 6–2
Grant/Denial of Access by Combination of Settings
Security set by Position
Based on settings on left, user
is Granted or Denied access
Denied = False
Granted = True
User
User Group
World
Resulting Access
Denied
Denied
Denied
Denied
Denied
Denied
Granted
Denied
Denied
Granted
Denied
Denied
Granted
Denied
Denied
Denied
Denied
Granted
Granted
Denied
6-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Security Administration Workbook
Table 6–2 (Cont.) Grant/Denial of Access by Combination of Settings
Security set by Position
Based on settings on left, user
is Granted or Denied access
Denied = False
Granted = True
User
User Group
World
Resulting Access
Granted
Denied
Granted
Denied
Granted
Granted
Denied
Denied
Granted
Granted
Granted
Granted
Position level security is used when a user selects positions in the wizard process
before building a workbook. Only positions to which a user has access are available for
selection in the 2-tree, which are then included in the build of the workbook.
Workbook Security
Currently, workbook access is either granted or denied. If users have been granted
access to a workbook, they can open, modify, and commit the workbook. No
distinction is made between read-write-commit, read-write, and read-only access.
Workbook access is automatically granted to the user that built it, and it may be shared
with multiple groups or the world.
A user must have access to the workbook template in order to
access the workbook, even if the workbook has world or group access
rights.
Note:
Users with administrator status automatically have access to all workbook templates.
By default, administrators have access to all workbooks that are saved with world
access. If a workbook is saved with group access, administrators can only access the
workbook if they are members of the default user group of the user who saved the
workbook.
Another aspect of workbook security is the ability to set limits for the number of
workbooks that a user can have saved at any given time. Limits can be set for a user
per template, for a user group per template, or for a template for all users. The limits
are evaluated in the above order, which means that a limit defined at user-template
overrides any values defined at group-template or template. If the above limits are not
defined, the default value is one billion.
The limits are checked when the workbook build process is initiated. When the limit is
reached, an error message displays informing the user that the workbook build
process cannot complete because the limit has been reached. The message also lets the
user know what that limit is. The wizard process then terminates.
Administrative users have full access to all workbook templates regardless of the
access rights that other admin users may assign to them in the Security workbook. The
administrative user can build the Security workbook to change the access right back,
so the nominal assignment does not matter for administrative users.
Non-administrative users do not have access to Security template and User
Administration template groups even if the administrator inadvertently assigns them
access rights.
System Administration 6-17
Security Administration Workbook
Security Administration Workbook
The Security Administration workbook is only available to system administrators.
After users and user groups are created, the administrator may set up and maintain
access permissions to workbook templates and measures within those workbook
templates. This workbook allows the administrator to determine which templates
individual users can access, as well as the measures that users can access while
manipulating workbooks in the system. The user can also specify and restrict the
measures that are available to be added to a given workbook template. Setting access
permissions in this way provides a high degree of measure security, because users can
be restricted to viewing and editing only certain relevant measures.
All administrative users have full access to all workbook templates regardless of the
access rights that they were assigned in the Security workbook by other administrative
users. The administrative user can build the Security workbook to change the access
right back, so the nominal assignment does not matter for admin users.
The Security Administration workbook has the following worksheets:
■
Workbook Template Rights Worksheet
■
Workbook Template Measure Rights Worksheet
■
Measure Rights Worksheet
■
Dimension Modification Rights Worksheet
■
Position Level Security Worksheets
■
Workbook Template Limits Worksheets
■
Max Domain Session Limit Worksheet
■
Max User Session Limit Worksheet
Security Template Administration also allows the administrator to modify the label,
Admin status, and/or default workbook template associated with each user. You also
access this workbook template to modify the labels associated with user groups,
workbook templates, and workbook template groups. Using this workbook, the
administrator can:
■
■
■
Assign and modify access rights of each user to all workbook templates. User/
template permissions are set in the Workbook Template Rights worksheet.
Determine which optional measures are to be accessible through individual
workbook templates. Template/measure permissions are set in the Workbook
Template Measure Rights worksheet.
Assign/restrict user access to individual measures. User/measure permissions are
established in the Measure Rights worksheet.
6-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Security Administration Workbook
Workbook Template Rights Worksheet
The Workbook Template Rights worksheet is for setting and maintaining access
permissions of each user to specific workbook templates.
The worksheet contains a drop-down list for each available workbook template and
user combination. To grant a user access rights to a workbook template, select one of
the following options from the drop-down list for that workbook template:
■
Denied
■
Read Only
■
Full Access
After changing a user's profile, the changes must be committed to the database in
order for them to take effect.
The Read Only permission on a template applies only to actual workbooks created by
the template. For templates that do not generate a workbook, but only run through a
wizard process for other purposes, the Read Only permission for a user on that
template will not prevent them from running through the wizard. This applies to
standard RPAS templates, such as Add User and Delete User, but it may also apply to
various application-specific templates.
Workbook Template Measure Rights Worksheet
The Workbook Template Measure Rights worksheet allows administrators to
determine which registered measures will be available for optional inclusion in newly
built workbooks.
When a measure is initially registered as a public measure, all templates default to
having access to that measure. This means that it is possible for this measure to be
added to a workbook template, even if it is not one of the standard measures
displayed when a workbook of that type is built. Some new workbook wizards
include a dialog that prompts users to select any additional measures to be included in
the workbook build. By default, all newly registered measures are included on this list
of available additional measures. The other method of inserting new measures into a
workbook is with the Insert Measure command.
The Workbook Template Measure Rights worksheet is used to modify template/
measure permissions, which allows only certain templates to optionally include
specified measures in new workbook builds.
This worksheet contains a check box for each available workbook template and
registered measure combination.
System Administration 6-19
Security Administration Workbook
Measure Rights Worksheet
The Measure Rights worksheet allows the administrator to restrict user access to
individual measures on a user-by-measure basis. User/measure permissions are
initially determined by the system by integrating the current user/template and
template/measure settings and applying the following rule: "A user cannot have
access to any measure that is not available in at least one template to which the user
has access."
Permissions can be made even more restrictive on a user by measure basis by using
the Measure Rights worksheet to deny users access to measures that they would
normally be permitted to edit.
The worksheet contains a drop-down list for each available user and registered
measure combination. Three security options are available: Denied, Read-only, Read/
Write. Denied prevents the user from viewing data. Read-only allows the user to view
the data. Read/Write allows the user to edit data values. However, a commit rule must
be configured for a measure for data to be committed to the RPAS datastore.
A measure will have the security rights it had when it was inserted in the workbook.
The change in measure security rights is only reflected in new workbooks when that
measure is inserted.
Notes:
■
■
If a measure that has dependent measures is inserted into a
worksheet, those dependent measures will also be inserted. If the
dependent measures have denied measure access, they are still
inserted into the workbook but are not visible to users.
The Measure Rights worksheet contains only public measures;
that is, measures that can be optionally included in a worksheet,
depending on choices made in a new workbook wizard. Measures
that are registered as private measures will not appear in this
worksheet. If there are no public measures available to be
displayed in this worksheet, the worksheet will not be built.
Dimension Modification Rights Worksheet
The Dimension Modification Rights worksheet allows the administrator to determine
which dimensions, if any, a user can modify. The worksheet contains a checkbox for
each available user and dimension combination. A checkmark in the cell indicates that
the user is permitted to modify the specified dimension.
After changes are made to a user's dimension modification rights, they must be
committed before they take effect.
6-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Security Administration Workbook
Position Level Security Worksheets
The position-level security worksheets are used to grant or deny access to positions for
individual users, user groups, or all users. Position-level security is set for a specific
dimension of a hierarchy (other than calendar). See the RPAS Configuration Tools User
Guide for more information on setting position-level security dimensions.
For each hierarchy/dimension that has position-level security enabled (normally just a
single hierarchy/dimension), there are three worksheets: one each for user, user group,
and world/all users.
After changes are made to position-level security, they must be committed before they
take effect.
Workbook Template Limits Worksheets
The Workbook Template Limit worksheets are used to limit the number of workbooks
that the user can have saved. Limits can be set for a user per template, for a user group
per template, or for a template for all users. The limits are evaluated in the above
order, which means that a limit defined at user-template will override any values
defined at group-template or template. If the above limits are not defined, the default
value is 1 billion, but it is not displayed in the workbook.
The limits are checked when the user begins the workbook build process. If the limit
has been reached, an error message appears that informs the user that the workbook
build process cannot complete because the limit has been reached. The wizard process
then terminates.
Max Domain Session Limit Worksheet
The Max Domain Session Limit worksheet is used to limit the number of user sessions
that can be attached to a single domain by all users of that domain. The limit is set at
the domain level. In a global domain environment, the same limit is applied
individually to each local domain and the master domain.
This limit is checked during user login. If the limit has been reached, an error message
appears to inform the user that the login has failed due to this limit being reached.
Max User Session Limit Worksheet
The Max User Session Limit worksheet is used to limit the number of concurrent user
sessions that can be attached to a single domain by the same user at the same time. The
limit is set per user so that admin can control the maximum number of concurrent
sessions that are allowed for an individual user. In a global domain environment, the
same limit is applied individually to each local domain and the master domain.
This limit is checked during user login. If the limit has been reached, an error message
appears to inform the user that the login has failed due to this limit being reached.
System Administration 6-21
Security Administration Workbook
Using the Security Administration Workbook
These tasks are performed through the Security
Administration workbook. This workbook is available to only system
administrators.
Note:
Access Security Administration
1.
From the main menu, select File - New. The New dialog box appears.
2.
Select the Administration tab to display a list of workbook templates for
Administration.
3.
Select Security Administration and click OK.
Set or Modify User Access to Workbook Templates
1.
From the File menu, select New.
2.
Click the Administration tab.
3.
Select Security Administration and click OK.
4.
On the Workbook Template Rights worksheet, select each template for which a
user's access rights require modification. Set to Denied, Read-only or Full Access.
5.
Changes must be committed to the master database before they take effect. To
commit the changes, select Commit Now from the File menu.
6.
Save the workbook by selecting Save from the File menu, if desired.
7.
To close the workbook, select Close from the File menu.
Set Measure Availability for Workbook Templates
1.
From the File menu, select New.
2.
Click the Administration tab.
3.
Select Security Administration and click OK.
4.
On the Workbook Template Measure Rights worksheet, select each registered
measure that should be available for inclusion in the associated workbook
template. For measures that should not be included in the associated template,
make sure there is no check mark.
5.
Changes must be committed to the master database before they take effect. To
commit the changes, select Commit Now from the File menu.
6.
Save the workbook by selecting Save from the File menu, if desired.
7.
To close the workbook, select Close from the File menu.
6-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Security Administration Workbook
Assign or Restrict User Access to Measures
1.
From the File menu, select New.
2.
Click the Administration tab.
3.
Select Security Administration and click OK.
4.
On the Measure Rights worksheet, for each measure that a user should have access
to, select either Read Only or Read/Write from the drop-down list. For measures
to which the user should not have access, make sure Denied is selected.
5.
Any changes made must be committed to the master database before they take
effect. To commit the changes, select Commit Now from the File menu.
6.
Save the workbook by selecting Save from the File menu, if desired.
7.
To close the workbook, select Close from the File menu.
Change User Ability to Modify Dimensions
1.
From the File menu, select New.
2.
Click the Administration tab.
3.
Select Security Administration and click OK.
4.
On the Dimension Modification Rights worksheet, select each dimension for
which the user needs modification rights. For dimensions that the user should not
be able to modify, make sure there is no check mark.
5.
Any changes made must be committed to the master database before they take
effect. To commit the changes, select Commit Now from the File menu.
6.
Save the workbook by selecting Save from the File menu, if desired.
7.
To close the workbook, select Close from the File menu.
Set or Modify Access to Positions
Use this procedure if position level security has been enabled.
1.
From the File menu, select New.
2.
Select the Administration tab.
3.
Select Security Administration and click OK.
4.
Select the worksheet for which security needs to be set or modified: User, User
Group, or World.
5.
By default, the dimension (level) at which position level security is enabled will be
displayed. To manage security at a level above the designated level (only levels
above are possible), right-click and Select Rollup to view the available
dimensions.
6.
To grant access to a position, click the checkbox of the cell.
A user must have access at the User, User Group, and World
levels to have access to a position.
Note:
7.
Changes must be committed to the domain before exiting in order for them to take
effect.
System Administration 6-23
Security Administration Workbook
Limit the Number of Workbooks that a User Can Save
1.
From the File menu, select New.
2.
Select the Administration tab.
3.
Select Security Administration.
4.
Click OK.
5.
Select the worksheet for which the limit will be set: User / Template, Group /
Template, or Template.
6.
Set the values as necessary.
7.
Commit the data to the domain before exiting.
Set or Modify the Maximum Domain Session Limit
1.
From the File menu, select New.
2.
Select the Administration tab.
3.
Select Security Administration.
4.
Click OK.
5.
On the Max Domain Session Limit worksheet, modify the scalar measure
Maximum Domain Session Limit value with a valid integer value.
6.
Changes must be committed to the master database before they take effect. To
commit the changes, select Commit Now from the File menu.
7.
To save the workbook, select Save from the File menu.
8.
To close the workbook, select Close from the File menu.
Set or Modify the Maximum User Session Limit
1.
From the File menu, select New.
2.
Select the Administration tab.
3.
Select Security Administration.
4.
Click OK.
5.
On the Max User Session Limit worksheet, modify the Maximum User Session
Limit measure per user.
6.
Changes must be committed to the master database before they take effect. To
commit the changes, select Commit Now from the File menu.
7.
To save the workbook, select Save from the File menu.
8.
To close the workbook, select Close from the File menu.
6-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Measure Analysis Workbook
Measure Analysis Workbook
The Measure Analysis workbook allows the user to view data associated with any
registered measure in the RPAS applications, such as actual sales data for specified
product/location/calendar combinations. The user may also use the Measure Analysis
workbook to edit values for writable measures, however commit capability is only
allowed to administrative users.
Although a common use of the Measure Analysis workbook is to view actual sales
data, the workbook is not restricted to presenting sales data alone. The user can view
any data loaded into the RPAS master database, such as selling prices, shipments, and
orders. The Measure Analysis Wizard provides a list of all stored measures that have
an insertable measure property set to true (see the RPAS Configuration Tools User Guide
for more information on measure properties). The user simply chooses the measures to
be displayed in the new workbook.
Due to its dynamic nature, formatting settings cannot be saved
in the Measure Analysis workbook.
Note:
Building a Measure Analysis Workbook
The Measure Analysis Wizard guides the user through the process of creating a new
Measure Analysis workbook in which the user can view selected measure data.
1.
Access the New Workbook window by clicking New in the menu.
2.
Select the Analysis tab and then select Measure Analysis. Click OK.
Figure 6–11 Measure Analysis Workbook
3.
The Measure Analysis Wizard opens. Select the measures you want to include in
the workbook. Click Next.
4.
The Available Location Positions step appears. Select the locations to be included
and click Next.
5.
The Available Product Positions step appears. Select the products to be included
and click Finish.
System Administration 6-25
Measure Analysis Workbook
Measure Analysis Worksheet
The Measure Analysis worksheet allows the user to view the chosen measure data for
the positions selected from the measure's associated hierarchies. Each Measure
Analysis worksheet is displayed at a different dimensional intersection, depending on
the measure selections made in the wizard. This dimensional intersection is shown in
the worksheet title bar.
Figure 6–12 Example of Measure Analysis Worksheet
Figure 6–12 shows a Measure Analysis worksheet that displays Weekly Sales data for
several items in a particular store. The location/product/calendar dimensional
intersection of this worksheet, as shown in the title bar, is STR (Store), ITEM, WEEK.
The Weekly Sales measure, because it is registered as a read/write measure, can be
edited in this worksheet. However only an administrative user can commit overwrites
to writable measures in this workbook.
Review and Edit Sales or Other Registered Measure Data
1.
To open an existing Measure Analysis workbook: select Open from the File menu,
double-click on the workbook to be opened, and go to step 9.
Or, to open a new workbook, select New from the File menu.
2.
On the Analysis tab, select Measure Analysis and click OK.
3.
The Measure Analysis Wizard opens and prompts the user to select the measures
to be displayed in the new workbook. Use Ctrl-Click and/or Shift-Click to select
multiple measures. Click Next.
4.
For each hierarchy specified in the base intersection of the measures selected, the
user will see a hierarchy wizard from which to select positions to view. Repeat this
step for each hierarchy wizard and click Next.
5.
Click Finish to open the Measure Analysis workbook.
6.
On the Measure Analysis Worksheets, view the stored data associated with the
measures and hierarchy positions selected in the wizard. Make any changes as
required. Administrative users may commit changes.
6-26 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
7
Hierarchy Management
7
There are a number of key concepts and processes that are critical to the hierarchy
management process:
■
■
■
■
■
■
■
■
Hierarchy structures are loaded into a domain using the loadHier utility.
RPAS uses integer indexing for simplified hierarchy administration. A set number
of hierarchy positions, based on bit size, are allocated to each dimension. The preallocation of positions reduces the need for updating the measure data structures.
The length of position names is 24 characters or less by default. RPAS provides the
ability to increase this length using the dimensionMgr utility.
Position names must consist of only the following characters: a-z, A-Z, 0-9, _, &, $,
and %. Position names cannot start with _. Any uppercase letters are converted to
lowercase letters by the application. Position names cannot be an empty string.
RPAS provides the ability to have placeholder positions in the domain that can be
used when loading new hierarchy positions.
RPAS can automatically handle the movement of positions and their
corresponding data between local domains when their parent-child relationships
change and cause such a scenario. This is only applicable in a global domain
environment.
Positions at the partition level in a global domain environment can be moved
between local domains using the reconfigGlobalDomainPartitions utility.
New local domains can be added to an existing global domain environment using
the reconfigGlobalDomainPartitions utility.
Loading Hierarchies - loadHier
The loadHier utility is used to load and refresh a hierarchy. loadHier supports comma
separated value (CSV) or fixed width flat files for loading. The load file should have a
.dat file extension when a flat file is loaded and a .csv.dat file extension when a CSV
file is loaded. When using a fixed width file, the width of fields (number of characters)
is specified in a configuration file before a domain is built. The width of fields can be
increased after a domain has been built using the dimensionMgr utility or by changing
a property in the Configuration Tools and patching the domain. The utility has also
been enhanced to allow a simple compression method that can skip duplicated values
line by line.
Hierarchy Management
7-1
Loading Hierarchies - loadHier
Note:
■
■
The following notes concern hierarchy loading with intraday:
Pre-13.2.2: Hierarchy loading is not supported while RPAS users
are online unless all users are asked to limit the scope of their
activities to workbook calculations only. Other operations such as
workbook build, refresh, commit, custom menus, and dynamic
position maintenance (DPM) can interfere with the hierarchy
loading process. In such scenarios, users and administrators will
experience concurrency issues and, in the worst case, hierarchy
data corruption can occur.
13.2.2 and later: The Ride framework allows execution of the
loadHier process. Users can stay logged in and continue their
activities as long as they do not perform activities such as
workbook build, refresh, DPM, and custom menu scripts that
touch hierarchies. The system restricts users from performing
these activities while the batch process is running. Users can
submit commit-ASAP requests which are queued and executed at
the completion of the batch process.
To manage the addition, removal, and reclassification of positions in a hierarchy, RPAS
uses a methodology called integer indexing. It is used to manage multidimensional
data at the storage level. For more information, see Integer Indexing.
loadHier supports both the loading of hierarchy positions and purging data in parallel.
When RPAS deletes a partition position through purging, RPAS adjusts the cache data
in parallel to maintain the correct position/domain mapping.
RPAS allows for multiple input files to be loaded for the same hierarchy. The extra
input files should be named with a secondary extension (for example, ' msgs.dat.1').
The extra input files can be loaded only with the main input file. For example, you
cannot load 'msgs.dat.1' in a separate loadHier call. Multiple files are often used when
the hierarchy load data comes from different sources.
RPAS automatically generates a backup copy of hierarchy files prior to performing a
load for a hierarchy. If any type of error occurs during the load process, the hierarchy
is restored from the backup copy.
The loadHier utility stops with an error if the loadHierBk directory exists in the data
directory of the domain, which indicates there may be a non-recoverable error
occurred in the previous run. If this occurs, contact My Oracle Support at http://
www.oracle.com/support/contact.html. The My Oracle Support team can best
determine whether to delete the loadHierBk directory or copy the loadHierBk content
back to the domain.
To optimize performance while moving or cleaning data during the hierarchy purging
or reclassification processes, the -excludeMeasList or -includeMeasList
argument can be specified. Both arguments specify a full path to an xml file, in the
following format, that contains a list of measures to either be excluded or included:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
</rpas>
<measures>meas1,meas2,meas3…,measN</measures>
</rpas>
7-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Loading Hierarchies - loadHier
It is very important to specify the measures wisely, especially
with the -includeMeasList option. This is because there will no
data moving for those measures not included in the list, that data will
be lost when loadHier completes.
Note:
loadHier Usage
loadHier -d domainPath -load hierName -loadAll {-purgeAge purgeage}
{-purgeAll hierarchy1} {-noClean}{-loglevel level} {-defaultDomain ldom#, ldom#}
{-excludeMeasList listName | -includeMeasList listName} {-includeUdd}
The following table provides descriptions of the arguments used by the loadHier
utility.
Table 7–1
loadHier Utility Arguments
Argument
Description
-d domainPath
The domain in which to load the hierarchy data.
-load hierName
The name of the hierarchy to load and refresh.
-loadAll
Loads all hierarchy input files (with a .dat file extension) that are
located in the input directory of the domain. Including this
argument disables the reshaping process until all files have been
loaded.
-purgeAge purgeage
Specifies the purgeage during loadHier.If not specified, loadHier
gets purgeage from domain. In global domains, -purgeAge
supports the purge of partition positions when the purgeage is
reached.
-purgeAll hierarchy1,
hierarchy2
Purges formal, informal, and user-defined positions in the listed
hierarchies. It cannot be used on a partition hierarchy or any
system hierarchy.
-noClean
This is a switch that prevents the removal of input files and
temporary data files that are generated during the hierarchy
load process. Input files will remain in the input directory of the
domain after the process is completed. This option is often used
for debugging or troubleshooting purposes.
-logLoadedPositions
This argument will enable the logging of successfully loaded
input file lines into a loaded[HIERNAME].dat file under the
processed directory.
-maxProcesses count
If specified, some parts of loadHier will run in parallel, meaning
that it will use a maximum of the defined processes, which are
specified by count.
-forceInputRollups
This argument enforces new hierarchy roll-up changes. New
roll-up changes will override or dominate existing hierarchy
roll-ups in the event they conflict with the rollups specified in
the input file. This allows you to load a hierarchy file that
reclassifies one or more upper level positions while removing
one or more discontinued base-level positions that roll-up to the
reclassified position.
-forceNAConsistency
Use this argument to force NA consistency when the current NA
value is different from the originally defined NA value for the
measure.
Hierarchy Management
7-3
Loading Hierarchies - loadHier
Table 7–1 (Cont.) loadHier Utility Arguments
Argument
Description
-includeUdd
Loads user-defined positions back to the domain. The data file
must be in CSV format with a headerline. The name of the data
file should follow the current standard: <hierarchy
name>.csv.dat.
All user-defined dimensions must be in the data file. Any
missing user-defined dimensions cause an error. All loaded
positions will have formal status after running -includeUdd.
-defaultDomain ldom#,
ldom#,
Use to specify comma separated default domain paths that will
be used for accommodating new partitions. The domain paths
can point to existing local domains or to new (non-existing) local
domain.
The local domain names are specified by a fully qualified path.
To specify more than one local domain, separate local domain
paths with a comma.
Example:
loadHier -defaultDomain ldom1, ldom2, ldom3
-excludeMeasList listName
or -includeMeasList
listName
Use one of these arguments to optimize performance while
moving or cleaning data during the hierarchy purging or
reclassification processes:
■
■
Use -excludeMeasList to optimize performance by
excluding the list of measures in listName.
Use -includeMeasList to optimize performance by including
only the list of measures in listName.
loadHier Notes
When using -defaultDomain, loadHier adds the new partition positions to the
specified default domains one by one. The list of default domains is performed in the
given order until each new partition positions is added.
Example:
Let's say we have a global domain that consists of two local domains, ldom0 and
ldom1.
Let's assume we use the following loadHier command:
loadHier ... -defaultDomain ldom1,ldom2,ldom3 ...
Let's say that in this call, there are three new partition positions (part1, part2, and
part3) in the input file. When the loadHier finishes, there will be two new local
domains, ldom2 and ldom3, with the following new partition positions included in
them:
ldom1 --> part1
ldom2 --> part2
ldom3 --> part3
In the previous example, if we only add two new partition positions (part1 and part2),
when the loadHier finishes there will only be one new local domain - ldom2. New
partition positions will be located as follows:
ldom1 --> part1
ldom2 --> part2
7-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Loading Hierarchies - loadHier
Using the same example, if we add 5 partition positions (part1, part2, part3, part4 and
part5), when the loadHier finishes there will be two new local domains, ldom2 and
ldom3. New partition positions will be located as follows:
ldom1 --> part1,part4
ldom2 --> part2,part5
ldom3 --> part3
Position Label Translation
To enable translation of position labels for the desired dimensions using the RPAS
Configuration Tools, check the box in the Translate column of the Dimension
definition tools. Building or patching the domain with this configuration builds the
necessary infrastructure in the domain to manage translations for those dimensions.
However, label translations must be separately loaded.
Position label translations are loaded in dimension specific translation measures for
every language that will be used by the users. If translated labels are not loaded using
these measures, workbooks show position names wherever a label has to be shown.
Note that for a translatable dimension, RPAS never uses or shows the position labels
from the hierarchy load file but always refers to the labels in dimension specific
translation measures. This implies that if a domain were patched to make a dimension
translatable but the translation measures were not loaded, RPAS users would see
position names instead of position labels from the load file.
Dimension specific position translation measures are named as r_<dim name>label,
where <dim name> must be replaced with the name of the translated dimension. For
example, if the sku dimension were to be translated, load the r_skulabel measure with
translations. These measures must be loaded after loading the hierarchy because RPAS
can only load translations for already loaded positions.
The position label translation measure load files have three columns. The first column
has the position names, the second column has the language identifier, and the third
column has the translation for the language specified in that row.
For example, a translation measure file for the sku dimension will be named
r_skulabel.csv.ovr and will have the content formatted as shown below. Note that in
the following example, the same file contains labels in four languages.
10006782,ENGLISH,White Nike Running Shoe size 11
10006782,CHINESE_SIMPLIF, 白色耐克 ? 鞋大小 11
10006782,FRENCH,Taille blanche 11 de chaussure de course de Nike
10006782,ITALIAN,Formato bianco 11 del pattino corrente di Nike
10004523,ENGLISH,Black leather shoe size 8
10004523,CHINESE_SIMPLIF, 黑皮鞋大小 8
10004523,FRENCH,Taille noire 8 de chaussure en cuir
10004523,ITALIAN,Formato nero 8 del pattino di cuoio
For a list of language identifiers, see Table 11–1, " Supported
Languages with Language Identifiers".
Note:
Alternatively, you can manually enter or alter translated labels using the Translations
workbook in the Administration tab. In this workbook, a worksheet is available for
each dimension that has translations enabled. You can manually enter translated
strings for the language of interest. After they are committed, these translations are
available for every new workbook.
Hierarchy Management
7-5
Integer Indexing
It is possible that due to errors when preparing translation files, translated labels for
some positions may not be loaded. In a situation where RPAS is unable to look up the
label for the locale of the machine on which the RPAS client is being run, RPAS looks
for a non-empty label string for the ENGLISH language. If it fails to find a non-empty
label string for the ENGLISH language, it uses or shows the loaded position name of
the position.
For the fixed-width format of translation measure load files,
RPAS limits the labels to 80 bytes (RPAS uses UTF-8 encoding). For
CSV format files, there is no limit. To avoid the complexity of
calculating starting positions for fixed-width format files and the
limitation of translation string length, it is recommended that CSV
files be used.
Note:
Integer Indexing
Integer indexing refers to the RPAS methodology for managing multidimensional data
at the storage level. It aims at eliminating some of the inefficiencies around the
addition, removal, and reclassification of positions in a hierarchy.
In the earlier versions of RPAS, string identifiers were constructed and used for
internal addressing of the multidimensional data. Integer Indexing changes this
mechanism in the sense that the data is internally referenced and stored by integer
identifiers that are calculated from the dimension size and measure intersection.
Integer index calculation and management is entirely internal to RPAS. From a domain
administrator’s point of view, loading and exporting hierarchy and measure data is
achieved through external names consistent with the earlier versions of RPAS.
One major advantage of integer indexing is its impact on reducing the complexity of
operations around managing position placeholders (buffers). The number of positions
that a dimension can hold is defined by a bit size which typically provides significant
space for including new positions. For instance, a SKU dimension at 24 bits can
include in excess of 16 million products. This provides significant growth space for
adding new products.
Compared to the earlier versions of RPAS, integer indexing can improve the hierarchy
load performance as it eliminates the need for running the frequent rebuffering
processes and completely eliminates the reshaping process.
Before integer indexing is described in more detail, review the following terms:
■
■
Index: An indentifier that allows for random access to the multidimensional data.
In RPAS, it is a numerical value that identifies a position in a given dimension.
Before integer indexing, RPAS used string-type position identifiers and referred to
them as internal names. Internal names were internally generated by RPAS. They
were often different from the Position IDs provided in the hierarchy input files.
Position ID: The name provided in the input hierarchy files. RPAS maps the
position ID to an internally generated integer index.
For example, let’s say you load some items into the Product hierarchy. These items are
externally identified by the position names and labels (as shown in the second and
third columns in the table below). The table below represents the SKU dimension in
the product hierarchy. Integer indexes, names, and position labels are the three major
pieces of information associated with a dimension.
7-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Integer Indexing
Integer Index Position Name Position Label
0
SKU1234
blue sweatpants
1
SKU2345
white sweatpants
2
SKU3456
green sweatpants
3
SKU4567
purple sweatpants
4
SKU5678
yellow sweatpants
5
SKU6789
pink sweatpants
6
SKU7890
orange sweatpants
7
N/A
N/A
8
N/A
N/A
9
N/A
N/A
When the green sweatpants item was loaded into the domain, its position ID,
SKU3456, was mapped to an available integer index, which was 2. After these items
were loaded, RPAS uses the integer indexes to look up those items instead of their item
IDs. Therefore, if you performed a query for green sweatpants, RPAS first identifies
that the integer index of the green sweatpants is 2. Then, it searches for instances of 2
in the array. The reason that RPAS searches for 2 instead of SKU3456 is because
searching for an integer is faster than searching for a string.
Now let’s say that you delete the blue and white sweatpants from your domain
because they are discontinued. Rather than delete these position IDs from the
dimension, RPAS marks them as inactive. By keeping these position IDs in the
dimension, RPAS maintains the position ID to integer index mapping. This way, the
green sweatpants are still mapped to the integer index 2.
Integer Index Position Name Position Label
Position Status
0
SKU1234
blue sweatpants
Inactive
1
SKU2345
white sweatpants
Inactive
2
SKU3456
green sweatpants
N/A
3
SKU4567
purple sweatpants
N/A
4
SKU5678
yellow sweatpants
N/A
5
SKU6789
pink sweatpants
N/A
6
SKU7890
orange sweatpants
N/A
7
N/A
N/A
N/A
8
N/A
N/A
N/A
9
N/A
N/A
N/A
As you delete items from the domain, the dimension begins to have gaps in it where
inactive items are using integer indexes. This is not an issue unless you want to add
more position IDs than the dimension has room for. When this happens, you will need
to reindex the dimension first.
Hierarchy Management
7-7
Integer Indexing
For instance, let’s say you want to add 5 more colors of sweatpants to the dimension.
This dimension has 10 integer indexes, so it can hold 10 total position IDs. As the
dimension is now, it has only 3 available integer indexes (7, 8, and 9) even though
there are five indexes that are not being used (0, 1, 7, 8 and 9). To use the 0 and 1
integer indexes that the inactive sweatpants are mapped to, you would use the
reindexDomain utility to defragment the dimension. This removes the blue and white
sweatpants and allows you to use the 0 and 1 integer indexes for the new sweatpants.
For more details about reindexDomain and defragging, see Reindexing Domains reindexDomain.
Integer Index Position Name
Position Label
Position Status
0
SKU3456
green sweatpants
N/A
1
SKU4567
purple sweatpants
N/A
2
SKU5678
yellow sweatpants
N/A
3
SKU6789
pink sweatpants
N/A
4
SKU7890
orange sweatpants
N/A
5
N/A
N/A
N/A
6
N/A
N/A
N/A
7
N/A
N/A
N/A
8
N/A
N/A
N/A
9
N/A
N/A
N/A
Now let’s say that you want to add 15 new SKUs instead of 5. Even if you defragment
the dimension, there is room for only 5 new SKUs. In this instance, you will need to
add more room to the dimension by increasing the dimension’s bit size. There are two
ways to increase the bit size: through the configuration and patching process or
through the dimensionMgr utility. (For more information about dimensionMgr, see
Setting Properties for Dimensions -dimensionMgr).
Changing the Bit Size
To change the bit size after a domain has been built or upgraded to 13.3, perform one
of the following sets of steps:
1.
Update the configuration and patch the domain. See Upgrading and Patching
Domains for instructions. To change the bit size, see the “Defining Dimension
Properties” in the RPAS Configuration Tools User Guide.
2.
Run the reindexDomain utility. See Reindexing Domains -reindexDomain for
instructions.
Or,
1.
Run the dimensionMgr utility to update the bit size. See Setting Properties for
Dimensions -dimensionMgr for instructions.
2.
Run the reindexDomain utility. See Reindexing Domains -reindexDomain for
instructions.
7-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reindexing Domains -reindexDomain
Reindexing Domains -reindexDomain
Use the reindexDomain utility to compress, increase, or decrease the set of physical
address space (or indexes) of the multidimensional arrays. The process of compressing
and defragmenting of the physical IDs makes the domain load and run faster.
Compression is achieved by removing the gaps, which develop due to hierarchy
operations like purge and delete. Gaps essentially block certain physical IDs within an
address space and prevents them from being used to store data in the individual
dimension arrays. After the gaps are removed, the dimension space of the
multidimensional array is recreated.
Increasing or decreasing the multidimensional array's address space is also achieved
by increasing or decreasing the bit size of the dimension arrays and then recreating the
dimension space of the array with the reindexDomain utility. In addition to
defragmenting, increasing and decreasing the number of indexes, the reindexDomain
utility also updates any measure array affected. The update is similar to the dimension
data because they are reindexed and defragmented. An affected measure is one that
has a dimension that was reindexed in its base intersection.
Notes: While working with a global domain, the reindexDomain
utility runs from master domain and spawns subprocesses across
subdomains if more than one process is used.
Domain reindexing should not invalidate existing workbooks.
After the reindexing process, workbook refresh and build operations
may run slower. Users who try to open a workbook that was built
before the reindexing process should be prompted and informed
about the potential slow performance.
A workbook is old if its dimregistry version is older than the domain
dimregistry version.
Workbook commit and refresh processes will use external name
dimension maps if the workbook is old.
Hierarchy Management
7-9
Reindexing Domains -reindexDomain
Figure 7–1 Reindexing Domain Process Flow
reindexDomain Usage
reindexDomain -d <domainPath> {Commands} {Options}
There are three unique usages of the reindexDomain utility: reindex, analyze, and
domain properties. These three usages are described in the sections below.
ReindexDomain Usage: Reindex
The reindexing options allow you to reindex the entire domain, dimensions within a
hierarchy, a specified list of dimensions, or prepend calendar dimension positions.
Table 7–2
reindexDomain: Reindexing Usages
Usage
Use
reindexDomain -d <domainPath>
Reindexes the entire domain. Checks the
reindex condition.
reindexDomain -d <domainPath> -hier <hierName>
Reindexes all dimensions of the specified
hierarchy.
reindexDomain -d <domainPath> -dimSpec <Dim1,Dim2,..>
Reindexes the comma separated list of
dimensions.
reindexDomain -d <domainPath> -hier CLND -prepend
Creates a new DimRegistry by allocating space
to prepend calendar dimensions' positions.
The input to this process comes from
clndprepend.xml file which is generated by
loadHier before it throws an exception trying
to prepend. After this process, loadHier must
be run again to complete prepending the
calendar hierarchy.
Two options can be used with these usages:
■
-force
7-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reindexing Domains -reindexDomain
Forces reindexing at domain/hierarchy/dimension level. It does not check the
reindexing condition.
■
-processes max
Specifies the number of processes to run in parallel.
ReindexDomain Usage: Analysis
The analysis usages of the reindexDomain utility allow you to analyze the dimensions
of a hierarchy or a CSV list of dimensions.
Table 7–3
reindexDomain: Analyzing Usages
Usage
Use
reindexDomain -d <domainPath> -analyze -hier <hierName>
Analyses the dimensions of the hierarchy
and prints a report.
reindexDomain -d <domainPath> -analyze -dimSpec <Dim1, ...>
Analyses the CSV list of dimensions and
prints a report.
The report consists of the following information:
■
DimName
■
DimRegistry BitSize
■
DimInfo BitSize
■
Capacity
■
Maximum Physical Id
■
Maximum Logical Id
■
Threshold
■
Action Required
Hierarchy Management
7-11
Reindexing Domains -reindexDomain
ReindexDomain Usage: Domain Properties
The reindexDomain utility can be used to review the domain properties by appending
the -prop argument.
Table 7–4
reindexDomain: Domain Properties
Usage
Use
reindexDomain -d <domainPath> -prop
Prints the following domain properties:
■
dimregistry_version
■
reindexing_in_progress
The following table provides descriptions of the arguments used by the
reindexDomain utility.
Table 7–5
reindexDomain Usage
Argument
Description
-d
Use this argument to specify the path to the global or non-partitioned
domain.
This argument is required for all reindex usages.
-hier
Reindexes all the dimensions of the specified hierarchy.
When used with the -analyze argument, the -hier argument specifies which
hierarchies should be analyzed.
-dimSpec
Reindexes the comma separated list of dimensions.
When used with the -analyze argument, the -dimSpec argument specifies
which dimensions should be analyzed.
-force
Use this argument to force the reindexDomain utility to reindex the entire
domain whether it needs it or not. This argument overrides the logic that
checks whether reindexing is necessary.
-prepend
Use this argument only when you are prepending the calendar hierarchy.
This argument creates a new DimRegistry by allocating space to prepend
calendar dimensions' positions. The input to this process comes from
clndprepend.xml file. The loadHier utility generates the clndpreprend.xml
file when you load the calendar hierarchy that has positions been
prepended. After loadHier generates this file, it displays a message, stating
that reindexDomain needs to be run first.
The clndprepend.xml must exist in the master domain root. After you run
the reindexDomain utility, you must run the loadHier utility again to
complete the prepending the calendar hierarchy process. You can also
generate clndprepend.xml manually without using loadHier.
-processes max
Specifies the number of processes to run in parallel.
-analyze
Checks whether reindexing is necessary for hierarchies or dimensions. This
argument returns details about the dimension name, bitsize, number of
available and used position IDs, the threshold ratio, and whether
reindexing is necessary.
-prop
Use this argument to see the domain properties. The properties are
dimregistry_version and reindexing_in_progress, where the dimension
registry number and the progress indicates whether a reindex is currently
running. For more information about these domain properties, see Version
and ReindexStatus.
7-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reindexing Domains -reindexDomain
When to Reindex
To know whether you should reindex a domain, run the reindexDomain utility with
the -analyze option to generate a status report. (Detailed instructions for using the
analyze option are described in the Run Reports section.) RPAS calculates how much
space is left in the array with the following equation:
(C-M) < Thresh
Where:
■
C equals the maximum number of positions IDs that the array has been allocated
to hold. C is the dimension or bitSize cardinality, which is computed with the
following equation:
C = 2BitSize
BitSize is used to compute the cardinality of a dimension. The BitSize can be
represented by up to a 4-byte unsigned long integer, which gives a maximum of
four gigs of address space. Since four gigs is very large, the BitSize is specified at
configuration time. The BitSize is determined based on the current size of the
dimension and expected increase in future. If the user does not specify Bit Size for
a dimension at configuration time, then the RPAS Configuration Tools provides a
default BitSize of 8 for that dimension.
For domains that were converted to 13.3.0, you must ensure that the hierarchy.xml
file contains an entry for all dimensions along with the bit sizes.
■
■
M equals the number of used position IDs in the dimension. This is across all
position IDs currently assigned to the dimension positions. The maximum number
of utilized physical IDs can differ from the maximum number of utilized logical
IDs if the hierarchy is subjected to deletions and additions.
Thresh is the threshold value you set for a dimension. The threshold is an integer
that represents the number of unused position IDs that you want to be available in
the dimension array. When the dimension array no longer has this specified
amount of free space, RPAS reindexes the dimension array. The threshold is part of
the configuration and is configured as a dimension attribute.
The threshold can be specified per dimension and can be configured to as any
initial value. The default value is 10% of the BitSize cardinality for a particular
dimension. This value helps determine what approach you need to take:
■
–
Increase the address space of a dimension after reindexing the dimension
arrays
–
Compress the domain arrays without increasing the BitSize
–
Both
L is the maximum utilized logical ID, which is the logical ID value of the last
position in a dimension. The domain sequence generator displays this number,
which is incremented as new positions are added to the dimension.
For example, if you have a dimension with the following characteristics:
■
C: Dimension or BitSize Cardinality for the dimension: 16 (where Bitsize is 4)
■
M: Maximum Utilized Position IDs: 9
■
Thresh: Threshold: 10
■
L: Maximum Utilized Logical ID: 4
Hierarchy Management
7-13
Reindexing Domains -reindexDomain
In this case, the calculation would produce the following:
(C-M) < Thresh
(16 - 9) < 10
7
< 10
Since 7 (the number of available position IDs) is less than 10 (the threshold of
required available position IDs), the report returns a a message that states the
dimension needs to be defragmented.
RPAS also checks the C - L > or < Thresh condition. If C - L > Thresh,
then the report returns a message that states not to increase the BitSize, but to
defrag the dimension to recover unused address space. In the example above, C L (16 - 4 =12) is less than the threshold (10). Therefore, the available address space
is sufficient after the dimension is defragmented.
If you have a dimension with the following characteristics:
■
C: Dimension or BitSize Cardinality for the dimension: 16 (where Bitsize is 4)
■
M: Maximum Utilized Position IDs: 9
■
Thresh: Threshold: 10
■
L: Maximum Utilized Logical ID: 7
In this case, the calculation would produce the following:
(C-M)
(16-9)
7
< Thresh
< 10
< 10
(C-L)
(16-7)
9
< Thresh
< 10
< 10
Since 9 is less than 10, the report returns a message that states that defragging
alone will not help, but that a BitSize increase is required to create additional
address space.
Before calculating this equation, RPAS validates the inputs. The main inputs to this
utility are the domain path, hierarchy names, and dimension names. Validation
logic checks the syntax of the command and verifies all inputs
Run Reports
There are three reports you can run with the reindexDomain that help you determine
if you should reindex your domain. Depending on the results of these reports, RPAS
may recommend that you need to reindex the dimension, that you need to increase its
bit size and then reindex, or that you do not need to either of these because the cost of
reindexing outweighs the benefit. To find out which one of these is the case, run the
following commands:
Hierarchies and Dimensions This command analyzes one or more dimensions to check
whether reindexing is necessary. You can use either the -hier argument or the
-dimSpec argument.
If the -hier argument is used, the command analyzes all dimensions in the specified
hierarchy to check whether reindexing is necessary:
reindexDomain -d [domainPath] -analyze -hier [hierName]
7-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reindexing Domains -reindexDomain
If the -dimSpec argument is used, the command analyzes all the dimensions in the
CSV list to check whether reindexing is necessary:
reindexDomain -d [domainPath] -analyze -dimSpec [comma seperated dim names]
The command returns the reindexing details. The following is an example of the
returned details:
Dim Name
DimRegistry
DimInfo
Capacity
MaxPhyId
MaxLogId
Threshold:
:
BitSize:
BitSize:
(C):
(M):
(L):
(T):
Action Required
:
splr
8
8
256
3
3
25
No action required for this dimension at this stage
Version and ReindexStatus To see the DimRegistry version and reindex status, run the
following argument:
reindexDomain -d [domainPath] -prop
It returns details about the following two domain properties:
dimregistry_version
reindex_in_progress
These two domain properties can be set using the domainprop utility. But when
reindexDomain is run, these two properties are set automatically. Therefore, there is no
need to set them separately unless you want to see their values before using the
reindexDomain utility.
■
■
dimregistry_version: This domain property stores the current version number of
the dim registry. A dim registry defines the version of the indexes. The version
number is reset with a new value when reindexing is performed. For instance, if
SKU123’s index was 15, but then reindexing caused that same SKU to be at index
2, then the dimregistry_version would be incremented. The new version is created
and stored in the domain at the same level as the previous version. Each version
can be identified physically as they are named after their version number. The
path up to the version is the same across all versions to enable data to be
processed from one version to another.
reindex_in_progress: This domain property stores the status of the last run reindex
process. It is set to TRUE when the reindexing starts and to FALSE when it
successfully completes. When the process aborts in the middle, the status remains
TRUE to indicate that reindexing needs to be restarted. As long as the status is
TRUE, the domain cannot be used for any purpose other than reindexing.
After reindexing process starts, the domain should not be used
for any other purpose until the process finishes successfully. If the
process aborts in the middle, then the reindexing process must be
restarted and completed successfully.
Note:
Only an administrator should run this utility.
Hierarchy Management
7-15
Reindexing Domains -reindexDomain
How to Reindex a Dimension
The sections below describe the various scenarios and steps needed for reindexing.
Reindex Entire Domain as Needed
This usage checks whether the reindex condition is met by at least one dimension in
the domain. If so, the reindexDomain utility stops further checks and reindexes the
entire domain. If reindex condition is not met by any of the dimensions, the utility
exits.
It is recommended that you do not reindex the entire domain. Instead, you should
reindex on a hierarchy by hierarchy or dimension by dimension basis.
reindexDomain -d <domainPath>
Reindex Entire Domain with Force Option
By using the reindexDomain with the -force option, you can reindex the entire
domain. The -force option overrides the logic that checks whether reindexing is
necessary and reindexes the entire domain.
reindexDomain -d <domainPath> -force
Reindex Dimensions
Reindexes one or more dimensions. You can use either the -hier argument or the
-dimSpec argument
When used with the -dimSpec argument, the utility reindexes only those dimensions
in the CSV list that meet the reindex condition. If listing more than one dimension, use
commas to separate them.
reindexDomain -d <domainPath> -dimSpec <comma seperated dim names>
When used with -hier argument, if at least one dimension in the hierarchy meets the
reindex condition, the utility reindexes all the dimensions in the specified hierarchy.
reindexDomain -d <domainPath> -hier <hierName>
You can use the -force option with both the -hier and
-dimSpec arguments.
Note:
Prepending Calendar Dimensions
This is a unique case where you need to add calendar positions before the current start
of the calendar. This scenario must be handled differently from scenarios where you
add calendar positions at the end of the calendar. This is because the DimRegistry for
calendar dimensions must make space at the beginning for the new positions to be
added. Here is what happens during the process of prepending positions to calendar
dimensions:
1.
The loadHier utility detects during its first run that clnd.dat has positions to be
prepended. It generates an XML file (clndPrepend.xml) which contains the
dimensions to be prepended and the number of new positions to be prepended for
each dimension. The loadHier utility then displays an error message, stating that
the reindexDomain utility must be run first before prepending the calendar
dimensions.
7-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reindexing Domains -reindexDomain
Below is an example of the clndPrepend.xml file:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <clnd>
- <prepend>
<dimension>day</dimension>
<prependsize>1457</prependsize>
</prepend>
- <prepend>
<dimension>mnth</dimension>
<prependsize>48</prependsize>
</prepend>
- <prepend>
<dimension>qrtr</dimension>
<prependsize>16</prependsize>
</prepend>
- <prepend>
<dimension>ssn</dimension>
<prependsize>8</prependsize>
</prepend>
- <prepend>
<dimension>week</dimension>
<prependsize>208</prependsize>
</prepend>
- <prepend>
<dimension>year</dimension>
<prependsize>4</prependsize>
</prepend>
</clnd>
2.
The reindexDomain utility is run with syntax added specifically for prepending
calendar dimensions:
reindexDomain -d <domainPath> -hier CLND -prepend
3.
The reindexDomain domain reads the clndPrepend.xml file and creates a new
version of the DimRegistry with space allocated to prepend the calendar
dimensions by shifting the physical IDs by an offset equal to the number of new
positions. The reindexDomain utility then reindexes all the arrays in the domain
which have these calendar dimensions.
4.
After running reindexDomain, run the loadHier utility again to complete the
process of prepending the calendar dimensions. During both the first and second
runs of loadHier, the loadHier utility checks whether calendar dimensions are
ready to be prepended or not. The DimRegistry interface is modified to verify this
condition.
If you want to avoid using loadHier for generating the clndPrepend.xml file, then you
can manually generate the file and place it under the domain root. Ensure that you use
the same syntax as the one loadHier generates, as shown in the example on the
previous page.
Hierarchy Management
7-17
Reindexing Domains -reindexDomain
Reindex Domain Examples
This is not a comprehensive list of scenarios that can occur. This is just to highlight
some examples of the reindexDomain functionality.
Condition 1: Change of Bit Size
Table 7–6
Change of Bit Size Scenarios
Scenario
Utility Option
Result
Increase/Decrease Bit
Size for SKU dimension
-dimSpec SKU
Reindexes SKU dimension and create a new
dimRegistry version.
Increase/Decrease Bit
Size for SKU and Store
dimensions
-dimSpec
SKU,STR,CLSS
Reindexes SKU and Store dimensions only.
The Class dimension does not meet any
reindex condition. A new dimRegistry
version is created.
Increase/Decrease Bit
Size for SKU dimension
-hier PROD
Reindexes all dimensions in the product
hierarchy and creates a new dimRegistry
version. For SKU dimension, the bit size
change is applied to the dimension and
measures.
Increase/Decrease Bit
Size for SKU
-d
Reindexes all the dimensions in the entire
domain and creates a new dimRegistry
version. For the SKU dimension, the bit size
change is applied to the dimension and
measures.
Condition 2: Using the -force Option
Table 7–7
-force Option Scenarios
Scenario
Utility Option
Result
No bit size change or
any fragmentation
-dimSpec SKU
Reindexes the SKU dimension and creates a
new dimRegistry version.
Bit size change for SKU,
fragmentation in CLSS,
no fragmentation in
STR
-dimSpec
SKU,CLSS, STR
Reindexes by changing the bit size for the
SKU dimension and defragmenting CLSS and
STR. Creates a new version of dimRegistry.
Bit size change for SKU
and fragmentation in
CLSS and STR
-hier PROD
Reindexes all dimensions in the product
hierarchy and creates a new dimRegistry
version. SKU dimension has bit size change
applied. STR dimension and location
hierarchy are not affected.
Bit size change for SKU,
fragmentation in CLSS,
no fragmentation in
STR
-d
Reindexes all the dimensions in the entire
domain and creates a new dimRegistry
version. For the SKU dimension, the bit size
change is applied to the dimension and
measures.
7-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reindexing Domains -reindexDomain
Condition 3: Fragmentation Checks
Table 7–8
Fragmentation Check Scenarios
Scenario
Utility Option
Result
Fragmentation in SKU
dimension but does not
meet reindex condition.
In this case, C-M>TR
-dimSpec SKU
Nothing happens.
Fragmentation in SKU
dim - does not meet the
reindex condition (here
C-M>TR) and
fragmentation in STR
dimension which meets
the reindex condition
(C-M<TR)
-dimSpec
SKU,STR
Only the STR dimension will get reindexed. A
new dimRegistry version is created.
Fragmentation in SKU
dimension but does not
meet reindex condition.
In this case, C-M>TR
-hier PROD
Nothing happens.
Fragmentation in SKU,
CLSS and STR but none
meet reindex condition.
In this case, all three
have C-M>TR.
-d
Nothing happens.
Fragmentation in SKU
dimension where
C-M<TR and C-L>TR.
-dimSpec SKU
Reindexes the SKU dimension and creates a
new dimRegistry version. This condition
means that there is fragmentation in the SKU
dimension over the threshold and
defragmenting can generate enough address
space to resolve the initial reindex condition
of C-M<TR.
Fragmentation in SKU
dimension with
C-M<TR and C-L>TR
and fragmentation in
STR with C-M>TR.
-dimSpec
SKU,STR
Only the SKU dimension is reindexed. A new
dimRegistry version is created.
Fragmentation in CLSS
dimension with
C-M<TR.
-hier PROD
All dimensions in the product hierarchy are
reindexed. A new dimRegistry version is
created.
Fragmentation in both
the SKU and STR
dimensions. Both
dimensions have
C-M<TR and C-L>TR.
-hier PROD
All dimensions in the product hierarchy are
reindexed. Nothing happens in the location
hierarchy or to the STR dimension. A new
dimRegistry version is created.
Fragmentation in the
STR dimension with
C-M<TR and C-L>TR.
-d
All dimensions in the entire domain are
reindexed. A new dimRegistry version is
created.
Fragmentation in the
SKU dimension with
C-M<TR and C-L<TR.
-dimSpec SKU
No reindexing of SKU takes place as it does
not resolve the issue since a bit size increase is
needed. A message is provided through the
utility indicating a bit size increase is
required.
Hierarchy Management
7-19
Optimizing Domains -optimizeDomain
Table 7–8 (Cont.) Fragmentation Check Scenarios
Scenario
Utility Option
Result
Fragmentation in the
SKU dimension with
C-M<TR and C-L<TR
and STR dimension
with no fragmentation
-dimSpec
SKU,STR
No reindexing takes place on either SKU or
STR. SKU requires a bit size increase. A
message is provided through the utility
indicating a bit size increase for SKU is
required.
Fragmentation of all
dimensions in the
product hierarchy were
C-M<TR and C-L<TR.
-hier PROD
No reindexing, but a message is provided
through the utility, stating that all dimensions
in the product hierarchy need an increase in
bit size.
Fragmentation for the
SKU and STR
dimension where both
have C-M<TR and
C-L<TR.
-d
No reindexing, but a message is provided
through the utility, stating that the SKU and
STR dimensions need an increase in bit size.
Optimizing Domains -optimizeDomain
Because the RPAS Btree dimension arrays undergo continuous updates and changes as
a result of adding and deleting existing positions, over time measure arrays become
full of stale data. This stale data is created when positions are deleted, but the
associated index remains. This results in wasted space and inefficient operations. The
measure arrays containing any data for these positions should be updated to reflect
these deletions. Deleting positions marks the hierarchy data for the corresponding
dimensions as changed, but it does not clean up the associated data from the measure
arrays. The optimizeDomain utility cleans this stale data from the measure arrays.
When running this utility in a global domain environment, it is centrally
administrated. This means it runs over the master domain and spawns parallel
processes over the local domains.
For example, consider a measure called meas1 that exists at intersection
sku_str_week. When a user adds a DPM position skudpm1 through an RPAS client,
it is assigned to an integer index in the meas1 data array in addition to being assigned
within the dimension's array. When this DPM position is deleted, position is flagged as
inactive, but the integer index cannot be reused until the dimension is reindexed. The
measure array also still contains the data associated with the inactive position. This
measure array needs to be updated too in order to remove the stale data.
The reindex process cleans data, but there are times when a
reindex is not needed but data needs to be cleaned. That is when
optimizeDomain should be run.
Note:
The same also holds true for formal positions that are purged during a normal
hierarchy patch. The measures arrays need to be updated for this set of positions
because they may be pointing to stale data too.
7-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Optimizing Domains -optimizeDomain
Another issue is that, over time, existing arrays in RPAS databases may become
fragmented, resulting in wasted space and a possible degradation in efficiency on
array operations. This is due to the fact that the RPAS Btree array stores data in chunks
of disk memory called pages. Deleting data from the array causes empty spaces or
holes to develop in these pages. These holes contain no data, yet they still increase the
overall size of the array. Over time, these holes become larger and more frequent, and
array operations suffer degraded performance as a result. Also, the pages begin to
acquire large amounts of unused space, causing an inefficient disk usage and a larger
than optimal domain size.
Notes: While reclassifying a position from one subdomain to
another, data associated with the reclassified positions is moved to the
new subdomain. But it is also cleaned from the source subdomain.
Therefore, the reclass operation in loadHier does not cause stale data.
No matter what option is specified, when an array is picked to be
processed by optimizeDomain, that array is both cleaned and
defragmented after a successful run.
The optimizeDomain utility is used to correct these two issues. It is recommended
after a full hierarchy purge that you run the optimizeDomain utility with the
-cleanOnly argument to remove all stale data from the domain.
optimizeDomain Usage
optimizeDomain -d [domainpath] [options]
The following table provides descriptions of the arguments used by the
optimizeDomain utility.
Table 7–9
optimizeDomain Usage
Argument
Description
-d domainpath
Use this to define the path to the domain that you want to
optimize. If no options are specified, by default
optimizeDomain defrags and cleans the entire measure set that
have arrays which have a BTree density ratio lower than the
threshold (80%). A BTree density ratio is the ratio of the
populated positions in the array to the total available BTree
pages in the array. The density threshold value (80%) is not
configured.
-defragOnly
This option selectively defrags the domain data based on
database fragmentation.
Note: -cleanOnly and -defragOnly cannot be specified
together. To achieve that behavior, run the utility without any
options.
-cleanOnly
This option cleans the stale data in the domain.
Note: -cleanOnly and -defragOnly cannot be specified
together. To achieve that behavior, run the utility without any
options.
-force
This option forces the utility to defrag the entire measure arrays
set. This should be used in combination with the -defragOnly
option. This option makes the defrag process run longer. This
option overrides the Btree density threshold (80%) and defrag
all measure arrays regardless of their BTree density.
Hierarchy Management
7-21
Optimizing Domains -optimizeDomain
Table 7–9 (Cont.) optimizeDomain Usage
Argument
Description
-excludeMeasList
Use this option to define the path to exclude list XML file.
Optimize performance by excluding this list of measures while
defragging or cleaning.
This option cannot be used with -includeMeasList.
-includeMeasList:
Use this option to define the path to include list XML file.
Optimize performance by including only this list of measures
while defragging or cleaning.
This option cannot be used with -excludeMeasList.
-returnFailure
Use this option to return a non-zero value if any of the
databases or arrays fail to defrag or clean. The optimizeDomain
process will still run to completion. The default behavior is to
log a warning and continue.
-processes max
Defines the maximum number of processes to run in parallel.
Usage Examples
Say we have the following measures list and corresponding BTree density ratios. SKU
dimension had some positions purged from the domain and marked for cleaning.
Meas1
Meas2
Meas3
Meas4
Base Intersection
SKU
SKU
STR
STR
Density Ratio
60%
90%
60%
90%
Below is the list of measures that are processed based on the command specified.
Meas1
Meas2
Meas3
No specified options
X
X
X
-includeMeasList Meas1,Meas3,
Meas4
X
X
X
-excludeMeasList Meas1,Meas3
-defragOnly
X
-cleanOnly
X
X
-defragOnly -force
X
X
X
X
OR
-force
-defragOnly -includeMeasList
Meas1,Meas4
X
X
-defragOnly -excludeMeasList
Meas1
-cleanOnly -includeMeasList
Meas1,Meas4
-cleanOnly -excludeMeasList
Meas1
Meas4
X
X
7-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
X
Adding New Dimensions to Hierarchies
Adding New Dimensions to Hierarchies
Using the RPAS Configuration Tools and RPAS utilities, you can add new dimensions
to hierarchies in existing domains. This process is described at a high level below. Each
step is described in greater detail in the following sections.
Caution: Due to its invasive impact, adding new dimensions is
different from normal domain patch process. It is a multi-step process
and requires careful user intervention.
1.
To add new dimensions to an existing hierarchy, use the Configuration Tools to
open and modify the existing configuration so that the new configuration includes
the additional dimensions.
Notes: This process can be used only for non-partitioned hierarchies.
It cannot be used to delete dimensions.
After the configuration has been modified, use the Reports Generator in the
Configuration Tools to generate a hierarchy.xml report. For more information
about creating this report, see the "Report Generator" section in the RPAS
Configuration Tools User Guide.
2.
Export measure data for all measures that have one of the dimensions of the
modifying hierarchies. See Exporting Measure Data.
3.
Export all hierarchy data from the hierarchy, including all DPM positions and
user-defined dimension rollup information. Repeat this step for each hierarchy
being modified. See Exporting Hierarchy Data.
4.
Purge all positions from the hierarchies. See Purging Hierarchy Data.
5.
Use the hierarchyMgr utility with the new hierarchy.xml to add the new
dimensions. Repeat this step for each hierarchy being modified. See Adding New
Dimensions.
6.
Create a new data file, or update the old one, to contain positions for the newly
added dimensions. Load it back to the domain. If the original hierarchy contains
user-defined dimensions, the format of the data file must be in CSV format with a
header line indicating all user-defined dimension position and label columns and
use the -includeUdd switch. Perform one execution for each modified
hierarchy. See Reloading Formal Hierarchy Data.
7.
Optional: Informalize previous DPM positions. See Informalizing DPM Positions.
8.
Reload measure data to the domain. See Reloading Measure Data.
Exporting Measure Data
Use the exportMeasure utility to export all measures for hierarchies. It exports only
measures that have storage in the domain (db property).
exportMeasure -d [domain path] -hier [hierarchy1, hierarchy2] -outDir
[outputDirectory]
To enter multiple hierarchies, separate them which commas, for example
-hier loc,clnd. This exports all hierarchy measures that have storage in the
domain.
Hierarchy Management
7-23
Adding New Dimensions to Hierarchies
If the output directory that you specify does not exist, it will be created. One output
file is created for each HBI (higher based intersection) measure. (In a global domain,
the HBI measures are stored in the master domain because the measure’s base
intersection is above the partition dimension. Forced non-HBI measures are measures
that should be an HBI measure and stored in the master domain, but the RPAS
application has forced these measures to be stored across the local domains.) In
addition, one file is created for each non-HBI or FnHBI measure per sub-domain. The
file names contain an internal sub-domain index, for example sales.0.csv.rpl,
sales.1.csv.rpl, and so on.
For more information about exportMeasure, see Exporting Measure Data exportMeasure.
Exporting Hierarchy Data
Use the exportHier utility to include user-defined dimensions. Export each hierarchy
individually.
exportHier -d [domain path] -hier [hierarchy] -datFile [datFile] -udd [listInformal fileName]
Use the -udd argument to export the user-defined definitions. The -udd argument can
only be used with the -onlyFormal or -onlyInformal options. It cannot be used
with -fixedWidth option. User-defined dimensions can only be exported in CSV
format.
If the -listInformal argument is used, exportHier also creates a file with the
fileName, which contains a list of informal positions in the domain in a format that can
be used by the informalPositionMgr. This option cannot be used with the onlyFormal option.
For more information about exportHier, see Exporting Hierarchy Data - exportHier.
Purging Hierarchy Data
Use the loadHier utility with the -purgeAll argument to purge the hierarchy data. The
-purgeAll argument purges formal, informal, and user-defined positions in the
listed hierarchies. It cannot be used on a partition hierarchy or any system hierarch.
loadHier -d [domain path] -purgeAll [hierarchy1,hierarchy2]
Use the -purgeAll argument to purge hierarchies. Specify multiple hierarchies by using
CSV format (-purgeAll loc,clnd). For more information about loadHier, see Loading
Hierarchies - loadHier.
Adding New Dimensions
Use the hierarchyMgr utility to add new dimensions. The hierarchyMgr utility parses
the hierarchy.xml file and determines where to add the new dimensions. All start and
width properties of all dimensions in the hierarchy are refreshed to be consistent with
the new hierarchy.xml.
hierarchyMgr -d [domain path] -h [hierName] -addLevels hierarchy.xml
One or more dimensions can be added to any existing hierarchy except for partitioned
or system hierarchies. Only one hierarchy can be parsed at a time. The original meta,
hmaint, and language databases are backed up and can be restored if a failure occurs.
7-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Adding New Dimensions to Hierarchies
Notes:
■
■
■
You cannot add or insert dimensions above or below user-defined
dimensions. The hierarchy.xml file does not include user-defined
dimensions.
Remove and move are not allowed.
This process is for inserting formal dimensions into the hierarchy.
It is not for adding user-defined dimensions.
Reloading Formal Hierarchy Data
Use loadHier to load the hierarchy that was purged. The user-defined dimensions
included in the input hierarchy file are also loaded.
loadHier -d [domain path] -load [hierarchy] [-includeUdd]
or
loadHier -d [domain path] -loadAll [-includeUdd]
Use the -load argument to load one hierarchy at a time. Use the -loadAll
argument to load all hierarchies that have an input file in the input directory of the
domain.
Use the -includeUdd argument to load user-defined positions back to the domain.
The data file must be in CSV format with a header line. The name of the data file
should follow the current standard: <hierarchy name>.csv.dat.
All user-defined dimensions must be in the data file. Any missing user-defined
dimensions will cause an error. All loaded positions will be in formal status. See the
Informalizing DPM Positions section for information on how to convert the status of
previous DPM positions to informal.
For more information about loadHier, see Loading Hierarchies - loadHier.
Informalizing DPM Positions
Use informalPositionMgr to informalize DPM positions.
informalPositionMgr -d domainPath -hier hierName -operation informalize -file
inputFile
Use the -file argument to enter the input file to be processed. The inputFile is the list
file exported by exportHier with -listInformal.
For more information, see Informal Position Manager.
Reloading Measure Data
Use loadmeasure to load all measure files located in the specified input directory.
loadmeasure -d [domain path] -inDir [inputDirectory]
Only .rpl files can be used with this option, and only CSV format with header line is
supported. The exported files will have one measure per file.
For more information, see Loading Measure Data - loadmeasure.
Hierarchy Management
7-25
Adding New Dimensions to Hierarchies
Adding New Hierarchy Dimensions Sample Script
Below is an example of a script that adds new hierarchy dimensions.
#!/bin/ksh
# ---------------------------------------------------------------------------#
# This is a sample script demostrates different steps to add levels to an
# existing domain
#
# ---------------------------------------------------------------------------DOMPATH=$TEST_GLOBAL_DOMAIN
# Need to be full path.
MEAS_STORAGE_DIR="C:/tak/patchHierScript/measdata"
OLD_HIER_DATA_DIR="c:/tak/patchHierScript/oldhier"
NEW_HIER_DATA_DIR="c:/tak/patchHierScript/newhier"
# can be comma separated list. If multiple is intended, exportHier, hierarchyMgr,
# and loadHier needs to be called in a loop.
# ex. HIERS="loc,clnd"
HIERS="loc"
mkdir -p $MEAS_STORAGE_DIR
mkdir -p $OLD_HIER_DATA_DIR
# Inside NEW_HIER_DATA_DIR, there should be new hierarchy xml file and new hier
data
# file.
IFS=","
# ---------------------------------------------------------------------------# Step one, export all positions.
# ---------------------------------------------------------------------------exportMeasure -d $DOMPATH -hier $HIERS -outDir $MEAS_STORAGE_DIR
if [ $? -ne 0 ]; then
echo "exportMeasure for exporing $HIERS hierarchy"
exit 1
fi
# ---------------------------------------------------------------------------# Step two, export all hierarchy data and informal position list. One hierarchy
# at a time.
# ---------------------------------------------------------------------------for h in "$HIERS"; do
exportHier -d $DOMPATH -hier $h -datFile $OLD_HIER_DATA_DIR/$h.csv.dat -udd listInformal $OLD_HIER_DATA_DIR/$h.informal.lst
if [ $? -ne 0 ]; then
echo "exportHier failed for $h"
exit 2
fi
done
# --------------------------------------------------------------------------# Step 3, purge the hierarchies.
# --------------------------------------------------------------------------loadHier -d $DOMPATH -purgeAll $HIERS
if [ $? -ne 0 ]; then
echo "Unable to purge $HIERS."
exit 3
fi
7-26 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Adding New Dimensions to Hierarchies
# BEGIN MODIFICATION and DATA LOADING.
# --------------------------------------------------------------------------# Step 4, patch the hierarchy (add levels) one hierarchy at a time.
# --------------------------------------------------------------------------for h in $HIERS; do
hierarchyMgr -d $DOMPATH -h $h -addLevels $NEW_HIER_DATA_DIR/hierarchy.xml
if [ $? -ne 0 ]; then
echo "hierarchMgr failed for $h"
exit 4
fi
done
# -------------------------------------------------------------------------# Step 5, Load the hierarchy data back. The structure reflect the
# new hierarchy structure.
#
# NOTE 1:
# Data should be updated to include positions of the newly added dimensions
#
# NOTE 2:
# Even though reclass is supported by loadHier, measure data is going
# to be loaded assuming old position is still in the original subdomain.
# Position reclassification is not recommended and may cause measure data lost.
# -------------------------------------------------------------------------for h in $HIERS; do
# copy the data file to input directory of the domain
cp $NEW_HIER_DATA_DIR/$h.csv.dat $DOMPATH/input/
loadHier -d $DOMPATH -load $h -includeUdd
if [ $? -ne 0 ]; then
echo "loadHier failed while loading $h hierarchy"
exit 5
fi
done
# -------------------------------------------------------------------------# Step 6, Set the previously DPM position back to DPM
# -------------------------------------------------------------------------for h in $HIERS; do
informalPositionMgr -d $DOMPATH -hier $h -file $OLD_HIER_DATA_DIR/
$h.informal.lst -operation informalize
if [ $? -ne 0 ]; then
echo "informalPositionMgr failed while informalizing positions in $h
hierarchy"
exit 6
fi
done
#
# -------------------------------------------------------------------------# Step 7, load measure data that exported with exportMeasure back to the
# domain.
# -------------------------------------------------------------------------loadmeasure -d $DOMPATH -inDir $MEAS_STORAGE_DIR
if [ $? -ne 0 ]; then
echo "Unable to purge load measure data in $MEAS_STORAGE_DIR. Please check the
logs in output directory"
exit 7
fi
# Completed
Hierarchy Management
7-27
Adding New Dimensions to Hierarchies
Transferring Data
The transferData utility allows you to load measure data into one domain by using a
second domain as the data source. While this can be achieved with the exportMeasure
and loadmeasure utilities, the transferData utility is more efficient since it is a
single process to load a data file into the destination domain.
The transferData utility works by copying the source measure data to the destination
measure data along any matching external position names between the source and
destination measures. This includes any informal positions that have matching names
in the destination. You can choose to exclude informal positions’ data from being
copied to the destination if desired.
You cannot use the transferData utility for forced non-HBI
(higher based intersection) measures. Forced non-HBI measures are
measures that should be an HBI measure and stored in the master
domain, but the RPAS application has forced these measures to be
stored across the local domains. For these measures, you must transfer
data using export and import utilities described in the Adding New
Dimensions to Hierarchies section.
Note:
The measure names do not need to be identical in both domains. However, the source
and destination measures must conform in intersection and data type.
The measures to be transferred are identified with the -measMap argument. The
format of the argument is a colon separated list of source measure name, destination
measure name, and an optional mask measure name:
src1:dest1[:mask1]
Multiple measure groups can be specified in pairings if separated by a comma:
src1:dest1[:mask1],src2:dest2[:mask2]
For a complete example, see the transferData Usage section.
The transferData utility can run in parallel when the destination domain is a global
domain. The -processes argument determines how many child processes to spawn
to perform the processing. This makes the transferData task faster when used in a
global domain destination.
The transferData utility validates several components before transferring data. It
validates that the source and destination domains exist, that the source and destination
measures exist, and that the source and destination measures have conforming
intersections and data types.
After it has validated everything, the transferData utility opens the source measure in
read mode and opens the destination measure in write mode; this prevents data
integrity issues. It iterates over positions in the source measure, pulls the values, and
writes them to the destination measure.
7-28 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Adding New Dimensions to Hierarchies
Masks
You can use a mask measure to restrict the transfer of a range of positions from the
source measure. This mask measure is a boolean measure, located in the source
domain, that is at the same intersection of the source/destination measure pair or
higher than that intersection.
It should be noted that the mask measure should have an NA
value of FALSE for optimal performance. The transferData utility will
stop and inform the user if this is not the case.
Note:
In addition, you can use the -clearDest flag with or without a mask option. These
combinations are described below.
No Mask with -clearDest Clears the destination arrays. Changes the destination array’s
NA value to the source measure's NA value at the beginning of the process. Loops
over the source arrays and populates the destination.
No Mask without -clearDest Does not clear the destination arrays. Does not change the
destination array’s NA value. Loops over the source arrays and copies to the
corresponding destination.
Mask with -clearDest Does not clear the destination arrays. Does not change the
destination array’s NA value. Loops over the mask and copies the source values
(populated or unpopulated) to the corresponding destination cells.
Mask without -clearDest Does not clear the destination arrays. Does not change the
destination array NA value. Loops over the mask and copies the populated source
values to the corresponding destination cells. It does not copy unpopulated source
values.
Table 7–10 illustrates the results of the mask and flag combinations.
Table 7–10
Mask and Flag Combinations and Outcomes
No Mask,
-clearDest Flag
No Mask,
No Flag
Mask,
-clearDest Flag
Mask,
No Flag
Clears destination
arrays
Yes
No
No
No
Changes the
destination array’s
NA value to the
source measure’s NA
value
Yes
No
No
No
Populates the
destination arrays
Yes
Yes
Yes, populated
and
unpopulated
source values
Yes, only
populated source
values
Hierarchy Management
7-29
Adding New Dimensions to Hierarchies
transferData Usage
transferdata -d destDomain -src srcDomain -measMap
"src1:dest1[:mask1],src2:dest2[:mask2]" {-processes n} {-clearDest} {-noInformal}
The following table provides descriptions of the arguments used by the transferData
utility.
Table 7–11
transferData Utility Arguments
Argument
Description
-d pathToDestDomain
Use this argument to specify the path to the domain containing
the destination measure. This is required.
-src pathToSrcDomain
Use this argument to specify the path to the domain containing
the source measure. This is required.
-measMap
Use this argument to enter a comma-separated list of source to
destination to mask mappings (src:dest:[:mask]), where src is
the name of the measure to be copied from the source domain,
dest is the name of the measure to be written to in the
destination domain, and mask is the name of the mask measure
to be used, if any. A one-to-one relationship must exist between
source measures and destination measures.
-processes max
Use this argument to define the maximum number of processes
to run in parallel in a global domain setup.
-clearDest
When used with a mask option, this argument ensures that the
destination measures array is not cleared and its NA value is
not changed. The utility copies the populated/unpopulated
data from the source measure positions that are populated in
the mask.
When used without a mask option, the transferData utility
clears the destination arrays and changes the destination array’s
NA value to the source NA value at the beginning of the
process. After that, the populated measure positions from the
source array
-noInformal
Use this argument to ensure only formal positions that have a
matching external name in the destination measure are copied
over.
Scenarios
The following sections describe the four scenarios of using the transferData utility.
Simple Domain to Simple Domain When the source and destination domains are simple
domains, the data is copied from the source domain to the destination domain.
Simple Domain to Global Domain When the source is a simple domain and the destination
is a global domain, and if the destination measure is a non-HBI measure, the data is
copied to the local domains of the destination. HBI measure data is copied to the
master domain. Since the destination domain is a global domain, the data is
transferred in parallel.
Global Domain to Simple Domain When the source is a global domain, for non-HBI
measures, the subdomain data array is copied to the destination. HBI measure data is
copied from the master domain to the destination domain.
7-30 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
FilterHier Utility
Global Domain to Global Domain Since the destination domain is a global domain, the
data is transferred in parallel. However, each subprocess visits each source subdomain
when transferring a non-HBI measure. This means that you do not have to run
transferData over each local domain, but only on the master domain once.
Global-to-global transferring follows this process:
1.
The transferData utility maps source's external position names to the destination's
external position names.
2.
The utility scans the source.
3.
The utility writes the values into destination measure.
The transferData utility always runs in parallel when the destination domain is a
global domain and the -processes option is set to a number greater than 1. When
the source domain is a global domain and the source measure is a non-HBI measure,
every subprocess running on each local domain of the destination domain visits every
local domain on the source, even when the source local domain has no common
position with that particular destination local domain. However, if there is no common
position, the subprocesses visits should occur quickly.
FilterHier Utility
Sometimes, a retailer has a master file of hierarchy data that needs to be loaded into
multiple domains. Some of these domains may be missing one or more levels from the
master hierarchy, mostly because the planning levels in these domains are higher than
the lowest level in the master and the domains don't need to have all the lower levels.
For example, a retailer may have one domain for Merchandise Financial Planning
where the lowest level is Category and another for Item Planning where the lowest
level is Item. The hierarchies in these two domains would have their relevant
hierarchy load data in one master file, but using loadhier, the retailer would not be
able to load just what is relevant to the domain from the master. System integrators
would need to write custom scripts to parse out irrelevant columns from the master
file to prepare load files suited for individual domains.
The filterHier utility does the filtering of columns for the system integrators ridding
them of the need to write custom scripts. The utility analyzes the target domain and
trims down the master file to only have those columns that are needed by the target
domain. The utility acts on CSV formatted files and requires the input file to contain a
header line containing the names of the columns, for example,
SKU,SKU_label,STCO,STCO_label. The output of the utility is a .csv.dat file that
can be subsequently used by the loadHier utility.
filterHier Usage
filterHier -d domainPath -input inputPath [COMMAND] {OPTIONS}
The following table provides descriptions of the arguments used by the filterHier
utility.
Table 7–12
filterHier Utility Arguments
Argument
Description
-d domainPath
The domain in which to load the hierarchy data.
-input inputpath
The path to the folder where the master files are located.
-filter hiername
Filters the hierarchy named in the parameter to the command.
Hierarchy Management
7-31
FilterHier Utility
Table 7–12 (Cont.) filterHier Utility Arguments
Argument
Description
-filterAll
Filters all hierarchies in the input directory that are relevant to the target
domain.
-compress
Creates a compressed .csv.dat output file.
RPAS has introduced a simple, proprietary compression technique to
help reduce the file size and file I/O time during loads. This technique
simply replaces a column's value with a '?' character to indicate that the
column's value for the row matches that of the row above. The
compressed file continues to print out '?' characters for a column until a
change is encountered.
This kind of compression is useful for hierarchy files where the lowest
level positions are grouped by the higher level positions. In such cases,
the output file will print out '?' characters for higher level positions until
a change is encountered, thus significantly reducing the file size.
Note that compressed files should not be split up or reprocessed in ways
that change the order of rows.
filterHier Notes
This utility will combine one or more input files into an output file that can be
imported into the target domain using loadHier. The input files must be csv data
containing a comma separated header line listing the name of each column. Column
names should be in the format DIM,DIM_label.
Example: SKU,SKU_label,STCO,STCO_label,SIZ1,SIZ1_label
The input files must have the extension .hdr.csv.dat. Optional extensions are allowed
at the end of the file.
Example: prod.hdr.csv.dat.foo1
The columns in the output file will be arranged to match the hierarchy format of the
target domain. Any dimensions from the input files that are not present in the output
domain will be filtered out.
The output file will be a properly formatted .csv.dat file, and will be in the input
directory of the target domain.
Error Conditions
The following error conditions may occur during the operation of filterHier:
■
■
■
■
Dimension Not Found - If a dimension that exists in the domain is not found in the
header, the input file will be skipped.
No Usable Input Files - If filterHier cannot find a usable input file, it will exit with
error.
Parse Error in Data - If one or more data rows contain an error, filterHier will
display an error specifying which lines contain an error, and proceed processing
the rest of the file.
Conflicting Base Positions - If a base position has multiple definitions in the input
files, the first definition will be used and all others will be skipped.
7-32 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Position Repartitioning
Position Repartitioning
Position repartitioning is the automated process of moving positions and all
corresponding measure data between local domains. This functionality is only
available (and relevant) in global domain environments. Positions need to be moved
between local domains when they are assigned a new parent that exists in a different
local domain. Note that moving positions at the partitioning level is a manual process
and requires the use of the reconfigGlobalDomainPartitions utility.
For example, imagine Style1 belongs to Sub-Class1 in LocalDomain1. If Style1 is
reassigned to be a child of Sub-Class2, which is located in LocalDomain2, RPAS will
move the Style1 position, Style1's children (if any), and all corresponding data to
LocalDomain2. This process is often referred to as reclassification by RPAS customers.
RPAS refers to this functionality as position repartitioning because it technically does
not handle the many complex functional requirements of true reclassification as most
retailers define the term to mean.
Loading RDF and Curve Parameters after Repartitioning
After repartitioning, default parameters for Curve and RDF are not automatically
loaded in new subdomains. To load these parameters, the following scripts, which are
located in the RPAS_HOME/bin directory, need to be executed:
■
loadCurveParameters.ksh - Used to load Curve parameters after a repartition.
■
loadRdfParameters.ksh - Used to load RDF parameters after a repartition.
These scripts are used to load RDF and Curve parameters to a subdomain that was
created as a result of repartitioning. These parameters are usually loaded during a full
installation by the plug-ins, but when performing a patchinstall, the parameters are
not loaded by default. These parameters include default required method, default
source, spreading profile, and others.
You need to run these scripts after repartitioning a domain on the new partition.
Syntax
scriptname -d <full path to domain> -s <full path to subdomain>
Example:
loadRdfParameters.ksh -d /vol.nas/forecast/domains/RDF_12 -s /vol.nas/forecast /
domains/RDF_12/ldom0/
Hierarchy Management
7-33
Reconfiguring Partitions of a Global Domain - reconfigGlobalDomainPartitions
Reconfiguring Partitions of a Global Domain
- reconfigGlobalDomainPartitions
It is common for many customers to regularly add, remove, or change the parent-child
relationships for positions in hierarchies, most commonly for positions in the product
hierarchy. While this movement/reassignment of positions is normally handled
automatically within the loadHier utility, a special process must be followed for
positions at the partition level of a global domain environment.
The RPAS utility reconfigGlobalDomainPartitions is used for the following activities in
a global domain environment:
■
■
■
■
Add a new position along the partition dimension and allocate it to an existing or
new local domain.
Remove an existing position from the partition dimension.
Remove local domains (this is automatic if all partition-level positions in a local
domain are removed or moved).
Move an existing partition position from one local domain to an existing or new
local domain.
Runs loadHier to apply the position addition/removal to hierarchy.
This utility can only be used on a master domain of a global
domain set.
Note:
The following processes must be followed to add, remove, or move positions at the
partition level in a global domain environment:
■
■
■
The administrator must be notified in advance that positions at the partition level
are being added, removed, or moved.
The administrator should run the utility reconfigGlobalDomainPartitions to by
specifying the sub-domain to which the positions do or will belong.
This utility calls the loadHier utility at the end of the reconfiguration process to
apply the hierarchy changes to the domain. When adding positions (using the
-add argument) an updated hierarchy file must be available in the input directory
when the reconfigGlobalDomainPartitions utility is called. Otherwise the utility
will fail. Updated hierarchy files are not required to remove (using the -remove
argument) or move positions (using the -move argument).
The use of this utility is only required for positions at the
partition level. Positions below the partition level can be added,
removed, or moved between local domains by loading a modified
hierarchy input file with these changes.
Note:
7-34 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Reconfiguring Partitions of a Global Domain - reconfigGlobalDomainPartitions
reconfigGlobalDomainPartitions Usage
reconfigGlobalDomainPartitions
...
reconfigGlobalDomainPartitions
sub pathToSubDomain
reconfigGlobalDomainPartitions
-sub pathToSubDomain
reconfigGlobalDomainPartitions
-d pathToMasterDomain -remove posName1, posName2,
-d pathToMasterDomain -add posName1,posName2, ... -d pathtoMasterDomain -move posName1,posName2, ...
-d pathToMasterDomain -input pathToInputDir
The following table provides descriptions of the arguments used by the
reconfigGlobalDomainPartitions utility.
Table 7–13
reconfigGlobalDomainPartitions Utility Arguments
Argument
Description
-d pathToMasterDomain
Specifies the path to the master domain in a global domain
environment.
-add posName1, posName2,
…
Adds one or more positions at the partition level to a specified
local domain.
The path to the local domain must follow the list of positions to
add, using the -sub argument. If the specified path is to a local
domain that does not yet exist, the system will create a new local
domain with the specified positions at the partition level.
This argument cannot be used with -remove or -input.
-remove posName1,
posName2, ...
Removes the designated positions from the local domain to
which the positions belong. The path to the local domain does
not need to be specified with this argument.
The local domain will be deleted if all the positions at the
partition level in a local domain are removed. This argument
cannot be used with -add or -input.
-move posName1, posName2,
...
Moves the specified positions at the partition level from the
current domain in which the positions are located to the
specified local domain.
This argument requires specification of the -sub argument. To
move positions, all dimensions below the partition level must be
enabled for dummy positions.
-sub pathToSubDomain
Specifies the path to the local domain to which positions are
being added or the destination local domain for positions being
moved.
When a new domain path is specified using -sub option, a new
local domain will be created.
This argument is required for the -add argument and -move
argument.
-input pathToInputDir
Specifies the path to the input directory that contains an xml
configuration file (reconfigpartdim.xml) to specify positions to
either add or move.
The file must have all the information to run the process
including the command name, position names to add or move,
and paths to the local domains.
This option is useful for adding or moving positions to multiple
local domains. This argument does not handle both adding and
moving in the same call.
This argument cannot be used with -add or -remove.
-maxProcesses count
If specified, some parts of reconfig utility will run in parallel,
utilizing up to the given number of processes.
Hierarchy Management
7-35
Reconfiguring Partitions of a Global Domain - reconfigGlobalDomainPartitions
Table 7–13 (Cont.) reconfigGlobalDomainPartitions Utility Arguments
Argument
Description
-forceInputRollups
This argument will prevent this utility from failing in instances
where there is a roll-up conflict in the input file provided to the
utility. This argument enforces new hierarchy roll-up changes
such that they dominate existing hierarchy roll-ups in case they
conflict with the roll-ups specified in the input file.
Using an Input File
When using the -input argument, the file must be in a particular format and must
contain the add or move commands, the path to each local domain to which positions
are being added or the destination for positions being moved, and the list of positions
for each local domain. The file must be XML and named reconfigpartdim.xml.
The -input argument only supports the addition or movement
of positions.
Note:
Below is the required format of the input file:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rpas>
<command name="command_name">
<subdomain>
<subpath>path_to_local_domain_1</subpath>
<subpositions>sample_pos_1</subpositions>
</subdomain>
<subdomain>
<subpath>path_to_local_domain_2</subpath>
<subpositions>sample_pos_2,sample_pos_3</subpositions>
</subdomain>
</command>
</rpas>
The entries in bold are the parameters that must be specified in
the input file.
Note:
The following table provides descriptions of the arguments used by the input file.
Table 7–14
Arguments Used by the input File
Argument
Description
command_name
Valid values are add or move.
path_to_local_domain
Path to the local domain to which positions are added or moved.
sample_pos
One or more positions that are being added or moved to the
designated local domains.
7-36 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Renaming Positions - renamePositions
Notes, Assumptions, and Limitations
■
■
■
■
■
■
■
Position names are separated by commas and must be valid external position
names without the prefix of a dimension (for instance, 0102,0144,0152,0160).
The utility backs up the required data and will automatically restore the domains
to the original state in case of failure.
In a single call to the utility without using the -input argument, positions can only
be added or removed or moved. That is, the -add, -remove, and -move arguments
cannot be mixed in the same call.
Multiple positions can be added or moved to a single local domain in a single call
to the utility using the -add or -move option, respectively.
Multiple positions can be added or moved to multiple local domains in a single
call to the utility using the -input option.
When adding positions at the partition level, an updated hierarchy file must be
available in the input directory when running this utility as the loadhier utility is
called after adding positions. If the updated hierarchy file is not present in the
input directory when attempting to add positions, the utility will fail.
No updated hierarchy file is required when moving or removing positions. If a
hierarchy file is in the input directory, the utility will back up this file.
Renaming Positions - renamePositions
RPAS provides the ability to change the name of a position using an RPAS utility
named renamePositions. Positions that are to be renamed should be included in a
hierarchy data file. After the hierarchy data files have been updated and placed in the
designated location, an administrator must run the renamePositions utility.
Note: The renamePositions utility cannot be used to rename any
RPAS system objects such as dimensions, workbooks, hierarchies, and
so on.
renamePositions Usage
renamePositions -d domainPath
logFileName} {-dryRun}
-hier hierName {-input inputDirectory} {-log
The renamePositions utility renames positions in a specified hierarchy. It looks for
a file named hierName.rn.dat (for example, prod.rn.dat) in the domain's input
directory when -input is not specified.
The input file is a CSV text file with three columns. Tab-delimited fields are not
supported in the input file. This is consistent with other domain utilities in which tabdelimited fields are not supported. One line per rename request. Each line consists of a
dimension name, the old position name, and a new position name. For example:
sku,10000_old,10000_new
The utility ignores any line not formatted this way, empty lines, and lines with a
specified dimension that does not exist for the specified hierarchy.
Hierarchy Management
7-37
Renaming Positions - renamePositions
The input file is not case sensitive, and all names are converted to lower case before
the positions are renamed. Old position names that are specified but that do not
actually exist are ignored. New position names cannot be an already used name. Lines
with invalid position names are ignored and added to the log file. The old position
name and new position name should not be prefixed with the name of the dimension.
The width property of the dimension is enforced. The width attribute in the domain
must be greater than or equal to the max length of the new names in the input file. If
the width of the new name is greater than the width attribute of the corresponding
dimension, RPAS prints an error in the log file and ignores the record.
Dimensions specified in the input file should belong to the hierarchy that is specified
in arguments. Otherwise, the record is ignored, and RPAS prints an error in the log
file.
If you want to swap position names (a->b, b->a), you must
perform two separate operations: (a->tempa,b->tempb) and
(tempa->b, tempb->a).
Note:
The following table provides descriptions of the arguments used by the
renamePositions utility.
Table 7–15
Arguments Used by the renamePositions Utility
Argument
Description
-d domainPath
Specifies the full path to the domain.
-hier hierName
Hierarchy in which positions are being renamed.
-input inputDirectory
Input directory where input file with positions to rename is
located. This is optional.
Utility looks for hierarchy data files with "rn" between hierarchy
name and .dat extension (for instance, prod.rn.dat).
-log logFileName
Optional parameter to generate log file to file name other than
default. The default file name is hierRename.log.
This argument can be used to name the log file other than the
default, which is created as hierRename.log in the current
directory.
-dryRun
Does not apply changes, but generates a report that identifies
changes that would be applied. This argument generates a log
file.
7-38 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Setting Properties for Dimensions -dimensionMgr
Setting Properties for Dimensions -dimensionMgr
The dimension manager utility is used for setting a number of parameters for
dimensions and positions. Multiple command arguments are allowed.
dimensionMgr Usage
dimensionMgr -d pathToDomain -dim dimensionName [COMMAND] {Options}
The table below provides descriptions of the arguments used by the dimensionMgr
utility.
This utility includes arguments that are not documented in
this guide as it is recommended that those operations be configured
using the Configuration Tools to ensure consistency between the
configuration and the domain.
Note:
Table 7–16
dimensionMgr Utility Arguments
Argument
Description
-d pathToDomain
Specifies the path to the domain.
-dim dimensionName
Specifies the name of the dimension to which the settings will
apply.
-label newLabel
Use this argument to specify a new dimension label.
-enableDPM
This argument enables Dynamic Position Maintenance (DPM)
for the specified dimension (-dim dimensionName).
Using this argument not only enables DPM for the specified
dimension, but for all dimensions that roll up to it.
DPM cannot be enabled for any dimension in an RPAS-internal
hierarchy (DATA, META, RGPS, ADMU, ADMW, MSGS,
LNGS).
-enableTranslation
width
This argument enables the specified dimension to use translated
labels.
When enabling translated labels, the numeric parameter passed
in the argument (width) defines the field width for the translated
values in the data file, which is loaded using the loadMeasure
utility.
Hierarchy Management
7-39
Setting Properties for Dimensions -dimensionMgr
Table 7–16 (Cont.) dimensionMgr Utility Arguments
Argument
Description
-specs
This argument displays the properties of the specified
dimension. The dimension properties indicate whether DPM
and translation are enabled for the dimension and whether the
dimension is image-enabled.
Below is the full list of properties that the -specs argument
returns:
Dimension Label
Associated Hierarchy of Dimension
Start and Width for File Load
Label Start and Width for File Load
Number of Used Positions
Image Enabled
Bit Size
Capacity
Used
Reindex Threshold
Translation Enabled
Spreads/Aggs (meaning, where the dimension fits in the rollup)
If the dimension is at the base level of a hierarchy, that is
indicated as well.
-width widthVal
This argument sets the width of position names for the specified
dimension. After you have created a position name, you can
only increase its width; you cannot decrease the width.
bitSize
This argument changes bit size for the dimension, but does not
actually update the dimension arrays. You must run
reindexDomain for the dimension data and measure arrays to be
updated.
reindexThreshold
Use this argument to set a new reindex threshold for the
dimension.
Changing the Label of a Dimension
To change the label of a dimension, use the dimensionMgr utility. It is not restricted
to partitioned hierarchies.
dimensionMgr -d domainPath -dim dimName -label newLabel
7-40 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Exporting Hierarchy Data - exportHier
Exporting Hierarchy Data - exportHier
The exportHier utility is used to export all the positions in a hierarchy, including their
rollup relations. The exportHier utility cannot be run on local domains. It must be run
only on the master domain or simple domains. By default, the utility assumes that the
file has a CSV flat file format with fixed width format as an optional argument. The
utility exports all hierarchy positions, but the file may be specified to include only
formal or informal positions. The resulting file can then be used as a .DAT file with
loadHier.
exportHier Usage
exportHier -d domainPath -hier hier_name -datFile dat_file [-fixedWidth]
[-onlyFormal | -onlyInformal][-upperCase]
The following table provides descriptions of the arguments used by the exportHier
utility.
Table 7–17
Arguments Used by the exportHier Utility
Argument
Description
-d pathToDomain
Specifies the path to the domain.
-hier hier_name
The name of a hierarchy in the domain from which the .DAT file will be
generated.
-datFile dat_File
The path/location where the .DAT file will be created. This .DAT file can
then be used with loadHier to load the hierarchy into a domain.
-fixedWidth
This argument indicates that the output .DAT file is a fixed-width file
instead of a comma-separated value (CSV) file format.
-onlyFormal
This argument exports only formal positions to the .DAT file. If this is
option is specified, informal positions will be skipped.
-onlyInformal
This argument exports only informal positions to the .DAT file. If this is
option is specified, formal positions will be skipped.
-genheader
This argument generates a header line for CSV export. The line contains
fields to identify the dimension and its label column.
-udd
This argument exports the user-defined definitions. It can only be used
with the -onlyFormal or -onlyInformal options. It cannot be used
with -fixedWidth option. User-defined dimensions can only be
exported in CSV format.
-listformal
Creates a file with the fileName, which contains a list of the informal
positions in the domain in a format that can be used by the
informalPositionMgr. This option cannot be used with the
-onlyFormal option.
-upperCase
This argument converts the position names to all uppercase before
writing the output data file. Without this argument, position names are in
lowercase since they are stored in lowercase in the domain.
Hierarchy Management
7-41
Informal Position Manager
Informal Position Manager
Informal Position Manager is a domain utility that maintains informal positions for
any dimension in a domain. Informal positions are those created with the Dynamic
Position Manager (DPM). Formal positions are those created with the loadHier utility.
This utility can convert positions from formal to informal or from informal to formal. It
can also remove informal positions, create informal positions in bulk, and copy data
slices between positions in measures.
InformalPositionMgr Usage
There are three main areas of use for informalPositionMgr, which are described in the
following sections:
■
Basic Operations: Informalize, Formalize, Remove
■
Create Informal Positions in Bulk
■
Data Slice Copying
Basic Operations: Informalize, Formalize, Remove
Informalizing, formalizing, and removing informal positions all have similar
command line options.
informalPositionMgr -d domainPath -hier hierName -operation [remove | formalize |
informalize] [-dir inputDir | -file inputFile] [-retain]
The following table provides descriptions of the arguments used in basic operations of
the informalPositionMgr utility.
Table 7–18
Arguments Used by the informalPositionMgr Utility: Basic Operations
Argument
Description
-d domainPath
The domain to run the utility.
-hier hierName
Use this option to specify the hierarchy to operate on.
-operation informalize |
formalize |remove
Specify one of the three basic operations: informalize, formalize,
or remove. You can use only one of these operations at a time.
■
■
■
remove: Removes informal positions of the specified
hierarchy.
formalize: Formalizes positions of the specified hierarchy.
informalize: Informalizes positions of the specified
hierarchy.
7-42 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Informal Position Manager
Table 7–18 (Cont.) Arguments Used by the informalPositionMgr Utility: Basic
Argument
Description
-file inputFile
Use one and only one of these arguments to specify the input
files to use during the operation specified.
or
-dir inputDir
■
■
-dir inputDirectory: Processes all applicable files under
inputDirectory.
-file inputFile: Processes the inputFile only.
All files that match the naming patterns below are processed:
■
Remove files: {hierName}.remove[.extension]
■
Formalize files: {hierName}.formalize[.extension]
■
Informalize files:
{hierName}.informalize[.extension]
For example: prod.informalize.20100220
The format of the returned content has one position on each line.
The position has a dimension name and a position name that are
comma delimited. There is no header line:
dimName1, positionName1
dimName2, positionName2
-retain
Use this argument if you do not want to move the input files to
the processed subdirectory after a successful run.
Error Handling
The following errors result the described behavior.
Table 7–19
informalPositionMgr Error Handling
Error
Behavior
Input file does not exist
A log error is generated and the operation stops.
Any dimension specified in the input file is
not DPM enabled or does not exist
A log error is generated and the operation stops.
One or more positions does not exist
Log warnings are generated, the line is skipped,
and the operation continues.
Selecting to convert a position to informal
that is already informal
No action is taken on that position and a
warning message is logged and the operation
continues.
OR
Selecting to convert a position to formal
that is already formal
Hierarchy Management
7-43
Informal Position Manager
Create Informal Positions in Bulk
This feature allows user to create a number of informal positions on any DPM-enabled
dimension. These positions are automatically named and labeled. However, the user
must provide applicable rollup and spread information so that these new positions can
be properly placed in the hierarchy.
informalPositionMgr -d domainPath -create -dim dimName -n posCount
-rollups dim1:pos1,dim2:pos2,... [-spreads dimA:ratioA,dimB:ratioB,...]
For bulk creation of informal positions, the position names and labels are autogenerated. To ensure the names are unique, a prefix and sequence number is used and
the width and label width attributes of the dimension should be at least 10. If the
width or label width is less than 10, bulk creation is not allowed, and exception is
thrown.
If the specified dimension by option -dim is above the root dimension, informal
positions are added to the lower levels. The numbers of spread positions for lower
level dimensions are defined by the -spreads option. Note that the spread ratio
determines the number of children for each position at the level immediately above
the specified dimension. If not specified, the default is 1.
If these new descendent positions roll up to other alternate dimensions, there are a few
options to handle the rollups. If those dimensions are DPM-enabled, you can either
specify the rollup positions (in the -rollups option) or let the program to create
single rollup position for you. This repeats recursively for those new positions. If any
of those affected dimensions are not DPM-enabled, the rollup positions must be
specified.
To manage the performance impact of bulk creation, a limit is
placed on how many positions can be added at one time. The default
limit is 5000 per dimension, which can be overridden using the
following domain property:
Note:
MAX_NEW_BULK_DPM_POS
If the limit is exceeded, the program stops and no positions are created
in the domain.
The following table provides descriptions of the arguments used by the create bulk
positions functionality of the informalPositionMgr utility.
Table 7–20
Arguments Used by the informalPositionMgr Utility: Create Bulk Positions
Argument
Description
-d domainPath
The domain to run the utility.
-create
Use this option to batch create new positions with autogenerated names.
-dim dimName
Use this option to specify the dimension to operate on.
-rollups
dim1:pos1,dim2:pos2,…
Use this option to specify the rollup positions for the autogenerated positions. You should include the direct rollups for
the new positions and rollups for the descendents of these new
positions on alternate branches, if applicable.
-spreads
dimA:ratioA,dimB:ratioB,…
Use this option to specify the spread counts for the autogenerated positions. This is optional. It defaults to 1 if not
specified.
7-44 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Informal Position Manager
Table 7–20 (Cont.) Arguments Used by the informalPositionMgr Utility: Create Bulk
Argument
Description
-n posCount
Use this argument to enter the number of positions to create on
the specified dimension.
The following sections show some examples of creating informal positions in bulk on
the product hierarchy. Figure 7–2 displays a product hierarchy with alternative
branches and four DPM-enabled dimensions (STYL, STCO, SKU, and SZ12).
Figure 7–2 Sample Product Hierarchy with Alternative Branches
Hierarchy Management
7-45
Informal Position Manager
Example 1: Create Informal Positions on the STYL Dimension
To create informal positions on the STYL dimension, you must specify rollups for
SCLS, CLR and SPLR. You have two options for SZ12:
■
■
Option 1: Specify the rollup for SZ12
Option 2: Specify the rollups for SIZ1 and SIZ2. A new position is automatically
created on SZ12. You can specify spread ratios for STCO and SKU. If you do not
specify the spread ratio, it defaults to 1.
Option 1
informalPositionMgr -d domainPath -create -dim STYL -n 100 -rollups
SCLS:scls1001,CLR:clrwhite,SPLR:splr100,SZ12:sz12null -spreads STCO:2,SKU:5
This command creates the following:
1.
100 new informal positions on the STYL dimension. These positions all roll up to
SCLS:scls1001.
2.
Since the spread ratio for STCO dimension is 2, 200 new informal positions are
created at the STCO level, and every two of them roll up to one STYLE position
that was created in step 1. These new informal positions all roll up to CLR:clrwhite
on the alternate branch.
3.
Similarly, 1000 new informal positions are created at the SKU level, and every 5 of
them roll up to one STCO position that was created in step 2. They all roll up to
SPLR:splr100 and SZ12:sz12null on the two alternate branches.
Option 2
informalPositionMgr -d domainPath -create -dim STYL -n 100 -rollups
SCLS:scls1001,CLR:clrwhite,SPLR:splr100,SIZ1:siz1null,SIZ2:siz2lt02 -spreads
STCO:2,SKU:5
This command creates the following:
1.
100 new informal positions on the STYL dimension. These positions all roll up to
SCLS:scls1001.
2.
One new informal position at the SZ12 level, which rolls up to SIZ1:siz1null and
SIZ2:siz2lt02.
3.
Since the spread ratio for STCO dimension is 2, 200 new informal positions are
created at the STCO level, and every two of them roll up to one STYL position
created in step 1. These new informal positions all roll up to CLR:clrwhite on the
alternate branch.
4.
Similarly, 1000 new informal positions are created at the SKU level and every 5 of
them roll up to one STCO position created in step 3. They all roll up to
SPLR:splr100 and the new SZ12 position created in step 2.
Example 2: Create Informal Positions on the SZ12 Dimension
To create informal positions on SZ12 dimension, you must specify rollups for SIZ1,
SIZ2 and SPLR and specify the spread ratio for SKU. For the DPM-enabled dimension
STCO, you have two options:
■
■
Option 1: Specify a rollup position.
Option 2: Create a rollup position and specify a rollup position on CLR and rollup
position on STYL (or create recursively until the non-DPM enabled dimension is
reached).
7-46 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Informal Position Manager
Option 1
informalPositionMgr -d domainPath -create -dim SZ12 -n 10 -rollups
SPLR:splr100,SIZ1:siz1null,SIZ2:siz2lt02,STCO:stco2000 -spreads SKU:5
This command creates the following:
1.
10 new informal positions on the SZ12 dimension. These positions all roll up to
SIZ1:siz1null and SIZ2:siz2lt02.
2.
Since the spread ratio for SKU dimension is 5, 50 new informal positions are
created at the SKU level, and every 5 of them roll up to one position at the SZ12
level, which was created in step 1. These new informal positions all roll up to
SPLR:splr100 and STCO:stco2000.
Option 2
informalPositionMgr -d domainPath -create -dim SZ12 -n 10 -rollups
SPLR:splr100,SIZ1:siz1null,SIZ2:siz2lt02,SCLS:scls1001,CLR:clrwhite, -spreads
SKU:5
This command creates the following:
1.
10 new informal positions on the SZ12 dimension. These positions all roll up to
SIZ1:siz1null and SIZ2:siz2lt02.
2.
One new informal position at the STYL level, which rolls up to SCLS:scls1001.
3.
One new informal position at the STCO level, which rolls up to CLR:clrwhite, and
the new position at STYL level, which was created in step 2.
4.
Since the spread ratio for SKU dimension is 5, 50 new informal positions are
created at the SKU level, and every 5 of them roll up to one position at the SZ12
level which was created in step 1. These new informal positions all roll up to
SPLR:splr100 and the new STCO position created in step 3.
Position Naming Convention
When the bulk creation feature is used, the names and labels of the new positions are
created with the following name conventions:
■
Position name: {dimName}{dpm}{seq#}
The width is an attribute of the dimension. For auto-generated position names,
the minimum width required is 10.
–
For width = 10, {4 char dimName}d{5 char seq#}
–
For width = 11, {4 char dimName}d{6 char seq#}
–
For width = 12, {4 char dimName}d{7 char seq#}
–
For width = 13, {4 char dimName}dp{7 char seq#}
–
For width >= 14, {4 char dimName}dpm{7 char seq#}
If the dimName is less than 4 characters, an underscore is appended (for example:
sku_. Each dimension uses its own persistent sequence generator in the domain
with a unique label DPM_{dimName}. For a global domain, the sequence
generators are in the master domain.
■
Position label: Follows the same convention as that of position name, but uses the
label width attribute of the domain.
Hierarchy Management
7-47
Informal Position Manager
Data Slice Copying
This feature allows you to copy data slices of one position to those of another. It is
especially useful when you want to merge informal positions with existing formal
positions. An inclusive or exclusive measure list can be specified. A Boolean type mask
measure can be used to enable selective copying of data slices.
informalPositionMgr -d domainPath -copy -file inputXMLFile [-retain]
The following table provides descriptions of the arguments used by the data slice
copying functionality of the informalPositionMgr utility.
Table 7–21
Arguments Used by the informalPositionMgr Utility: Data Slice Copying
Argument
Description
-d domainPath
The domain to run the utility.
-copy
Use this option to copy data slices within measures.
-retain
Use this argument if you do not want to move the input file to
the processed subdirectory after a successful run.
-file inputXMLFile
Use this argument to specify the XML file that contains the
configuration settings for the copying operations.
Table 7–22 shows the available settings for the XML input file. This file defines the
configuration settings for the copying operation.
Table 7–22
Section
Attribute
copy
copy
XML Input File Settings
Description
Required Format
Settings for copying operation.
removeSource
Removes source data slices after copying.
Yes
“true” or “false”
A list of measures.
No
Comma delimited
measure names
The measure list is inclusive or exclusive.
Yes, if the
measures
section
exists
“include” or
“exclude”
mask
Mask measure.
No
One Boolean type
measure name
positionMap
Position mapping for the copying
operation.
Yes
The dimension of the mapped positions.
Yes
Dimension name
Two positions. The first one is the position
to copy from. The second one is the one to
copy to.
Yes
Comma delimited
measures
measures
positionMap
positions
option
dim
Figure 7–3 below shows a sample XML input file.
7-48 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Informal Position Manager
Figure 7–3 XML Input File Schema in XSD Format
Figure 7–4 XML Input File Example
Merge Informal Positions to Formal Positions
Below are the steps to merge informal positions to formal positions in a domain.
1.
Create the XML input file by specifying the position pairs to merge. Optionally,
you can specify the measures to update and a mask measure.
Hierarchy Management
7-49
Managing Position Lists as PQDs - pqdMgr
2.
Create the mask measure if you want to use a filter to protect some data slices
from being modified. For example if you want to leave elapsed data alone, you can
create a calendar based mask measure and set all the elapsed cells to false.
3.
Run informalPositionMgr with -copy option to copy the data slices.
4.
Create an input file for the removal of informal positions you no longer need
5.
Run informalPositionMgr with -operation remove to remove those informal
positions.
Managing Position Lists as PQDs - pqdMgr
pqdMgr is a command-line utility used to add and delete Position Query Definitions
(PQDs) using XML-formatted position lists. A position list is a multi-level listing of
positions along a non-Calendar RPAS hierarchy. For example, along the product
hierarchy, a position list could be a single-level listing of SKUs, or it could be a multilevel list of classes, styles, and SKUs. A PQD is used to represent a set of selected
positions in a particular hierarchy. Each PQD is identified by a unique name. A user
can load the PQD instead of performing manual selections on a two-tree wizard.
This utility can be used to load PQDs in master, local, and non-partitioned domains.
PQDs are not shared across local domains. Loading a PQD into a global domain does
not affect any local domain. Similarly, loading a PQD into a local domain does not
impact the master or other local domains.
The input file must be in the following XML file format. This example shows loading
and deleting lists for world and user access levels.
<? xml version="1.0" encoding="UTF-8" ?>
<pqdlists>
<pqdlist name="list_name" hier="hierarchy_name">
<access level="user">
<comma_separated_user_names>
</access>
<dimension name="dimension_name">
<pos>
<position_external_name>
</pos>
</dimension>
</pqdlist>
<pqdlist name="list_name" hier="hierarchy_name">
<access level="world">
</access>
<dimension name="dimension_name">
<pos>
<position_external_name>
</pos>
</dimension>
</pqdlist>
<pqdlist name="list_name" hier="hierarchy_name" operation="delete">
<access level="world">
</access>
</pqdlist>
<pqdlist name="list_name" hier="hierarchy_name" operation="delete">
<access level="user">
<comma_separated_list_of_users>
</access>
</pqdlist>
</pqdlists>
7-50 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Managing Position Lists as PQDs - pqdMgr
pqdMgr Usage
pqdMgr
pqdMgr
pqdMgr
pqdMgr
pqdMgr
-d
-d
-d
-d
-d
domainPath
domainPath
domainPath
domainPath
domainPath
-load xmlFile
-delete xmlFile
-deleteAll
-validate xmlFile
-export outFile [-user userName|-world]
The following table provides descriptions of the arguments used by the pqdMgr
utility.
Table 7–23
Arguments Used by the pqdMgr Utility
Argument
Description
-d domainpath
Specifies the path to the domain.
-load xmlFile
Use this argument to load position lists from an input XML file.
Position lists with an operation attribute of delete are ignored.
-delete xmlFile
Use this argument to delete PQDs as specified in the input XML
file with an operation attribute of delete. Position lists with an
operation attribute of load are ignored.
-deleteAll
Use this argument to delete all PQD lists from the domain.
-validate xmlFile
Use this argument to validate the XML file and report any
errors. No impact on the existing PQD files in the domain.
-export outFile [-user
userName|-world]
Use this argument to export existing PQDs in the domain for a
user or world access level. The file specified by outFile is
overwritten. Requires one of the following options:
■
■
-user userName exports PQDs for the provided userName in
the same XML format as used for a load.
-world exports PQDs with world permission in the same
XML format as used for a load.
pqdMgr Notes
■
■
■
■
■
■
■
Input files are validated before loading. All dimensions, hierarchies, and user
names provided in the input file must be consistent with the existing hierarchies
and registered users in the domain. The utility fails (return a non-zero error code)
if it finds such inconsistencies in the input file. The errors are reported to the
standard output.
Multiple list operations are allowed in the XML input file.
The supported operations are load and delete. If no operation is specified for a list,
the default is load.
The name list_name must be unique within an access level and, if the access level
is user, for the user name.
Each list definition consists of the list name, hierarchy, and access level. One or
more dimension definitions are allowed. One or more position definitions are
allowed for each dimension. Only external names are allowed to describe
positions.
When specifying an access level of user, a single user name or a comma-separated
list of user names is required. A PQD file is created for each user name in the list.
For the access level of world, the PQD file that is created is saved in the following
path:
<domain_root>/wizardPQD/<hierarchy_name>/_world/<list_name>
Hierarchy Management
7-51
Managing Position Lists as PQDs - pqdMgr
■
For the access level of user, the PQD file that is created is saved in the following
path:
<domain_root>/wizardPQD/<hierarchy_name>/<user_name>/<list_name>
7-52 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
8
Data Management
8
This chapter explains the processes involved in RPAS data management.
Loading Measure Data - loadmeasure
The loadmeasure utility is used to load measure data from text files into the domain.
The administrator must specify the measure names and the path to the domain that
contains the measures.
The loadmeasure supports the use of fixed width and CSV (comma separated
variable) files for loading measure data. RPAS recommends the use of CSV files to
reduce the size of the load file and to reduce disk I/O time.
To load measure data, system administrators must copy or create one or more load
files in the input folder of the domain directory. The administrator can then call
loadmeasure to load data.
Example:
Measure A has a base intersection of SKU and a clearint of dept.
If there is data for only a few SKUs (3, 5, and 11) in the incoming file, and SKUs 3 and 5
roll up to dept1 while sku11 rolls up to dept3, the data in all of the SKUs that rolls into
dept1 and dept3 will be cleared.
Figure 8–1 Loading Measure Data
■
The base intersection is SKU.
■
The clearint is dept.
■
Data is present for SKUs 3, 5, and 11; which fall under dept 1 and dept3.
■
Data will be cleared for dept1 (SKUs 1, 2, 3, 4, 5, 6) and dept3 (SKUs 11, and 12).
■
Data for SKUs in dept2 (7, 8, 9, and 10) will be untouched.
Data Management
8-1
Loading Measure Data - loadmeasure
Load File Names and Load Behavior
System integrators must pay close attention to file naming. If a file name has not
specifically been configured in the domain configuration, the file must be named the
same as the same as the measure name, with the appropriate extension depending on
the type of the load.
For example, if the measure is named "rsal" and does not have a filename configured
in the domain configuration, then the basic filename will also be "rsal". This name
should be appended with one of the following extensions to indicate the type of load.
If the load is an overwrite, then the filename should be rsal.ovr; if it is an increment the
file name should be rsal.inc, and so on. If a CSV file is being used, then the load type
extension should be prefixed with the .csv extension; for example, rsal.csv.ovr and
rsal.csv.inc.
RPAS supports the following types of loads (identified by file name extension):
■
.ovr - (Overlay) Existing values in the measure are overlaid with the values in the
input file. Any values not included in the input file are not changed in the
measure.
For string type measures, an empty cell in the ovr file is
treated as a valid string; as a result, the loadmeasure utility overwrites
the previously loaded string with an empty string.
Note:
For other measure types, an empty cell in the ovr file is treated as
invalid data. It is discarded and the previously loaded value is
retained.
■
■
■
.rpl - (Replace) The existing measure is cleared and the values in the input file are
taken as the new values for the measure. Existing values for cells that do not exist
in the load file will be switched to NA. In other words, all data at the base
intersection for the measure will be removed before cells are populated with the
data from the incoming file.
.inc - (Increment) Increment mode should only be used with numeric measures
where the load file contains incremental values. Therefore, if a cell had a value of 2
and the .inc file provided a value of 3 for the cell, the new value for the cell would
be 5 (2 incremented with 3).
.clr - (Clear) Clear mode is a variation of replace mode. It is meant to be used when
measure data is loaded in parts or staggered in time, such that data for all
positions grouped by an aggregate level position is replaced if one or more
positions for that group of positions are being loaded.
In other words, data at the base intersection of a measure will be partially cleared
based on incoming data and the clearint attribute for the measure. The clearint
attribute defines an intersection above the base intersection. All cells at the base
intersection that are descended from a given position at the clearint level will be
removed if there is data in the incoming file for at least one of those descending
positions.
8-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Loading Measure Data - loadmeasure
For example, assume that there are four regions, each with several stores, and the
data is loaded region by region or for a subset of regions at a time. When loading
data, ensure that data for a region is completely replaced with the new load if the
load file has data for one or more stores from that region, but other regions should
be left untouched. This is made possible by clear loads where the clear intersection
(clearint) property of a measure specifies the aggregate level at which to group
positions for completely replacing the data. In this example, the clear intersection
would be at the region level. Clear intersection does not have to be performed
along one hierarchy, but can be performed at the intersection of multiple
hierarchies.
However, if you load multiple .clr files with region as the clear intersection, and
data for one of those regions is in multiple files, then the last loaded .clr file for
that region will replace any information that the previous .clr files loaded for that
particular region.
The loadmeasure utility allows more than one load file to be present in the input
folder at the same time for the same measure. If more than one load file is present in
the input folder at the same time, each will be loaded. Since RPAS has a strict naming
convention for measure file names, in order to add more than one load file at the same
time, integrators must append the filenames as described above with filedistinguishing extensions.
For example, with the file names rsal.csv.ovr.1 and rsal.csv.ovr.2, RPAS does not care
about the form of the multi-file extension. The extensions can be anything, number or
text, and RPAS will still load them.
Notes:
■
■
Backup files should not be named as rsal.csv.ovr.bak, or they will
be loaded as well.
loadmeasure does not guarantee any specific ordering of loads
based on the appended extensions.
The loadmeasure utility also allows multiple types of load files to be present in the
input directory at the same time. RPAS loads .rpl files first, then .clr, .ovr, and .inc files.
Since .rpl files would completely erase existing measure data and then load the given
data, you should not have multiple .rpl files at the same time.
Data Management
8-3
Loading Measure Data - loadmeasure
Loading Multiple Measures from One File
The loadmeasure utility allows multiple measures to be loaded from a single file.
You can loaded measures from CSV Files or Fixed Width Files.
See the “Data Interface Tool” section of the RPAS Configuration
Tools User Guide for more information.
Note:
CSV Files
If a CSV file is used for loading measure data, loadmeasure will use the order that
measures were specified on the command line to determine the order of columns in
the CSV format. For example, if a file named multiple is used to load measures A, B,
and C, where the call to loadmeasure listed the -measure argument as A,C,B, then
when using the CSV file multiple.csv.ovr, loadmeasure will assume that after the
dimension columns, the first column is A, then C, and then B, because that is the order
they were passed in the call to loadmeasure.
It is not necessary to load all measures in a multiple measures file. If a file contains
more columns than the call to loadmeasure requires, the trailing columns are ignored.
If a line in the file does not contain enough columns to hold values for all measures
specified, the line will be skipped. For example, if a file containing three measures
(after the dimension positions), but only one measure is specified in the command line,
only the first measure field will be used and the rest of the line is ignored.
Even though it is not required to specify all measures
contained in the multi-measure CSV file in a single loadmeasure
command, there is no way to skip data columns in the CSV file.
Note:
Fixed Width Files
With a fixed width file, a single measure's data can be loaded from a file containing
multiple measures.
Loading Data from Below the Base Intersection of the Measures
The loadmeasure utility supports loading measure data from an intersection lower the
base intersection of the measure. The load intersection has to be pre-specified in the
configuration (loadint property) and the load time aggregation (loadagg property)
method must also be specified. See the RPAS Configuration Tools User Guide for
information on setting up measure properties.
When loadmeasure loads data from below the base intersection, all low-level data
corresponding to a cell at the base intersection must be available in the load file for
RPAS to be able to correctly aggregate the low-level data to the base level. A fault in
values of a subset of cells that aggregate up to one cell at the base level can only be
corrected by reloading the data for all low-level cells that correspond to the cell at the
base level. If any low-level cells are missing, RPAS substitutes their value with NA.
To perform a lower level load, RPAS first aggregates the data and then applies the
appropriate load type to update the measure value, overwriting the existing value
with the aggregate of the input cells if .ovr files were used, or incrementing the
existing value with the aggregate of the input cells if .inc files were used.
8-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Loading Measure Data - loadmeasure
Staging Measure Loads
RPAS supports the notion of stage-only measures. For stage-only measures,
loadmeasure queues the loaded data in an intermediate staging area, but does not load
it into the measure until it is called with the -applyloads parameter. For stage-only
measures, loadmeasure should be called twice, once to stage the measures and then
with the -applyloads parameter to subsequently load the staged data in the
measure arrays. loadmeasure cannot simultaneously stage loads and apply the
staged loads.
Measure staging should be performed when measure data can arrive from different
sources, in different load formats, and staggered in time, when system administrators
want to queue all these loads up and apply them at once while honoring the data
arrival queue. Measure staging can be performed while the system is online as it does
not cause measure data-related contention (it has the potential to cause metadatarelated contention). When staging measure data, loadmeasure splits the data and
purges the data files if data purging is enabled; it does not purge measure data until
the loads are applied. This staging time preprocessing significantly reduces the load
time when the loads are actually applied.
The replace (.rpl) format cannot be used for staging.
Furthermore, data loads from below the base intersection of the
measure cannot be staged.
Note:
Running Pre-Load or Post-Load Scripts
The loadmeasure utility provides the ability to automatically run scripts before and
after the utility is executed. These are referred to as preprocessing and post-processing
scripts.
When loadmeasure is called, the utility checks for the existence of scripts named
pre<measurename>.sh in the ./scripts directory of the domain. If scripts exist, they will
be run prior to the execution of the utility. Similarly, after the utility has completed
running, the utility checks for the existence of scripts named post<measurename>.sh
and executes them.
When loading multiple measures in a single call, only the preprocessing script for the
first listed measure will have any effect on the data.
Purging Old Measure Data
System administrators can purge old measure data during a load. When the base
intersection of a measure involves the Calendar hierarchy, the setting for the
purgeAge measure property defines how and when existing data gets purged to an
N/A value. If purgeAge has not been set, the data never gets purged. If a purge age
of zero or more has been set, data is purged for all dates that are before RPAS_TODAY
- purgeAge days. That is, if purgeAge is 5, then at data load time, all data that is
older than 5 days before RPAS_TODAY will be purged.
Data Management
8-5
Loading Measure Data - loadmeasure
Behavior in a Global Domain Environment
In a global domain environment, loadmeasure is centralized and can only be called
in the master domain. The loadmeasure utility will load one or more input files that
can contain data from one or all of the local domains within the given global domain
environment. The utility will then split the input files and load them into the required
domain, which is the local domain to which the position belongs, or the master
domain if the measure has a base intersection above the partition level. The split will
only occur once in the case of multiple measures. Local domains will be checked for
files even if there is no file in the global domain. The utility can be run in parallel in a
global domain environment.
loadmeasure Usage
loadmeasure -d pathToDomain -measure measureName{,measureName,…} {-applyloads}
{-processes max} {-noClean} {-forcePurge}{-splitOnly | -noSplit} {-defrag}
{-loglevel level} {-recordLogLevel level} {-inDir inputDirectory}
The following table provides descriptions of the arguments used by the loadmeasure
utility.
Table 8–1
Arguments Used by the loadmeasure Utility
Argument
Description
-d pathToDomain
Specifies the domain in which to load the measure.
-measure measureNames
Specifies the name of the measures to load.
Measure names must be lowercase (for example, measurename1,
measurename2, measurename3).
If more than one measure is specified, all the measures must be in
the same input file.
-applyloads
Use this argument to apply any staged loads for the named
measure.
If the measure is registered to be a stage-only measure,
loadmeasure will put the load in a staging area but will not update
the measure until loadmeasure is called again with this argument.
Upon the use of this argument, loadmeasure will apply all loads
that have been queued up in the staging area. It will clear out the
staged loads unless the measure's loadsToKeep property has been
set to a non-zero number. In that case, it will not clear out the latest
loadsToKeep loads.
Note that only .ovr, .inc, and .clr loads can be staged. .rpl loads
cannot be staged. Additionally, staging is only allowed for base
intersection loads. RPAS cannot stage loads where load
intersection is below the base intersection of the measure.
This argument should not be used for measures that are not stageonly.
-processes max
This argument specifies the maximum number of child processes
for parallel splitting of files and loading of measures across local
domains in a global domain environment. For instance, if you
specify 5 as the maximum number of processes, then up to 5 child
processes can run concurrently in the split or load operations.
If this argument is omitted or if only one process is specified, the
application will perform all processing in a single process and no
child processes will be created.
This only specifies the number of child processes. The controlling
process is not included (max + 1 is the actual number of processes).
8-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Loading Measure Data - loadmeasure
Table 8–1 (Cont.) Arguments Used by the loadmeasure Utility
Argument
Description
-noClean
Use this option to prevent the input files from being moved to the
processed directory.
This option is meant for use when a single file is used to load
multiple measures, but not all measures from the file are loaded at
once. The use of this option instructs loadmeasure to leave the
load file behind for subsequent loading of unloaded measures.
The user might want to use this option to perform intermediate
processing between loads of measures available from the same file.
-forcePurge
Force the purge routine to run even if no new data is loaded. This
purges old measure data.
This option can be applied to stage-only measures without having
to apply loads.
When a measure has the Calendar hierarchy in its base
intersection, the setting for the purgeAge measure property
defines how and when existing data gets purged to a N/A value.
If purgeAge has not been set, the data never gets purged. If a
purge age of zero or more has been set, data is purged for all dates
that are before RPAS_TODAY -purgeAge days. That is, if
purgeAge is 5, at data load time all data that is more than 5 days
before RPAS_TODAY will be purged.
This option does not require you to load any new data.
-loglevel level
Use this argument to set the logger verbosity level.
Possible values: all, profile, audit, information, warning, error, or
none.
-noSplit
Use this argument to load the pre-split input files (created by
-splitOnly) into the local domains. This option should only be used
in global domain environments.
-splitonly
This argument causes the input files in the global domain to be
split across the local domains, but does not do any further
processing of the input files. Subsequently, loadmeasure can be
used with the -noSplit argument to load these pre-split input files
into the local domains.
File-splitting is a fairly time consuming activity and can consume
up to 80% of the load time. System integrators may be able to
improve batch performance by breaking away file-splitting from
actual measure loading. This is specifically useful if a multimeasure file is being used such that subsets of measures are
loaded at different steps in a batch process.
The file can be split with multiple processes by specifying the
-processes argument.
This option should only be used in global domain environments.
-defrag
This argument can be used to defragment the domain at the end of
the measure loading process to reduce the physical size of the
domain. This space-saving is achieved by replacing the existing
fragmented pages with copied, fully populated BTree database
pages.
Data Management
8-7
Loading Measure Data - loadmeasure
Table 8–1 (Cont.) Arguments Used by the loadmeasure Utility
Argument
Description
-recordLogLevel level
This argument is used to set a logging level for record loading
issues. Issues such as parsing errors, missing positions, and data
conversion errors are evaluated for every record in the measure
load file. By default, these are logged as errors in the log file of the
loadmeasure utility. However, customers might want to
downgrade the logging level for such record loading issues. They
can do that with the use of the -recordLogLevel level argument.
The standard log levels, error, warning, information, and profile,
can be used as parameters to this argument.
When logging, loadmeasure compares this logging level to the
utility's logging level (set using -loglevel). If the utility's logging
level is less verbose than the record logging level, then record
issues will not be logged. If utility's logging level is at same or
higher verbosity as the record logging level, the record issues will
be logged with the log indicator as set using this argument.
-inDir InputDirectory
Only .rpl files can be used with this option, and only CSV format
with header line is supported. The header line is used to
correspond the columns to dimensions and measures (for
example: SKU,STR,DAY,Sales). Enter one measure per input file.
The name of the measure is extracted from the file name; for
example, sales.csv.rpl corresponds to measure sales.
The input data must be at the base intersection of the measure.
If the measure is normally partitioned (non-HBI), a sub-domain
index may be used for further performance optimization by
avoiding the data splitting step. For measure that may contains
duplicate positions in different sub-domains (FnHBI measures),
the sub-domain index is required. In either case, the name of the
file is used to figure the sub-domain index (for example,
sales.0.csv.rpl corresponds to the first local domain; sales.1.cvs.rpl
corresponds to the second local domain, and so on).
Note: The sub-domain index is designed to be used in conjunction
with exportMeasure -hier only. Manual name-indexing of the
files is not recommended.
The filename property of the measure is not considered with the
-inDir option.
8-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Exporting Measure Data - exportMeasure
Loading Image Paths for Positions
A configuration and backend process may also be used to support the load of image
paths for one or more positions of a dimension at a time. The paths of the images
should be stored in a measure called r_images_<dimension name> where <dimension
name> should be replaced with the RPAS Name of the image-enabled dimension (for
example, r_images_sku if loading image paths for the sku dimension). This measure is
single-dimensional, defined on the image enabled dimension. An .ovr file is required
with position names and the image paths for those positions formatted according to
the RPAS measure load formats. The loadMeasure utility is then used to load this data
into the domain.
Note: See the RPAS Configuration Tools User Guide and the "Position
Images" section in the RPAS User Guide for the Classic Client for more
information on Image Display.
Example
loadmeasure -d <domain path> -measure r_images_sku
<domain path> is the path to the domain.
Exporting Measure Data - exportMeasure
exportMeasure is a command-line utility that may be used to export domain or
workbook measure data from RPAS in either CSV or fixed width file format. A single
measure, or multiple measures, may be exported based a specified intersection. If the
measure's base intersection is not the same as the export intersection, the measure's
default aggregation method will be used to aggregate data to an intersection higher
than base, or replication will be used for spreading measure data if the data is required
at an intersection lower than base. This utility:
■
■
Supports export of data in a user specified range, which can be a single mask
measure, or a range specified on Calendar dimension, or a combination of the two.
Supports multiple processes for better performance in a global domain
environment.
exportMeasure allows multiple measures to be exported into
the same file when multiple measure names are provided. The same
measure name cannot be specified more than once (using comma
separation) in a single call; therefore, a measure can be exported only
once per file.
Note:
exportMeasure Usage
exportMeasure -d pathToDomain -out outFile [COMMAND] [OPTIONS]
The following table provides descriptions of the arguments used by the
exportMeasure utility.
Table 8–2
Arguments Used by the exportMeasure Utility
Argument
Description
-d pathToDomain
Specifies the path to the domain.
Data Management
8-9
Exporting Measure Data - exportMeasure
Table 8–2 (Cont.) Arguments Used by the exportMeasure Utility
Argument
Description
-out outFile
Specifies the output file name. It is required and must be a valid
file name including the path.
-wb wbname
If specified, exportMeasure exports data from the specified
workbook (wbname). A valid workbook name must be used.
-intx intxString
Specifies the intersection at which to export measures. If
measure's base intersection is higher than the export
intersection, replication is used to spread the measure down to
the export intersection. If measure's base intersection is lower
than export intersection, the measure's default method (defagg)
is used for aggregation.
The export intersection must be either at, above, or below the
base intersection of the measure. The export intersection cannot
have some dimensions above the dimension in the base
intersection of the measure and some below.
The RPAS dimension names in an intersection should be four
characters in length. If a RPAS dimension name is less than four
character long, then an underscore character ("_") should be
used as a filler at the end of a dimension name.
-mask measureName
Specifies a mask measure which must be a valid Boolean
measure registered. In current measure store, its baseintx must
be at same export intx.
-range start:end
Specifies a range of positions along the innermost dimension.
Only values in the range are considered for export.
-processes max
Defines the maximum number of processes to run in parallel.
-append
Appends new output to current output file. If not specified,
current output file will be erased and replaced with new data.
-nomerge
If run in a global domain environment and exporting
intersection below partition dimension, and have processes set
greater than 1, specifying nomerge will stop exportMeasure
from merging multiple output files created from each local
domain to the master output file. Output files created from local
domain will be stored at masterdomain/output/
exportMeasure[TS] folder, where [TS] represents a timestamp.
Files are named as out000X.txt, where 000X is the index of the
local domain.
-compress
Specifies the output file should be in the compressed CSV
format.
-hier hierarchy1, hierarchy2
Exports all measures for hierarchies. It exports only measures
that have storage in the domain. Multiple hierarchies can be
specified in a comma-separated list.
-outDir outputDirectory
Updates the output directory. If the output directory does not
exist, the utility creates one. The measure names are used to
generate the output file names. A CSV file with a header line can
identify the dimensions of the base intersection and the name of
the measure that is generated for each file. The files always have
a csv.rpl extension (e.g. sales.csv.rpl). Old files are overwritten.
One output directory is created for each HBI measure. In
addition, one file is created for each non-HBI or FnHBI measure
per sub-domain.
The file names contain an internal sub-domain index, for
example sales.0.csv.rpl, sales.1.csv.rpl, and so on.
8-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Exporting Measure Data - exportMeasure
Table 8–2 (Cont.) Arguments Used by the exportMeasure Utility
Argument
Description
-upperCase
This argument converts the position names to all uppercase
before writing the output data file. Without this argument,
position names are in lowercase since they are stored in
lowercase in the domain.
-meas "measSpec, measSpec
…"
Must specify one. measSpec is measName.modifier. The -meas
argument may be repeated to export multiple measure arrays to
the same output file.
modifier include the following:
.precision<double>, specify the precision for numeric measure
.format<formatString>, specify the user defined export format
The examples below provide valid measure specifications given
MeasNameA is a valid real type measure.
Examples:
-meas
-meas
-meas
-meas
MeasNameA
MeasNameA.precision(0.0001)
MeasNameA.format("%13.2f").precision(0.01)
MeasNameA.precision(0.01).format("%13.2f")
For specifying date and time, the following formats are
supported:
%Y - four-digit year
%y - two-digit year
%m - month
%d - day
%B - full name of the month
%b - three character abbreviation for the month
%H - hour
%M - minute
%S - second
%s - milli-second
The examples below provide valid measure specifications given
MeasNameB is a valid date/time type measure.
Examples:
-meas MeasNameB
-meas MeasNameB.format("%Y%m%d")
-meas MeasNameB.format("%d%B%Y%H%M%S")
Data Management 8-11
Exporting Measure Data - exportData
Exporting Measure Data - exportData
Use exportData to export measure data from RPAS into text files. Each line that is
exported contains the position name for the exported dimension followed by the value
in the cell for each array being exported.
More than one array may be exported and more than one
dimension in each array can be exported.
Note:
The utility may be invoked by specifying all parameters on the command line or by
specifying an array that contains a list of the parameters.
When running this utility in a global domain environment, the utility should only be
called to export data from the master domain. The utility will extract the data from
either the local domains or the master domain depending on where the data resides,
which depends on the level at which the global domain environment is partitioned.
The parameters specify what arrays and dimensions are exported and how to format
the data. It is best to specify the arrays first. An array specification begins with -array
followed by the array information. This includes the array name, formatting string,
NA cell value, and NA cell value formatting string. The formatting string for both the
cell value and NA value is based on the C language printf function formats. See the
documentation on the printf for more information on the possible values. The -array
parameter can be repeated as needed to export more than one array into the same
export file. Remember that the order the arrays appear in the -array parameter is the
order that they will appear in the export file.
After the arrays have been specified, the administration must specify the dimensions
to be exported within the arrays. The -dim parameter is used to specify a dimension in
an array. The -dim parameter is followed by the dimension name, a convert option, the
formatting string (just like an array), and the order the dimension appears in the
export file. Because arrays are not required to contain identical dimensions, it is
important to list all dimensions in all arrays with the -dim parameter. This makes it
possible to track dimensions across arrays and line the data up correctly. If a
dimension in an array is not to be in the export file, set the last value of this parameter
to 0. The conversion option specifies either the number of characters to be removed
from the position name or it specifies an array that contains the real position name. If
an array name is given, this array must be a vector. The function will go to this array
and use the original position name to jump to the cell of the same position name. It
will then get the cell value and use that as the position name in the export.
It is possible to specify the number of decimal places when exporting numeric
measures of data type real. This setting is defined in the specifications for measures,
arrays, and dimensions (measSpec, arraySpec, and dimSpec). The format is
%[.precision]type where [.precision] is the number of decimal places and type is the
letter f. For example, the setting %.2f would export numbers with two decimal places.
Other settings are provided below.
If all parameters are contained in an array, after the export file name and source
database name, the -params parameter is used to specify the database name and array
name that contains all of the parameters needed for the export.
Either the-array, -meas, or -params parameters must be
specified when using this utility.
Note:
8-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Exporting Measure Data - exportData
exportData Usage
exportData -d domainPath -out outputFile -params db array
exportData -d domainPath -out outputFile -array \"arraySpec\" {options}
exportData -d domainPath -out outputFile -meas <measspec> | -array <arrayspec> |
-params <paramspec> -wb <wbName> {options}
The following table provides descriptions of the arguments used by the exportData
utility.
Table 8–3
Arguments Used by the exportData Utility
Argument
Description
-d domainPath
Specifies the domain that contains the data that to export.
-out outputFile
Specifies the file that will contain the exported data.
The outputFile is relative to the domain unless the full path is
specified.
-meas \"measSpec\"
Specifies the measures to export.
measSpec must be quoted, and the format is
\"measName cellFormat naValue naFormat\"
The -meas argument can be repeated to export multiple measure
arrays to the same output file.
Measures are exported at the base intersection.
-array \"arraySpec\"
Specifies the array to export.
arraySpec must be quoted, and the format is
\"dbName|arrayName cellFormat naValue
naFormat\"
■
■
dbName can be a path to the database (relative paths are
relative to the domain root).
Both cellFormat and naFormat use printf format commands.
See the printf function for more information on the possible
values.
The -array argument can be repeated to export multiple arrays
to the same output file.
The order in which arrays are listed is the order in which they
will be exported.
Note: This argument cannot be used in a global domain
environment and can only be used in simple domains. This
argument cannot be used with -useLoadFormat.
-params db array
Instead of specifying all parameters on the command line, this
parameter allows the parameters to be read from an array.
■
■
db specifies the name of a .ary file where the array of
parameters is stored.
array specifies the name of an array in the specified database
that has the above parameters.
-wb WbName
Use this argument after specifying any of the command
arguments: -array, -meas, or -params.
-append
Specifies that output is appended at end of output file. The
default is to overwrite output file.
Data Management 8-13
Exporting Measure Data - exportData
Table 8–3 (Cont.) Arguments Used by the exportData Utility
Argument
Description
-dim \"dimSpec\"
Specifies the dimension to be exported.
■
■
■
■
dimSpec must be quoted, and the format is \"dimName
conversion format order\"
conversion is either a count of the number of characters to
strip from the start of the position name or the name of an
array to be used to translate the position name before
writing to the output file.
format is a printf-style format for the position names. See
the printf function for more information on the possible
values.
order indicates the order the dimension is listed in the
output file.
If the value is 0, then the dimension is not exported.
The -dim parameter can be repeated.
The -dim parameter is not allowed with the -useLoadFormat.
When using with the -wide parameter, the -dim parameter
should not be used for the innermost dimension.
-skipNA
always|allna|anyna|arrayna
Controls whether a line of data is exported based on having NAs
in a cell.
■
■
■
■
always exports data regardless of whether or not it contains
NAs.
allna does not export a row of data if all columns are NA
(default).
anyna does not export a row of data if any cell contains a
NA value.
arrayna does not export a row of data if the value in the
given array name is NA (requires -naArray).
-naArray arrayName
When arrayna is specified using the -skipNA parameter, this
option specifies the export array that is checked to determine if
data is exported.
-wide
This parameter causes the data to be exported wide, which
means the innermost dimension will go across the row instead
of each cell on a separate line.
This is most useful when the innermost dimension is time.
The -range parameter can be used in conjunction with wide
format (-wide) to specify a range along the innermost
dimension.
The -dim parameter should not be used for the innermost
dimension when -wide is being used.
-range start:end
Used to limit the export to positions in the range. The range can
only be specified for the innermost dimension.
May be used in conjunction with the -wide parameter.
-time
Specifies the YYYYMMDD format for dates.
8-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Exporting Measure Data - exportData
Table 8–3 (Cont.) Arguments Used by the exportData Utility
Argument
Description
-precision precisionValue
This parameter causes the utility to avoid exporting values that
differ from the NA value by the specified value.
Any values smaller than the precision value are not exported.
For example, consider a measure with the NA value of zero and
a precision value of 0.01. A value of 0.0034 would not be
exported while a value of 0.34 would be exported.
The precision value must be less than one.
If a value greater than one is provided the utility returns a
warning.
-processes max
Defines the maximum number of processes to run in parallel.
-useArrayNaValue
This argument enables the use the NA value of the array instead
of the NA value specified in measSpec or arraySpec.
-upperCase
This argument converts the position names to all uppercase
before writing the output data file. Without this argument,
position names are in lowercase since they are stored in
lowercase in the domain.
-displayArrayNaValue
This argument controls the display of measures used as a mask
in -naArray option. The default is to not display the mask NA
measure value. However, if this option is specified, then the NA
Array measure values are also exported.
-useLoadFormat
This argument enables the use of the format as specified by the
measure property. The level at which the data is stored in the
domain will be used. The -dim parameter is not allowed with
the -useLoadFormat.
-useLoadFormat Parameter
Use the format specified by the measure's loading format to export the measure. This
loading format includes Start and Width, which defines the column that corresponds
to this measure's data in the measure load file. The measure will be exported into the
same column in the output file. If the full measure export specs are not provided
including the cellFormat, naValue and naFormat, the default format will be used. The
default export format for each type of measure is listed below:
■
Integer: %<width>.0f
■
Real: %<width>f
■
String: %<width>s
■
Date: %Y%m%d
■
Boolean: TRUE or FALSE as string
All value will be exported right aligned as in the measure loading file.
If users give a full measure specs, user-specified cellFormat, naValue, and naFormat
will be used rather than the default format.
Users can either use the default format by specify the measure name only, or give the
full specs. It is not allowed to give a partial measure spec.
Data Management 8-15
Mapping Data Between Domains - mapData
If users specify multiple measures to be exported into the same file, these measures
will each occupy a column in the file defined by its start and width attributes. If two
measures occupy the same column, exportData will throw an exception with an error
message saying "overlapping measures in the output file" and exit. If a measure's
column is overlapping with the columns occupied by the position names, exportData
will throw an exception with an error message saying "measure column is overlapping
with position columns" then exit. Basically, if the measure cannot be exported correctly,
exportData will not try to export it but simply exit and alert user with a proper
exception.
The -dim and -array parameters are not allowed if -useLoadFormat is used. All
dimensions in the measure's base intersection will be exported by default. The external
position name will be exported to the export file, in the order specified by the
hierarchy's order attribute, usually in the order of CLND, PROD, and LOC. The
position names will be left aligned in the export file.
Mapping Data Between Domains - mapData
The mapData utility is used to move data from one domain to another. Specifically, it
copies data from an existing domain, database, or array to a new domain, database or
array.
Before running this utility, the new hierarchy must be loaded in the destination
domain. After mapData has copied data, administrators can purge the source domain
by calling loadHier with a purge age of 0. Tasks such as hierarchy loading, hierarchy
purging, and the validation of source and destination domains are performed outside
of this utility.
Note:
This utility does not update buffer positions.
mapdata Usage
mapdata -d SrcPath -dest destPath [-db dbName [-array arrayName]]
{-db dbName {-array arrayName}} {-loglevel}
The following table provides descriptions of the arguments used by the mapData
utility.
Table 8–4
Arguments Used by the mapdata Utility
Argument
Description
-d SrcPath
Specifies the path to the source domain.
-dest DestPath
Specifies the path to the destination domain.
-db dbName
Apply mapdata only on the given database. Must be a valid file.
If this argument is not specified the entire domain will be
included in the operation.
-array arrayName
Apply mapdata only on the given array. The database in which
the array resides must be specified with the -db argument.
8-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Moving Data Between Arrays - updateArray
Moving Data Between Arrays - updateArray
The updateArray utility moves data from a source array to a destination array. The
destination array must contain the superset of dimensions in both source arrays. The
source array's dimensions may be at the same or higher level as mapped by the
dimension dictionary. If a dimension in the source array is at a higher level, the results
are spread across the lower level dimension in the destination. If there are extra
dimensions in the destination array, the results are replicated across these extra
dimensions. The NA value of the destination array remains unchanged.
To limit the scope of the update, a mask array and an innermost range may be
specified. If a mask array is given, the update is limited to cells in the source array for
which the corresponding mask cell is on. If an innermost range is given for source or
destination array, the update is limited to cells that are within the start and end of this
range on the innermost dimension. If the source and destination arrays are not in the
same domain, the measure store associated with the source domain is used to find
hierarchy information.
Note:
This utility does not update buffer positions.
updateArray Usage
updateArray -destArray dbPath.arrayName {-srcArray dbPath.arrayName}{-destDomain
domainPath {-srcDomain domainPath} {-maskDomain domainPath} {-maskArray
dbPath.arrayName} {-updateMethod method} {-srcRange first:last} {-destRange
first:last} {-srcScalar scalarCell} {-version} {-loglevel level}
updateArray -argFile filename {-version} {-loglevel level}
The following table provides descriptions of the arguments used by the updateArray
utility.
Table 8–5
Arguments Used by the updateArray Utility
Argument
Description
-destArray
dbPath.arrayName
Required argument to specify the destination array where the
data will be copied.
dbPath is relative to destDomain.
-srcArray
dbPath.arrayName
Optional argument. Default is no source array.
-destDomain domainPath
Optional argument.
Note: This parameter cannot be used with -srcScalar scalarCell.
Default is current working directory.
-srcDomain domainPath
Optional argument.
Default is current working directory.
-maskDomain domainPath
Optional argument.
Default is current working directory.
Data Management 8-17
Scan Domain Data - scanDomain
Table 8–5 (Cont.) Arguments Used by the updateArray Utility
Argument
Description
-updateMethod method
Optional argument.
Default is OVERLAY.
The following update methods are available:
■
■
-srcRange first:last
SKIPNA - Omit NA cells in source.
SKIPPOP - Omit populated cells in source. OVERLAYNA Update NA cells in destination.
■
OVERLAYPOP - Update populated cells in destination.
■
OVERLAY - Update all cells in destination with source.
Optional argument.
Default is no range.
Defines range along innermost dimension of source array.
-destRange first:last
Optional argument.
Default is no range.
Defines range along innermost dimension of destination array.
The position names of the innermost dimension are the range
value. For example, if the range values is one week, the range
should be specified as
-srcRange WEEK200811011:WEEK200811022
-destRange WEEK200811011:WEEK200811022
-srcScalar "TYPE:VALUE" Optional argument.
Default is NA cell.
Format for scalar cell is one of:
■
NUMERIC: numeric value
■
STRING: literal value
■
BOOL: Boolean value
■
NA
Note: This parameter cannot be used with -srcArray
dbPath.arrayName.
Scan Domain Data - scanDomain
The scanDomain utility is a domain utility used for detecting data loss and repairing
data corruption in an RPAS database.
Data loss occurs when an RPAS process is abnormally terminated. This can happen
when an external mechanism, such as a power failure, causes a sudden termination of
an RPAS process. Data loss can also occur due to unexpected program breakdown.
Data corruption can occur if an external program modifies the RPAS database files or
an unforeseen defect occurs in the processes using the RPAS database (an extremely
rare event).
The scanDomain utility can detect both corruption and data loss, but it can only fix
corruption. This utility can operate on global, non-partitioned, and local domains. It
supports parallelization when repairing databases in a domain.
8-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Scan Domain Data - scanDomain
While attempting to perform a repair of the databases, the utility has a command line
option (-backup) to enable backing up the original databases. While running in
detection mode (-detectDataLoss or -detectCorruption option), the utility does not
change any of the RPAS databases, and therefore, it does not create such backups.
In detection mode, the utility prints a list of databases with data loss or data
corruption to the screen. The output can be directed to a file.
scanDomain Usage
scanDomain -version
scanDomain -d domainPath [-detectDataLoss ] [-detectCorruption] [-loglevel level]
[-noheader]
scanDomain -d domainPath -repairCorruption [-backup][-processes
maximumNumberOfProcesses] [-loglevel level] [-noheader]
scanDomain -d domainPath -listUnusedData outputFile [-processes
maximumNumberOfProcesses] [-loglevel level]
scanDomain [-?|-help|-usage]
If the user intends to detect both corruption and data loss, it is more efficient to run the
utility once with both the -detectDataLoss and -detectCorruption options. The user
could run two consecutive commands for detecting corruption and data loss, although
this would be less efficient.
When running scanDomain to detect unused data, the user is presented with a list of
databases that may not be needed by the domain. This information includes:
■
■
■
User directories for users who are not registered in the domain
Measure databases whose corresponding measures have been removed from the
domain
Other databases not referenced by the domain (for example, measure load
databases, backup databases, and temporary databases)
The data contained in the specified databases may not be needed by the domain. If the
user can confirm that the data is actually unnecessary, then the user can remove those
databases before proceeding with the upgrade.
The following table provides descriptions of the arguments used by the scanDomain
utility.
Table 8–6
Arguments Used by the scanDomain Utility
Argument
Description
-version
Prints the version of the utility.
-d domainPath
Required argument to specify the path to a global, nonpartitioned, or local domain.
-detectDataLoss
Checks for data loss in the specified domain.
-detectCorruption
Checks for database corruption in the specified domain.
-repairCorruption
Repairs the database corruption in the specified domain.
Note: This argument cannot be used with -detectDataLoss or detectCorruption.
-backup
Optional argument to back up database files before attempting
to repair them.
Note: This argument can only be used with -repairCorruption.
Data Management 8-19
Repair Domain Metadata - fixDomain
Table 8–6 (Cont.) Arguments Used by the scanDomain Utility
Argument
Description
-listUnusedData
Lists potentially unused data in the domain. Information about
this unused data is output to a file whose location is passed as
the outputFile argument.
-processes
maximumNumberOfProcesses
Optional argument to specify the maximum number of
processes to be started to repair Btree database corruptions.
Note: This argument can only be used with -repairCorruption.
-loglevel level
Optional argument to set the logger verbosity level. Possible
values: all, profile, debug, audit, information, warning, error, or
none.
-noheader
Optional argument to disable the timestamp header.
-?|-help|-usage
Optional argument to get the usage text.
Repair Domain Metadata - fixDomain
Discrepancies in the metadata of a domain can cause serious problems during domain
operations, and such discrepancies can be difficult to correct. The fixDomain utility
analyzes a domain in order to detect problems in the metadata of a domain and can be
used to attempt to fix any detected problems.
By default, fixDomain runs in report-only mode. Users should run fixDomain in this
mode first in order to detect discrepancies in the metadata. Should any problems be
discovered, fixDomain provides functionality to fix certain problems in the metadata
of the domain.
8-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
9
Operational Utilities
9
This chapter describes the following operational utilities of RPAS:
■
Find Alerts - alertmgr Utility
■
Copying Domains - copyDomain Utility
■
Move a Domain - moveDomain Utility
■
Setting Miscellaneous Domain Properties - domainprop Utility
■
Calculation Engine - mace Utility
■
Managing the Workbook Batch Queue - wbbatch Utility
■
Workbook Manager - wbmgr Utility
■
Register Measure - regmeasure Utility
■
Register Token Measure - regTokenMeasure Utility
■
Batch Plug-In Tasks: execPluginTask.sh
Find Alerts - alertmgr Utility
Alerts are an exception management tool for users. An alert is a measure that
evaluates a business rule (returning a value of true or false). RPAS then notifies users
of the "true" conditions and allows users to build workbooks to resolve the scenario
that drove the alert.
Alert measures are first defined in the domain using the RPAS Configuration Tools.
These measures are of type Boolean, which means they have a value of true or false.
Next, rules (expressions) are registered in the domain for the alert measures to define
the business rules used to evaluate the alert.
After the registration process is complete, the alert utility is run to find the alerts in the
domain. After the alert finder has been run, the identified alerts can be viewed in the
Alert Manager window in the RPAS Classic Client.
The following is a summary of the process for defining and finding an alert:
1.
Create an alert measure. This must be a Boolean measure (values are true-false, or
yes-no) and must be defined in the RPAS Configuration Tools. Its aggregation state
and base state must be read-only.
2.
Create the alert (the expression) for which the alert should be evaluated using the
Configuration Tools. Using alertmgr, register the alert with a category,
categoryLabel, and the above expression. This flags the registered measure as an
alert so that it is recognized when the alert finder is run.
Operational Utilities
9-1
Find Alerts - alertmgr Utility
3.
Repeat steps 1 and 2 for any additional alerts to be registered in the domain.
4.
Run the alert finder on the domain to evaluate the number of instances when one
or more alert expressions are true. This operation is completed using the RPAS
utility alertmgr.
alertmgr Usage
alertmgr -d domainPath [COMMAND [parameters]]
alertmgr -d pathtodomain -findAlerts {-navigationThresholdhits} {-alerts "a1 a2 …"
| -categories "cat1 cat2 …"}
This utility includes arguments that are not documented in
this guide as it is recommended that those operations be configured
using the Configuration Tools to ensure consistency between the
configuration and the domain.
Note:
Table 9–1 provides descriptions of the arguments used by the alertmgr utility.
Table 9–1
Arguments Used by the alertmgr Utility
Argument
Description
-d pathToDomain
Specifies the directory in which to run the utility. All commands
except -version require -d domainPath.
-findAlerts
Finds alerts in the specified domain. The utility will find all
alerts in the domain if neither the -alerts or -categories
arguments are specified. If -alerts or -categories list is not
specified, findAlerts is run on all alerts. findAlerts can be run
from either Master or Local Domains.
-alerts a1 a2…
Evaluate specific alerts in the domain. a1 a2 … must be valid
names of alerts that are defined in the domain.
-categories cat1 cat2 …
Evaluate all alerts in the domain that are associated with specific
categories of alerts. cat1 cat2 … must be valid names of alert
categories that are defined in the domain.
-sumAlerts
-sumAlerts sums up the hit counts of alerts across local domains.
It can be run based on a list of alerts or alert categories. If none
are provided, then the respective hit count of each alert across all
local domains is summed. -sumAlerts can be used only from
Master Domain.
Note: -findAlerts must be run first to generate hit counts of
alerts.
-navigationThreshold
hits
The maximum number of alert hits for Find Next/Previous Alert
functionality to remain operational in a workbook. If over that
threshold, the Find Alert functionality will only work up to that
number. The default value is 5000.
alertmgr can be run on the local domains individually. The
administrator may spawn several processes in parallel, and when
needed, run alertmgr -sumAlerts again to aggregate the results to the
global domain. If parallelization is desired, the administrator should
create a script to spawn the parallel processes.
Note:
9-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Copying Domains - copyDomain Utility
Copying Domains - copyDomain Utility
The copyDomain utility is used to copy a simple domain, all domains included in a
global domain environment, or a subset of domains in a global domain environment.
Domains are often copied before upgrading the domains after receiving a patch to
RPAS.
For a standard, simple domain (in other words, not a global domain environment),
copyDomain copies the domain directory recursively from one location to another.
For a global domain environment copyDomain copies the master domain to the
specified destination, and then it copies each local domain into corresponding
subdirectories of the new location. As part of this particular replication process, the
utility also updates all relevant data structures so that the domains are properly
connected together.
Relative paths are supported with this utility and are used when creating the new
copies of all the underlying data structures (arrays). Relative paths are based on the
full pathname of the domain's root directory.
copyDomain Usage
copyDomain -xmlConfigFile filename {OPTIONS}
copyDomain -d pathToSrc {OPTIONS}
copyDomain -version
Table 9–2 provides descriptions of the arguments used by the copyDomain utility.
Table 9–2
Arguments Used by the copyDomain Utility
Argument
Description
-d
pathToSrcDomain
Specifies the path of the domain to be copied. This argument and -dest
should not be used with -xmlConfigFile.
-xmlConfigFile This argument allows copyDomain to copy each subdomain into userpathToXmlConfigFil instructed specific locations.
e.xml
This argument should not be used with -d OR -dest.
See the copyDomain: Format of the XML Configuration File section for the
file format.
The following arguments are valid for -xmlConfigFile and -d:
-force
Deletes the existing domain at the specified destination path before
copying the source domain.
-clone dimposlist
Use this argument to copy a subset of a domain environment. Copies only
positions specified in a format as dim1,pos1,...,posn:dim2,pos1,...,posn
where the sequence dim1,pos1,...,posn specifies the selected positions
along dim1. Multiple dimensions may be specified, but only one
dimension per each hierarchy is allowed.
Deprecated. Use -clone instead.
partitionPosit
ions positions
-copyWorkbooks
workbookList
Copies only the specified workbooks to the destination location.
-skipInput
Do not copy the input directory located in the source domain.
-skipConfig
Do not copy the config directory located in the source domains.
workbookList is either a comma-separated list of the workbooks to copy, or
the value none such that no workbooks are copied. If this argument is not
specified all workbooks in the environment are copied.
Operational Utilities
9-3
Copying Domains - copyDomain Utility
Table 9–2 (Cont.) Arguments Used by the copyDomain Utility
Argument
Description
-skipEmptyDir
Do not copy the empty directory located in the source domain.
-maxProcesses
count
If this argument is specified, some parts of copyDomain run in parallel,
utilizing up to the given number of processes.
-noSubDomains
Do not copy any local domains in the source domain.
The following arguments are valid only with -d:
-dest
pathToDestDomain
Specifies the path to where the domain is to be copied. The copied domain
can also be renamed in this step by providing a name different than the
source domain.
This argument must be provided when using any other option (other than
-xmlConfigFile or -relativizePaths) of the utility. If this argument is not
provided, the domain is updated to have relative paths.
-export
Export each database from the source domain into a format that can be
used on a UNIX platform. This argument cannot be used when specifying
an -xmlConfigFile.
-gzip
Compress the copied domain into a gzip format. This argument cannot be
used when specifying an -xmlConfigFile.
-dimDictOnly
Copies only the source domain structure, metadata, and hierarchy data.
Running copyDomain with this option result in a non-functional domain.
Therefore this argument should be used for diagnostic purposes only.
Updates the existing master and subdomain path references to relative
relativizePath paths.
s
If the current absolute path references are invalid paths, subdomains are
searched for in the same location as the master and within the master
domain directory. When this argument is used, no domain copy is made.
Note: When using this argument, do not provide a destination with the dest argument.
For example, if you build a domain, this is what it looks like at first:
(PGRP100 INFO):
"C:\Oracle\Domains\1323\mfprtl\ldom3"
(PGRP200 INFO):
"C:\Oracle\Domains\1323\mfprtl\ldom3"
(PGRP21 INFO) :
"C:\Oracle\Domains\1323\mfprtl\ldom0"
(PGRP22 INFO) :
"C:\Oracle\Domains\1323\mfprtl\ldom1"
(PGRP300 INFO):
"C:\Oracle\Domains\1323\mfprtl\ldom3"
(PGRP31 INFO) :
"C:\Oracle\Domains\1323\mfprtl\ldom2"
(PGRP32 INFO) :
"C:\Oracle\Domains\1323\mfprtl\ldom2"
This tells you, by partition dimension, the path to the local domain. You
can see that it is a full path and that the domains are subdirectories of the
master domain. If you then run copyDomain with the -relativizePaths
option, the paths look like the following:
(PGRP100 INFO)
: "ldom3"
(PGRP200 INFO)
: "ldom3"
(PGRP21 INFO)
: "ldom0"
(PGRP22 INFO)
: "ldom1"
(PGRP300 INFO)
: "ldom3"
(PGRP31 INFO)
: "ldom2"
(PGRP32 INFO)
: "ldom2"
9-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Copying Domains - copyDomain Utility
copyDomain Notes
■
By not providing the -dest or pathToDestDomain, the utility no longer makes
the paths to the subdomains relative paths. Instead the -relativizePaths
argument should be used.
■
■
■
■
■
■
When used with -clone or -noSubDomains, copyDomain does not affect
workbook metadata or hierarchies.
Workbooks that are not included in the list used with the -copyWorkbooks
option are not included in the new domain.
Any existing workbooks in a domain copied with the -clone or -noSubDomains
options may not be able to be committed back to the new domain.
When used with -dimDictOnly, the -clone or -noSubDomains options
cannot be specified.
-dimDictOnly switch implies -copyWorkbooks none.
Use -xmlConfigFile to specify destination locations for individual
subdomains.
■
To get the usage text, use -?, -help, or -usage.
■
To get the version of this utility, use -version.
■
■
To set the logger verbosity level, use -loglevel with the following values: all,
profile, debug, audit, information, warning, error, or none.
To disable timestamp header, use -noheader.
copyDomain: Format of the XML Configuration File
The XML configuration file contains source and destination fields for the location of
the master domain and each of the sub-domains. Here is a basic example:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rpas>
<globaldomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain</srcPath>
<dstPath>C:\usr\Rpas\Domains\GlobalDomain2</dstPath>
<subdomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom0</srcPath>
<dstPath>C:\usr\Rpas\Domains\GlobalDomain2\ldom0</dstPath>
</subdomain>
<subdomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom1</srcPath>
<dstPath>C:\usr\Rpas\Domains\GlobalDomain2\ldom1</dstPath>
</subdomain>
<subdomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom2</srcPath>
<dstPath>C:\usr\Rpas\Domains\ldom2</dstPath>
</subdomain>
<subdomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom3</srcPath>
<dstPath>C:\usr\Rpas\Domains\ldom3</dstPath>
</subdomain>
</globaldomain>
</rpas>
Operational Utilities
9-5
Move a Domain - moveDomain Utility
The globaldomain tag should contain one srcPath tag, one stPath tag, and a
subdomain tag for each sub-domain. Each subdomain tag should contain one
srcPath tag and one dstpath tag. Each srcPath tag should be a path to either the
master or subdomain begins copied. Each matching dstPath tag should be a path to
where to copy that part of the domain.
The copyDomain utility will validate the configuration xml file first before any files are
copied. If any of the subdomain source paths do not match a sub-domain path of the
global domain being copied, a "can't find source sub-domain 'sub-domain' error will
be report. If the global domain being copied contains any sub-domain that doesn't
have a matching srcPath tag, a “sub-domain 'sub-domain' doesn't have a subdomain
xml tag" error will be reported. If the global domain srcPath tag doesn't contain the
path of a valid global domain then an "invalid source path 'srcPath' to global domain"
will be reported.
The destination paths in all cases will be validated when that part of the global domain
is being copied. Unless the switch -force is provided, the destination must not exist
and must be writable.
There are two options that control the number of sub-domains to be copied. These
options will still limit the number of sub-domains that are copied; however the
configuration file must still contain entries for all domains.
Move a Domain - moveDomain Utility
The moveDomain utility provides the flexibility to move elements of global domains
such as individual local domains and the master domain to pre-specified locations
based on a given XML configuration file. The utility automatically updates RPAS
metadata to reflect the modified directory paths in local and master domains. This
utility also ensures that the globalDomainConfig.xml file is updated as domains are
moved.
The XML configuration being used will be simple and designed to fit the required
task. It will contain fields for the locations of the source master domain and
destination master domain as well as source and destination fields for each of the subdomains that need to be moved.
moveDomain Usage
moveDomain -version
moveDomain -xmlConfigFile filename
moveDomain -d master -srcSubDomain src -dstSubDomain dst
Table 9–3 provides descriptions of the arguments used by the moveDomain utility.
Table 9–3
Arguments Used by the moveDomain Utility
Argument
Description
-xmlConfigFile
pathToXmlConfigFile.xml
This argument allows moveDomain to move a subdomain into
user-instructed specific locations based paths specified in an
XML file. This argument should not be used with the -d,
-srcSubDomain, and -dstSubDomain parameters.
See the moveDomain: Format of the XML Configuration File
section for the file format.
-d pathTomaster
This argument will allow moveDomain to move each subdomain based on the user-specified paths. Enter the path to the
master domain.
9-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Move a Domain - moveDomain Utility
Table 9–3 (Cont.) Arguments Used by the moveDomain Utility
Argument
Description
-srcSubDomain src
Path of the sub-domain to be moved.
-destSubDomain src
Path where the sub-domain is to be moved.
moveDomain: Format of the XML Configuration File
The XML configuration being used will be simple and designed to fit the required
task. It will contain fields for the locations of the source master domain and
destination master domain as well as source and destination fields for each of the subdomains that need to be moved. Here is a basic example of the XML configuration file.
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<rpas>
<globaldomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain</srcPath>
<dstPath>C:\usr\Rpas\Domains\GlobalDomain2</dstPath>
<subdomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom2</srcPath>
<dstPath>C:\usr\Rpas\Domains\ldom2</dstPath>
</subdomain>
<subdomain>
<srcPath>C:\usr\Rpas\Domains\GlobalDomain\ldom3</srcPath>
<dstPath>C:\usr\Rpas\Domains\ldom3</dstPath>
</subdomain>
</globaldomain>
</rpas>
The globaldomain tag must contain a srcPath tag and dstPath tag for the master
domain. The master domain will not be moved if srcPath and dstPath are the same. It
is essential to specify srcPath and dstPath for the master domain even if the master is
not intended to be moved; otherwise an error condition will be incurred.
The srcPath and dstPathtags for local domains are required ONLY if the local
domain is intended to be moved; otherwise, the lack of tags for a specific local domain
indicates that the local domain will not be relocated. If srcPath and dstPath are
identical for a given local domain, it will not be moved.
When global domain srcPath and dstPath are different; i.e. when moving global
domains, all local domains that reside under the global domain folder and are not
included in the XML file, will be moved to the destination global domain folder. Other
local domains with a specified destination location will be moved according to the
configuration.
Assumptions and Requirements
The following rules apply to the XML configuration settings:
■
All source and destination paths must be absolute.
■
All source paths must correspond to existing directories.
■
All destination paths must be valid, in the sense that:
■
The parent of the destination directory must exist
■
The parent directory must be writable by the user.
■
The destination directory itself must not exist.
■
The source and destination master domain paths are required.
Operational Utilities
9-7
Setting Miscellaneous Domain Properties - domainprop Utility
■
■
■
The source and destination sub domain paths are required only for the domains
that need to be moved.
The sub domains that need to be moved can be specified or those sub domains
that will remain under the master domain can be left out. If a sub domain is not
specified, it will be moved along with the master domain.
If the xmlConfigFile contents do not abide by the above mentioned rules, the
utility does not clear the validation phase and terminates with the appropriate
error message.
Minimum Space Requirement
Minimum space requirement for moving a global domain is the size of (just) master
domain plus the size of the largest local domain.
Setting Miscellaneous Domain Properties - domainprop Utility
Use the domainprop utility to manipulate the properties of a domain. Specify
password properties, lock user accounts, and determine whether or not a daemon is
currently managing a domain. The domainprop utility can be run on a global domain
master to set values in all subdomains.
domainprop Usage
domainprop -d pathToDomain {-property propertyname=value}
Table 9–4 provides descriptions of the arguments used by the domainprop utility.
Table 9–4
Arguments Used by the domainprop Utility
Argument
Description
-d pathToDomain
Specifies the domain path.
-property
propertyname=value
Used to specify the property to be changed.
-reportSubDomains
Use this option to show property values for subdomains (should
all match).
See the table of available properties below that can be set with
this utility. To view the current property setting, use the property
command with no value.
Available Properties
Table 9–5
Available Properties for the domainprop Utility
Domain Property
Name
Type
Description
disable_commit_asap
Boolean
If this property is set to TRUE, the ability to use
"Commit ASAP" in the File menu of the RPAS Client is
disabled. Furthermore, the "Commit ASAP" radio
button on the workbook close dialog is disabled.
By default, this property is set to FALSE.
disable_commit_later
Boolean
If this property is set to TRUE, the ability to use
"Commit Later" in the File menu of the RPAS Client is
disabled. Furthermore, the "Commit Later" radio
button on the workbook close dialog is disabled.
By default, this property is set to FALSE.
9-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Setting Miscellaneous Domain Properties - domainprop Utility
Table 9–5 (Cont.) Available Properties for the domainprop Utility
Domain Property
Name
Type
Description
domain_name
String
If this property is set, the domain name is displayed on
the "About" page of the RPAS Client (menu Help >
About).
insert_measure_disabl Boolean
ed
If this property is set to TRUE, the "insert measure…"
item under the Edit menu is disabled.
By default, this property is set to FALSE.
help_path
String
This property defines the path to the help files. It is set
when using custom help files for the RPAS Client
instead of the default help files that are provided with
the RPAS Client installation. These files need to be in
"WebHelp" format. This path would normally be a path
to a network folder where the common help files are
located. The folder must have a file named "Start.htm".
This file is the starting point for the custom help.
The default RPAS help has several pages for context
sensitive help. Help searches for these folders in the
preset relative location from the root folder of
WebHelp. If an implementation uses custom help, it
must locate the context help files in the expected
default locations relative to that folder. Otherwise,
context sensitive help will not be available and an error
will be raised every time the user tries to invoke
context sensitive help for a particular function.
If this property is not set, the path specified in the
foundation.ini file of the Client machine is used. If a
path is not specified in that file, help looks in the
default location in the RPAS Client installation for help
files. If the default files have been removed, help is not
available.
For the location of the foundation.ini file, see the
Translation Administration section.
meas_fillclr_preceden
ce
Boolean
By default, when deciding which color to fill a
particular cell with, RPAS grid uses the following order
or formatting settings: Read-only, Measure,
Hierarchical, and then Read/Write. That is, if the cell is
in a read-only state, it will use the read-only formatting
setting. However, if that is not the case, the grid will
check if there is any Measure level formatting. Failing
to find it will fall through to checking for the
hierarchical setting and then the read-write setting.
However, some customers want RPAS to follow a
different priority order for fill color formatting decision
making. They want it to try Measure, then Read-only,
then Hierarchical, and finally Read/Write. This change
from default can be made by setting this domain
property to TRUE. To reset behavior, this domain
property can be reset to FALSE.
measure_locking_disa Boolean
bled
If this property is set to FALSE, the user can lock a
measure on a work sheet. By default, this property is
set to FALSE. To disable measure locking, set this
property to TRUE.
Operational Utilities
9-9
Calculation Engine - mace Utility
Table 9–5 (Cont.) Available Properties for the domainprop Utility
Domain Property
Name
Type
ovr_def_admin_privil Boolean
eges
Description
Using the Security Administration workbook,
administrators can set workbook template access for
every user in the system. Non-administrative users
cannot access the workbook templates to which they
have not explicitly been given access. However, if a
user is an administrator, by default they can see all the
workbooks in the system.
Some retailers want to prevent this from happening.
Reasons for this include reducing clutter and having
different kind of administrators that manage different
administrative tasks in their RPAS systems.
Ability to control template access for administrators
from the Security Administration workbook is made
possible by setting this domain property to TRUE. By
default, this property is FALSE.
Calculation Engine - mace Utility
The mace utility (Multi-dimensional Array Calculation Engine) allows the
administrator to evaluate rule groups or expressions in order to manipulate measures.
mace supports the use of the RPAS calculation engine in batch.
The mace utility is most commonly used to run a rule group or an expression, but can
also be used to:
■
create rules and rule groups
■
add rules to rule groups
■
add expressions to rules
■
delete rules not contained in a rule group
■
remove any or all rule groups
■
validate expressions
■
print a list of rules or rule groups
Parallelization: The mace utility can execute in parallel under the following
circumstances:
1.
The utility must be invoked on a master domain.
2.
Parallelization is only applicable to single-expression evaluation (-run -expression
argument). Parallelization does not apply to rule group evaluation.
3.
The evaluated expression cannot be a SpecialExpression.
4.
All of the measures appearing on the left hand side of the expression must be nonHBI; that is, the base intersection of the measures must be below the partition
level.
The mace utility creates multiple child processes based on the -processes argument
and each child mace process evaluates the expression in one local domain. This
functionality enables mace to achieve higher levels of CPU utilization using
parallelization on systems with multiple CPUs. It also simplifies the user script when
the same expression must be evaluated in all local domains.
9-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Calculation Engine - mace Utility
Centralization: When running mace on a master domain, the following command line
options apply to the master as well as all local domains. For example, running mace d domain -newRule … creates a new rule in the master and all local domains.
■
-newRule: create a new rule in the domain
■
-delRule: delete an existing rule from the domain
■
-addRule: add a new rule to a specific rule group
■
-removeRule: remove an existing rule from a specific rule group
■
-newGroup: create a new rule group in the domain
■
-remove Group: remove an existing rule group from the domain
■
-addExpression: add an expression to a specific rule
■
-purgeRules: remove all rules not contained in any rule group from the domain
■
-removeAllRuleData: remove all rule and rule group data from the domain
The behavior and usage of the following commands is unchanged:
■
-find: search all expressions for the specific measure and print all rules / rule
groups that use it
■
-check: validate the specific expression
■
-resolve: order but do not evaluate expressions within the rule group
■
-transit: rule calc engine by transitting over a list of rule groups
■
-print: print all specific rules and groups
■
-validate: validate rule groups
mace Usage
mace -version
mace -d domainPath
mace -d domainPath
numProcesses}
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
numProcesses}
mace -d domainPath
mace -d domainPath
numProcesses}
mace -d domainPath
mace -d domainPath
mace -d domainPath
debugRuleEngine}
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
mace -d domainPath
-find string
-newRule {-ruleName ruleName} {-label ruleLabel}{-processes
-delRule ruleName (-processes numProcesses}
-addRule
groupName:ruleName {-processes numProcesses}
-removeRule groupName:ruleName {-processes numProcesses}
-newGroup
groupName {-label groupLabel}{-processes
-removeGroup groupName {-processes numProcesses}
-addExpression ruleName -expression exprString{-processes
-check -expression exprString
-run -group groupName
{-debugRuleEngine}
-run -expression expString {-processes numProcesses}{-resolve groupName -measures measList {-debugRuleEngine}
-transit workbookName -group groupList {-debugRuleEngine}
-print -rule ruleList
-print -group groupList
-print -allGroups
-purgeRules {-processes numProcesses}
-removeAllRuleData {-processes numProcesses}
-validate calc
-ruleGroup groupName
-validate general -ruleGroup groupName
-validate refresh -ruleGroup groupName -calcRuleGroup calc
Operational Utilities 9-11
Calculation Engine - mace Utility
Table 9–6 provides descriptions of the arguments used by the mace utility.
Table 9–6
Arguments Used by the mace Utility
Argument
Description
-d domainPath
Specifies the domain in which to load the measure.
-find string
Use this argument to search all expressions for the specified
string, printing all the rules and rule groups that have these
expressions.
-newRule {-ruleName
ruleName}
Use this argument to create a new empty rule. If desired, use the
-ruleName argument to specify a name for the rule.
-label {ruleLabel |
groupLabel
Use this argument to specify the label of the rule with the newRule argument or label of the group with the -newGroup
argument.
-processes numProcesses
Use this argument to specify the number of child processes to be
run in parallel.
-delRule ruleName
Use this argument to remove the specified rule.
-addRule
groupName:ruleName
Use this argument to add the specified rule to the group
specified by groupName.
-removeRule
groupName:ruleName
Use this argument to remove the specified ruleName from the
group specified by groupName.
-newGroup groupName
Use this argument to create a new rule group with the specified
name.
-removeGroup groupName
Use this argument to remove the specified group and nonshared rules in it.
-addExpression ruleName Use this argument to add an expression to the specified rule. expression should be used with this argument.
-check
Use this argument to validate the specified expression. expression should be used with this argument.
-run
Use this argument to evaluate the specified expression or rule
group. -expression should be used with this argument.
-resolve groupName
Use this argument to order (does not evaluate) expressions
within rule group.
Requires a comma-separated list of edited measures.
-transit workbookName
Use this argument to run a calc engine by transitioning over a
list of rule groups.
Requires the name of an existing workbook and a commaseparated list of rule-group names.
-print {ruleList |
groupList | true}
Use this argument to print all the specified rules and rule
groups.
The ruleList is a comma-separated list of rule names.
The groupList is a comma-separated list of group names.
If "true" is supplied for either ruleList or groupList, all rules or
rule groups are printed.
-purgeRules
Use this argument to remove all rules not contained in any rule
groups.
-removeAllRuleData
Use this argument to remove all rule groups and all rules.
9-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Managing the Workbook Batch Queue - wbbatch Utility
Table 9–6 (Cont.) Arguments Used by the mace Utility
Argument
Description
-validate {calc | general | Use this argument to validate rule groups.
refresh}
Use calc to validate a calc rule group.
To validate a refresh rule group, use the refresh parameter along
with -calcRuleGroup to specify the corresponding calc rule
group.
For all other types of rule groups, use general.
-debugRuleEngine
Use this argument to generate a file "mace.log" in the working
directory for logging RuleEngine specific debug information.
-expression exprString
Use the argument to specify the expression.
This argument is used in conjunction with the
-addExpression, -check, and -run arguments.
-group groupName
Use this argument to specify the rule group to evaluate using the
-run argument.
-measures measureList
Use this argument to specify the measures to resolve.
-group groupList
Use this argument to specify a list of group names, separated by
commas.
Use this argument in conjunction with the
-transit and -print arguments.
-rule ruleList
Use this argument to specify a list of rule names, separated by
commas.
Use this argument in conjunction with the -print argument.
-allGroups
Use this argument in conjunction with the -print argument to
print all rule groups.
-addGroup
Use this argument to create a new rule group with the specified
name
Managing the Workbook Batch Queue - wbbatch Utility
The wbbatch utility is used to manage workbook batch categories and workbooks in
the workbook batch queue. The workbook batch queue is updated by using the
standard RPAS wizard Auto Workbook Build or using various options of the wbbatch
utility.
The most common use of this utility is to build workbooks that have been scheduled to
be automatically built using the Auto Workbook Build wizard in the RPAS clients. It is
also used to add, update, and delete batch categories, update assignments of
workbook build entries to workbook batch categories, provide workbook batch
categories when adding workbooks to the refresh queue, and update the assignments
to workbooks already in the refresh queue.
When a user defers a workbook commit (using Commit Later), that workbook commit
process is added to the Commit Later queue which is committed using this utility. An
administrator can also add a workbook to the commit later queue with this utility.
RPAS provides the ability to update workbook data with domain data without having
to rebuild the workbook; this refreshing process is completed using a workbook's
default refresh rule group. Workbooks are added to the queue to be refreshed and
refreshed using this utility.
Operational Utilities 9-13
Managing the Workbook Batch Queue - wbbatch Utility
The build and refresh operations can be executed in multiple, parallel processes using
the -processes argument.
wbbatch Usage
wbbatch -version
wbbatch -d pathToDomain -build queueIndex
wbbatch -d pathToDomain -refresh workbookName
wbbatch -d pathToDomain -commit workbookName
wbbatch -d pathToDomain -scheduleRefresh workbookName [-category categoryName]
wbbatch -d pathToDomain -unscheduleRefresh workbookName
wbbatch -d pathToDomain -scheduleCommit workbookName
wbbatch -d pathToDomain -unscheduleCommit workbookName
wbbatch -d pathToDomain -startQueue [all|build|refresh|commit] [-processes max]
[-categories catName1,catName2]
wbbatch -d pathToDomain -printQueue [all|build|refresh|commit]
wbbatch -d pathToDomain -listCategories
wbbatch -d pathToDomain -addCategories catName1:Label1,catName2:Label2
wbbatch -d pathToDomain -deleteCategories catName1,catName2
wbbatch -d pathToDomain -changeCategoryLabels catName1:NewLabel1,
catName2:NewLabel2
wbbatch -d pathToDomain -queue build -updateCategories queueIndex1:newCatName1,
queueIndex2:newCatName2
wbbatch -d pathToDomain -queue refresh -updateCategories
workbookName1:newCatName1, workbookName2:newCatName2
Table 9–7 describes the arguments used by the wbbatch utility.
Table 9–7
Arguments Used by the wbbatch Utility
Argument
Description
-d pathToDomain
Specifies the domain containing the workbooks.
-build queueIndex
Runs workbook build for provided queueIndex.
-refresh workbookName
Refreshes workbooks scheduled to be refreshed using this utility.
To refresh a single workbook in the queue, specify the name of
the workbook.
If no name is provided, all workbooks scheduled to be refreshed
will be completed.
-commit workbookName
Commits workbooks with deferred commits.
To commit a single workbook in the commit later queue, specify
the name of a workbook.
If no name is provided, all workbooks in the commit later queue
will be committed.
-processes count
Used with either -build or -refresh to build or refresh workbooks
in the auto-workbook queue in parallel using the specified
number of parallel processes.
-scheduleRefresh
Schedules a workbook to be refreshed later by adding it to the
workbook refresh batch queue. If the -category option is
specified, the scheduled workbook will be in that category.
Otherwise, it will be in the default category.
-unscheduleRefresh
workbookName
Removes a workbook from the workbook refresh batch queue.
-scheduleCommit
workbookName
Schedules a workbook to be committed later by adding it to the
workbook commit batch queue.
9-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Managing the Workbook Batch Queue - wbbatch Utility
Table 9–7 (Cont.) Arguments Used by the wbbatch Utility
Argument
Description
-unscheduleCommit
workbookName
Removes a workbook from the workbook commit batch queue.
-startQueue
Runs all workbooks in provided queue. The queue options are
build, refresh, and commit. If the -category option is used and
one or more categories are specified, only the workbooks in
those categories are built or refreshed. Categories do not apply
to committing.
-printQueue
Prints the contents of the queue argument. The queue indexes
for auto workbooks in the build queue are shown when printing
the build queue. If “all” is specified, all three queues (build,
refresh, and commit) are displayed.
-listCategories
Lists both the name and label for all categories.
-addCategories
Name1:Label1, Name2:Label2,
Name3:Label3
Adds a new category by providing a name and label, separated
by a colon. Multiple categories can be specified on the same
command line if separated by a comma.
If the users use a different language other than the one typed in
the command line, the administrator should use the Workbook
Batch Category Management wizard to create new categories.
-deleteCategories catName1,
catName2
Deletes a category by specifying the name of that category.
Multiple categories can be deleted if separated by a comma.
-changeCategoryLabels
Name1:NewLabel1,
Name2:NewLabel2
Changes the label of an existing category by specifying the
category name and providing a new category label.
-updateCategories
queueIndex1:newCatName1,
queueIndex2:newCatName2
Use this to update the category for an entry in the build queue or
to change the workbook category of an existing entry in the
refresh queue. Multiple category assignment for workbook auto
build queue entries and refresh entries can be updated.
Or:
-updateCategories
wbName1:newCatName1,
wbName2:newCatName2
If the users use a different language other than the one typed in
the command line, the administrator should use the Workbook
Batch Category Management wizard to change category labels.
If using the -build option, list the queue index. If using the
-refresh option, list the workbook name.
Build example:
wbbatch -d pathToDomain -queue build -updateCategories
queueIndex1:newCatName1, queueIndex2:newCatName2
Refresh example:
wbbatch -d pathToDomain -queue refresh -updateCategories
workbookName1:newCatName1, workbookName2:newCatName2
Operational Utilities 9-15
Workbook Manager - wbmgr Utility
Workbook Manager - wbmgr Utility
Use the Workbook Manager utility to inspect or remove the existing workbooks. It is
recommended that administrators use this utility to remove workbooks rather than
doing so manually.
wbmgr Usage
wbmgr
wbmgr
wbmgr
wbmgr
wbmgr
wbmgr
wbmgr
-version
-d pathToDomain
-d pathToDomain
-d pathToDomain
-d pathToDomain
-d pathToDomain
-d pathToDomain
-list -all
-list -user userName
-print -wbList wb1,wb2,...
-remove -all
-remove -user userName
-remove -user userName -wbList wb1,wb2,...
Table 9–8 provides descriptions of the arguments used by the wbmgr utility.
Table 9–8
Arguments Used by the wbmgr Utility
Argument
Description
-d pathToDomain
Specifies the domain that contains the workbooks.
-list -all
Lists all workbooks in the domain.
-list -user userName
Lists all workbooks belonging to the user.
-print -wbList wb1,wb2,...
Prints detailed information about workbooks in the list.
-remove -all
Removes all workbooks from the domain.
-remove -user userName
Removes all workbooks from the domain belonging to the
specified user.
-remove -user userName wbList wb1,wb2
Removes all the workbooks in the specified list for the specified
user.
9-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Register Measure - regmeasure Utility
Register Measure - regmeasure Utility
The regmeasure utility is used for batch measure registration. The following
functionality is included:
■
■
■
Register a new measure in the user-specified domain with the user-specified
measure properties. If the domain specified by the user is a global domain, this
measure will be registered in the master domain and all its local domains. The user
must provide a minimum set of measure properties, type and base intersection.
Other measure properties are optional, such as default aggregation and spreading
method. If the user omits an optional measure property, the measure will be
registered with default value of that property.
Unregister an existing measure identified by its name, from the user-specified
domain. If the specified domain is a global domain, this measure will be removed
from the master domain and all local domains. Unregistering a measure from a
domain will cause the measure definition and all the related measure data arrays
and supporting arrays to be removed from the domain.
Modify measure properties of an existing measure. Not all measure values can be
modified, such as type, base intersection, NV value, and database name. These
properties cannot be changed once the measure is registered. Measure properties
such as default aggregation method, default spread method, base state, agg state,
and so on can be modified after the measure is registered.
regmeasure Usage
regmeasure -version
regmeasure -d pathToDomain -add measureName -type typeName(-baseint
baseIntersection|-scalar) {-label labelString} {-db dataDbPath}{-navalue naValue}
{-defagg aggType} {-defspread spreadType}{-allowedaggs "aggType1 aggType2"}{refreshable (true|false)} {-insertable (true|false)}{-basestate (read|write)} {aggstate (read|write)}{-stageonly (true|false)} {-filename fileName}{-loadint
loadIntersectionString} {-clearint clearIntersectionString}{-loadstokeep
loadsToKeep} {-start fieldStart} {-width fieldWidth}{-loadagg loadAgg} {-range
range} {-purgeage purgeAge} {-viewtype viewType}{-syncwith syncWith} {-description
descriptionString} {-picklist}{-materialized (persistent|display)}{-lowerbound
measurename} {-upperbound measurename}{-attr attrName -attrpos attrPosName} {scriptname scriptName}{-specialval
action:specval:behavior,action:specval:behavior,...} {-fnhbi}{-hybridaggspec
hiername:aggop,hiername:aggop,...}{-periodstartvalue (true|false)}
regmeasure -d pathToDomain -modify measureName {-label labelString}{-defagg
aggType} {-defspread spreadType} {-allowedaggs "aggType1 aggType2..."}{refreshable (true|false)} {-insertable (true|false)}{-basestate (read|write)} {aggstate (read|write)}{-stageonly (true|false)} {-filename fileName}{-clearint
clearIntersectionString}{-loadstokeep loadsToKeep} {-start fieldStart} {-width
fieldWidth}{-loadagg loadAgg} {-range rangeString} {-purgeage purgeAge|clearPurgeAge}{-viewtype viewType} {-syncwith syncWith} {-description
descriptionString}{-picklist|-nopicklist} {-materialized (persistent|display)}{lowerbound measureName} {-upperbound measureName}{-attr attrName -attrpos
attrPosName} {-scriptname scriptName}{-specialval
action:specval:behavior,action:specval:behavior,...}{-hybridaggspec
hiername:aggOp,hiername:aggOp,...}{-periodstartvalue (true|false)}
regmeasure -d pathToDomain -remove measureName
Table 9–9 provides descriptions of the arguments used by the regmeasure utility.
Operational Utilities 9-17
Register Measure - regmeasure Utility
Table 9–9
Arguments Used by the regmeasure Utility
Argument
Description
-d pathToDomain
Specifies the path to the domain. A valid domain path must be
specified.
-add measureName
Adds a measure with the specified name. Set the values for the
measure by using the required arguments and any of the
optional arguments.
Measure names can be up to 30 characters long.
-type typeName
Specifies the measure data type. It can be set to int, real, string,
date, or boolean.
Required with the -add option. Not available with the -modify
option.
-baseint baseIntersection|scalar
Specifies the base intersection of the measure. Non-scalar
measures must use the -baseint option. Scalar measures must
use the -scalar option.
Required with the -add option. Not available with the -modify
option.
-label labelString
Specifies the measure label. If not specified, it defaults to the
measure name specified for the -add option.
-db dataDbPath
Specifies the database path for the measure's data arrays. A valid
database path name must be specified. If not specified, the
measure will be registered without a database. As a result, the
measure will not be able to store any data in the domain.
However, if the measure is not a Display only type, it will still be
assigned a database in the workbook.
Not available with the -modify option.
-navalue naValue
Specifies the na value for the measure's base level data array.
The navalue must be the same type as the measure. For date, the
navalue must be formatted as 'YYYYmmddHHMMSSsss'. If not
specified, it defaults to the type's default value: 0 for numeric
type, false for boolean type, an empty string for string type, and
0001/01/01 for date type.
Not available with the -modify option.
-defagg aggType
Specifies the default aggregation method for the measure. It
must be an aggregation name valid for the type of measure. For
a list of valid aggregation type names, see the RPAS
Configuration Tools User Guide. If not specified, it defaults to the
measure type's default aggregation method: Total for int and
real, Ambig for string and date, and OR for boolean.
-defspread spreadType
Specifies the default spread method for the measure. It must be a
spread method valid for the type of measure. For a list of valid
spread methods, see the RPAS Configuration Tools User Guide. If
not specified, it defaults to the measure type's default spread
method: Ratio for int and real, and Replicate for string, date, and
boolean.
9-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Register Measure - regmeasure Utility
Table 9–9 (Cont.) Arguments Used by the regmeasure Utility
Argument
Description
-allowedaggs "aggType1
aggType2..."
Specifies a list of aggregation methods that are allowed for this
measure. The aggregation methods must be valid for the type of
measure. If not specified, it defaults to the default allowed aggs
for the type of measure.
For numeric (int or real type) measures: total, total_pop, first,
first_pop, last, last_pop, min, min_pop, max, max_pop, average,
average_pop, popcount, nobcount, ambig, ambig_pop, none,
period_start_total, period_end_total, period_start_average,
period_end_average, median, median_pop, recalc, hybrid.
For string type measures: ambig, ambig_pop, none, popcount,
nobcount, first, first_pop, last, last_pop, recalc, hybrid.
For date type measure: ambig, ambig_pop, pop_count,
nob_count, first, first_pop, last, last_pop, min, min_pop, max,
max_pop, non, recalc, hybrid.
For boolean measure: boolean_and, boolean_or, pop_count,
nob_count, ambig, ambig_pop, none, first, first_pop, last,
last_pop, recalc, hybrid.
-refreshable (true|false)
Note: This option is no longer supported but is kept for
compatibility.
-insertable (true|false)
Specifies whether the measure can be dynamically inserted into
the workbook. If not specified, it defaults to true.
-basestate (read|write)
Specifies the workbook access right for the base array of the
measure. If not specified, it defaults to read. The access rights of
this measure will be further restricted by the RPAS security
features. As a result, write access specified by this option does
not guarantee write access of this measure in a specific
workbook.
-aggstate (read|write)
Specifies the workbook access right for the aggregated level of
the measure. If not specified, it defaults to read. The access rights
of this measure will be further restricted by the RPAS security
features. As a result, write access specified by this option does
not guarantee write access of this measure in a specific
workbook.
-stageonly (true|false)
Specifies whether the measure is a stage only measure. If not
specified, it defaults to false. Measure data loaded by
loadmeasure for stage only measures will not be automatically
applied to the measure's base data array. User intervention is
usually required to manually approve the loaded measure data
and apply the approved loads to the measure's base data array.
-filename fileName
Specifies the file name of this measure's loading file. It should
not inlcude any extensions. If not specified, it defaults to the
measure name in lower case.
-loadint
loadIntersectionString
Specifies the intersection to load data for this measure. It must
be a valid intersection string which is either the same or lower
than the base intersection of this measure. If loadint is lower
than the base intersection of the measure, the aggregation
method specified by the -loadagg option will be used to
aggregate the loaded data to the base array of the measure.
Not available with the -modify option.
-clearint
clearIntersectionString
Specifies the clear intersection for the clear load of this measure.
For more information on the various loading methods including
clear load, refer to the Loading Measure Data - loadmeasure
section in this guide.
Operational Utilities 9-19
Register Measure - regmeasure Utility
Table 9–9 (Cont.) Arguments Used by the regmeasure Utility
Argument
Description
-loadstokeep loadsToKeep
Specifies the number of temporary measure load arrays to be
kept in the staging database. If not specified, it defaults to 1.
-start fieldStart
Specifies the starting column of this measure's data in the
measure loading file. If not specified, it is calculated based on
the loadint of the measure.
-width fieldWidth
Specifies the number of characters this measure's data occupies
in the measure loading file. If not specified, it defaults to the
default width of the measure type: 8 for integer, real, and date,
24 for string, and 1 for boolean.
-loadagg loadAgg
Specifies the aggregation method used to aggregate the
temporary load array to the measure's base array if the
measure's loadint is lower than its baseint. If not specified, it
defaults to the measure type's default aggregation method: Total
for int and real, Ambig for string and date, and OR for Boolean.
-range rangeString
Specifies the valid range for the measure. The value of the range
parameter depends on the measure type.
For int or real types, the format is min:max where min is the
lowest possible value of the measure and max is the highest
possible value of the measure.
For picklist measures, to give the allowed options, the format of
the string argument is 'a(Label A),b(Label B),c,d', where a, b, c,
and d are allowed measure values and Label A and Label B are
optional labels for the values. In addition, the list of allowed
options can be changed dynamically with the cell the user is
clicking in. For this functionality, the measure's range is specified
as 'measurerange=measurename' where measure name is the
name of the measure that contains strings in the above format of
value/label pairs.
For date types, the range must be in the format
MMddyyyyhhmmss:MMddyyyyhhmmss, where the first string is
the starting date and time of the range and the second date is the
ending date and time of the range. If you omit the time portion
of the string (hhmmss), the default time is used. The default
lower bound is 000000 (12:00:00AM), which is used for the
beginning of the day. The default upper bound is 235959
(11:59:59PM), which is used for the end of the day.
If the range begins with a negative number (which may confuse
the command-line argument parser), enclose the entire range
string in square brackets, such as -range [-10:10].
-purgeage (purgeAge)
Specifies the number of days (or whatever the base dimension of
the calendar hierarchy is) of measure data that should be kept in
the measure's base data array after measure load. This is used to
keep the measure's data size small. If not specified, it defaults to
-1 in which case the measure data will never be purged.
When using the -modify option, -purgeage or -clearPurgeAge
can be specified.
-clearPurgeAge
Resets the number of days (or whatever the base dimension of
the calendar hierarchy is) of measure data that should be kept in
the measure's base data array after measure load to -1. This
means that the measure data will never be purged.
clearPurgeAge is only available with the -modify option. When
using the -modify option, -purgeage or -clearPurgeAge can be
specified.
9-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Register Measure - regmeasure Utility
Table 9–9 (Cont.) Arguments Used by the regmeasure Utility
Argument
Description
-viewtype viewtype
Specifies the view type of this measure on the RPAS Client. The
valid values are: 0 for none, 1 for view_only, 2 for sync_first_lag,
3 for sync_lead_last, 4 for sync_first, and 5 for sync_last. If not
specified, it defaults to none. If the view type starts with "sync",
the measure is called a 'Virtual Measure'.
A measure of sync_first_lag type must have two sync measure
names specified by the -syncwith option. The first syncwith
measure name is a 'Period Start Value' type of measure, like
opening stock. Measure data at the beginning period of the
calendar is synchronized with this period start value kind of
measure. The subsequent measure data is synchronized with the
other measure data but lagged one period.
A measure of sync_lead_last type must have two sync measure
names specified by the -syncwith option. The first measure is a
'Period End Value' type of measure. Measure data at the last
period of the calendar is synchronized with this period end
value. Measure data of previous periods is synchronized with
the other measure lead one period data.
A measure of sync_first type must have one measure name
specified by the -syncwith option. The data of the beginning
period is synchronized with this syncwith measure.
A measure of sync_last type must have one measure name
specified by the -syncwith option. The data of the ending period
is synchronized with this syncwith measure.
Measures of view_only type are non-persistent. View only
measures can only be used in workbooks. Their measure data is
calculated during the Fetch process using a calc expression
usually specified in the workbook's calc rule group.
-syncwith syncWith
Specifies the measures that the measure must be synchronized
with. This option must be specified if the measure is not a virtual
measure.
For sync_first_lag and sync_lead_last measures, the syncwith
option must have two measure names separated by a comma.
The first measure is used to synchronize the data at the first or
the last calendar period. The second measure is used to
synchronize data at other periods.
For sync_first and sync_last measures, the syncwith option must
be specified with a single measure name that will be used to
synchronize the first or last calendar period.
-description
descriptionString
Specifies the description of the measure.
-picklist|-nopicklist
Specifies whether the measure is displayed as a picklist in the
Client. The actual value of the picklist is specified by the -range
option of the measure.
-nopicklist is only available with the -modify option. It means
the measure should not be displayed as a picklist measure in the
RPAS Client.
Operational Utilities 9-21
Register Measure - regmeasure Utility
Table 9–9 (Cont.) Arguments Used by the regmeasure Utility
Argument
Description
-materialized
(persistent|display)
Specifies whether the measure is persistent or display only on
the RPAS Server side.
Persistent measures must have a valid database and arrays to
store the measure data.
Display only measures do not have permanent data arrays
associated with it. The data for a Display only measure must be
calculated on the fly. As a result, Display only measures can not
be used on the RHS of any expression. Display Only measures
can still be used on the LHS of a calc expression used in a
workbook, in which case a temporary array will be created in
the workbook to hold the temporary data for the Display
measure.
-lowerbound measureName Specifies a measure name that defines the lower bound for each
cell of the measure. The difference between the -lowerbound and
-range options is that the -range option specifies a single scalar
as the lower bound for all cells of the measure, but the lower
bound value specified by the -lowerbound option can be
different from cell to cell.
-upperbound measureName Specifies a measure name that defines the upper bound for each
cell of the measure. The difference between the -upperbound
and -range options is that the -range option specifies a single
scalar as the upper bound for all cells of the measure, but the
upper bound value specified by the -upperbound option can be
different cell to cell.
-attr attrName
Specifies the measure attribute name. If not specified, it defaults
to no attribute is assigned to the measure.
Note: If this option is specified, the -attrpos option must also be
specified.
-attrpos attrPosName
Specifies the measure attribute position name. Combined with
the -attr option, the measure attribute provides a way to group
measures together based on measure attributes.
Note: If this option is specified, the -attr option must also be
specified.
-scriptname scriptname
Specifies a shell script that must be executed as part of a specific
event. Currently, the only script that is handled is to give the
option of selecting a hierarchy position name as the content of a
string measure. In other words, when a user clicks in a cell, the
user is presented with a hierarchy dimension single-tree pop-up.
The format for this is 'SingleSelect(HIER="<HIER>",
DIM="<DIM>") where <HIER> and <DIM> should be replaced
with the actual names of the hierarchy and dimension for which
the single-tree pop-up should be created.
-specialval
Specifies a list of measure special values in the form of
"Action:SpecialValue:Behavior,…". The special values are stored
in the domain's meta data database.
action:specval:behavior,
action:specval:behavior,...
For Action, the only action supported is: "DISPLAY".
The only SpecialValue supported is "NAVAL".
For Behavior, "NULL" means translate any na cell to a blank cell
for display. "CELLVALUE" means no translation, just display the
navalue as a regular value.
9-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Register Token Measure - regTokenMeasure Utility
Table 9–9 (Cont.) Arguments Used by the regmeasure Utility
Argument
Description
-fnhbi
Specifies that this measure is a "Forced non=HBI" measure,
which means that although the base intersection of this measure
is above the partition dimension, the measure data must still be
stored in each local domain.
Not available with the -modify option.
-hybridaggspec
Specifies the aggregation method to be used for each hierarchy
hiername:aggOp,hiername:a in the base intersection. This option is only valid when the
ggOp,...
default aggregation method for the measure is hybrid.
-periodstatevalue
(true|false)
Specifies that this measure stores a "Period Start" type of data,
like beginning inventory. PeriodStart measures usually use
Period Start Total or Period Start Average for the default
aggregation method. It also has different behavior in elapsed
lock. At the aggregated calendar level, if the starting period is
elapse locked, then the whole aggregated period is locked.
-modify measureName
Modifies the measure with the specified name. Set the updated
values for the measure by using any of the optional arguments.
-remove measureName
Removes the measure with the specified name.
Register Token Measure - regTokenMeasure Utility
The regTokenMeasure utility is used to register, list, and remove RPAS Token
Measures.
RPAS Token Measure provides placeholder functionality for measure names in RPAS
expressions. An RPAS Token Measure is a special RPAS measure.
An RPAS Token Measure is always registered as a scalar measure of string type, with
the measure property called tokenmeas set to true. Its measure data holds a valid
value measure name as a single string. The data arrays for all token measures are
stored in one database called token under the data directory in the RPAS domain.
Token measure can be used in RPAS expressions by prefixing @ in front of the token
measure name, either on the LHS or RHS of the expression. Before evaluation,
@TokenMeasName in the expression is replaced with the value measure name that is
associated with the token measure. As a result, the expression will be evaluated
against the value measure. A token measure name cannot be used in expression
without the prefixing @.
In the following example, TM1 is a token measure registered with the value measure
name VM1.
The following expression:
@TM1 = a + b
Will be evaluated as:
VM1 = a + b
The following expression is not valid, because TM1 is used without prefixing it with @:
TM1 = "sth"
If evaluated using mace, mace will throw a ParserException with the message that the
token measure "TM1" is used without prefixing @. This functionality prevents the
modification of the token measure's data, which is actually the value measure's
measure name.
Operational Utilities 9-23
Batch Plug-In Tasks: execPluginTask.sh
regTokenMeasure Usage
regTokenMeasure
regTokenMeasure
regTokenMeasure
regTokenMeasure
-version
-d pathToDomain -add tokenMeasure=valueMeasure {-fnhbi}
-d pathToDomain -list
-d pathToDomain -remove tokenMeasure=valueMeasure
Table 9–10 provides descriptions of the arguments used by the regTokenMeasure
utility.
Table 9–10
Arguments Used by the regTokenMeasure Utility
Argument
Description
-d pathToDomain
Specifies the path to the domain. A valid domain path must be
specified.
-add
tokenMeasure=valueMeasure
Adds a token measure with the specified token measure name
and value measure that the token measure points to.
-fnhbi
If specified, the token measure will be registered as an fnhbi
measure in the global domain. Its data will be stored in each
local domain rather than the global domain, although by
definition the token measure should be always be HBI measure
since its scalar type.
-list
Prints all token measure names and the value measure names
associated with the token measure, which are registered in the
domain specified by the -d option.
-remove
Removes the token measure with the specified token measure
tokenMeasure=valueMeasure name and value measure. The token measure is unregistered
from the domain specified by -d option. Unregistering the token
measure has no side effect to the value measure that the token
measure is associated with.
Batch Plug-In Tasks: execPluginTask.sh
Many RPAS applications can be used to extend the functionality of the RPAS
Configuration Tools and the rpasInstall process. Theses extensions are provided by
plug-ins included as part of the solution. Most plug-in extensions execute either within
the RPAS Configuration Tools or within the rpasInstall process. However, some
applications may include plug-in extensions that can be executed from a command
prompt.
The execPluginTask.sh utility is the method by which these command line plug-in
tasks can be performed. When execPluginTask.sh is executed, it loads a configuration,
locates the desired plug-in extension, and executes that extension on the loaded
configuration. Then, depending on the task being executed, the configuration may or
may not be saved. Extensions that do not modify the configuration, for example, ones
that generate resources based on the contents of the configuration, do not require
saving the configuration at the conclusion of the automation.
Individual applications document the command line extensions they support, if any,
along with information on how those extensions may be used.
9-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Batch Plug-In Tasks: execPluginTask.sh
execPluginTask.sh usage
In addition to the standard arguments described below, it is possible to pass any
number of additional arguments to execPluginTask.sh. These additional arguments are
passed to the extension being executed to allow control over its operation. Details on
the arguments any given command line extension accept and their function are
located in the application-specific documentation of the extension.
execPluginTask.sh plug-inName:taskName pathToConfiguration {plug-inTaskArguments}
execPluginTask.sh -version
execPluginTask.sh -help
Table 9–11
Arguments Used by the execPluginTask.sh Utility
Argument
Description
plug-inName
The name of the plug-in containing the extension to be executed.
taskName
The name of the extension to be executed.
pathToConfiguration
The path to the configuration execPluginTask.sh should load to
execute the extension. As with the rpasInstall process, paths passed
as arguments should be absolute paths and not relative paths.
plug-inArguments
Additional arguments that are passed to the extension.
-version
Prints the version information for execPluginTask.sh.
-help
Prints the usage statement for execPluginTask.sh.
Operational Utilities 9-25
Batch Plug-In Tasks: execPluginTask.sh
9-26 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
10
Informational Utilities
10
There are numerous RPAS utilities that can be used for finding information about
many of the different components of a domain or domain data. The following utilities
are solely for retrieving information and to not make any changes to a domain or data
in a domain.
■
Retrieving Domain Information - domaininfo Utility
■
Checking the Validity of a Domain - checkDomain Utility
■
Determining RPAS Server Version - rpasversion Utility
■
List Contents of a Database - listDb Utility
■
Printing Data from Arrays - printArray Utility
■
Printing Data from Measures - printmeasure Utility
Retrieving Domain Information - domaininfo Utility
The domaininfo utility is used to provide miscellaneous details about a domain,
such as the type of domain (simple, master, or sub/local), and the upgrade/version
history of the domain.
domaininfo Usage
domaininfo -d pathToDomain [Command]
domaininfo -expectedversion
Domain path (-d) is required for all options except
-expectedversion.
Note:
The following table provides descriptions of the arguments used by the domaininfo
utility.
Table 10–1
Arguments Used by the domaininfo Utility
Argument
Description
-d
Path to the domain. Required for all options except expectedversion.
-domainversion
Display the RPAS version of the specified domain.
-expectedversion
Displays the expected RPAS version of the domain that the
utility expects to find.
Informational Utilities 10-1
Retrieving Domain Information - domaininfo Utility
Table 10–1 (Cont.) Arguments Used by the domaininfo Utility
Argument
Description
-type
Command to display the type of the domain. Possible values are
Simple, Global, and Sub.
A Simple domain is a traditional, non-partitioned (non-global)
domain.
A Global domain is the central/master domain of a global
domain environment.
A Sub domain is one local domain in a global domain
environment that can contain one or more partitions.
-apptag
Displays the application associated with domain.
-history
Displays the version history of the domain, specifically when the
domain was upgraded to new versions of RPAS (patches or
releases).
-listsubdomains
Displays a list of all the local domains in a global domain
environment, and indicates which positions at the partition level
are in each local domain. This argument is only valid when run
on a global domain.
-masterdomaininfo
Lists the master domain path and partition dims for
subdomains.
-all
Displays the domain version, expected domain version, domain
type, associated application, history, subdomains, and master
domain info (where applicable).
-domainsize
Displays the file size information for the domain.
-stringstats
Displays the number of strings of all given lengths that occur in
the domain. The output returns a list by string length, for
example:
0
1
2
3
...
-stringvalues
758
21
8
69
Displays how many occurrences of each unique string there are
in the domain. The output returns a list of each unique string,
for example:
785 ''
1 '#copied <> #pasted'
2 '%'
1 '%1 <= passwd <= %2'
2 '%1 Window'
...
-arraydensity
Displays array btree density.
-arrayschemas
Displays how many arrays in the domain are formatted for each
schema. The output returns a list like the following:
Count of Array Schemas for Domain ‘domain’
Array schema 10: 371
Unknown schema: )
-version
Displays the version of this utility.
-subdomain dim,pos
Indicates to which local domain the specified position belongs.
The position can be at or below the partition level.
-registrypaths
Displays all array paths to dimRegistry.
10-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Checking the Validity of a Domain - checkDomain Utility
Table 10–1 (Cont.) Arguments Used by the domaininfo Utility
Argument
Description
-showrelativepaths
When listing subdomains, indicates if paths are relative. Only
relevant in combination with -listsubdomains or -all.
-terse
Removes the header information from the output, therefore
returning only the requested information.
Checking the Validity of a Domain - checkDomain Utility
This utility is used to check the validity of an existing domain. Its primary purpose is
to verify that a master domain matches its respective local domains and report all
discrepancies to the administrator.
checkDomain Usage
checkDomain -d pathToDomain -type expectedType {-q}
The following table provides descriptions of the arguments used by the checkDomain
utility.
Table 10–2
Arguments Used by the checkDomain Utility
Argument
Description
-d pathToDomain
Path to the domain that needs to be validated.
-type expectedType
Expected type of domain: simple, master, or sub.
-q
Quiet mode. Do not display progress messages.
When checkDomain is run on a simple domain the following two items get
validated:
■
The domain directory exists
■
It is of type "simple"
If checkDomain is run on a global domain, it verifies the following:
■
The global domain exists
■
The global domain is of type "master"
■
The global domain checks all of the sub-domains for:
■
The sub-domain directory exists and is of type "sub"
■
If the master domain and the sub-domain have a repos directory
■
The measures, rules, rule groups, templates, and functions are the same in the
global and sub-domain
If it is run on a sub-domain, it checks all of the items listed above for the global
domain, but the validation is only performed between the global domain and the
specified sub-domain.
Informational Utilities 10-3
Determining RPAS Server Version - rpasversion Utility
Determining RPAS Server Version - rpasversion Utility
Use the rpasversion utility to determine which version of the RPAS Server is
running in a particular location.
rpasversion Usage
rpasversion -l pathToLibrary
List Contents of a Database - listDb Utility
Use listDb to list the basic information of all arrays contained in the databases
provided.
listDb Usage
listDb
listDb
listDb
listDb
listDb
listDb
pathToDb*
-row -db pathToDb*
-row -pageUsage -db pathToDb*
-row -standardOptions -db pathToDb*
-standardOptions -db pathToDb*
-version
The following table provides descriptions of the arguments used by the listDb
utility.
Table 10–3
Arguments Used by the listDb Utility
Argument
Description
-db pathToDb
Specifies the database to list the contents.
-row
List array information in a row format.
-pageUsage
Show btree page usage. Requires -row switch to be active.
-standardOptions
List only standard options.
Printing Data from Arrays - printArray Utility
Use printArray to print the contents of an array.
printArray Usage
printArray -array db.array -specs {-maxpos num}
printArray -array db.array {-cell "dim1:pos1,dim2:pos2,..."
{-format "formatString"}
printArray -array db.array -slice "dim1:pos1,dim2:pos2,..."{-format
"formatString"} {-cellsperrow num} {-noposnames}
printArray -array db.array -allpopulatedcells {-format "formatString"}{cellsperrow num} {-noposnames}
10-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Printing Data from Arrays - printArray Utility
The following table provides descriptions of the arguments used by the printArray
utility.
Table 10–4
Arguments Used by the printArray Utility
Argument
Description
-array db.array
Specifies the array to print.
Specify the full path to the database containing the array.
Required for all commands except -version.
db is a full or relative path to a database. Do not specify the .ary
suffix. If no other commands are included, the array defaults to
-allpopulatedcells with cells per row 1. The
-allpopulatedcells command is still available, but now
functions as a useful default action. The -noposnames,
-cellsperrow, and -format parameters may still be
specified when relying on the implicit -allpopulatedcells
behavior.
-specs
Prints the specifications of the array and positions along each
dimension.
-popcount
Outputs only the popcount of the specified array. Useful to
shell script writers to get the popcount value into a shell script
variable. For example, export POPCOUNT=`printArray array hmaint.dim_year -popcount`
-cell CELLSPEC
Prints a specific cell value from the array. Must not contain
spaces. Must identify a single of 1-D slice. Specify using the
format "dim1:pos1,dim2:pos2,…"
-cellplain CELLSPEC
Outputs a specific cell value with no space padding.
Useful for scripts when capturing cell values into shell variables.
Must not contain spaces. Must identify a single of 1-D slice.
Specify using the format "dim1:pos1,dim2:pos2,…"
-slice CELLSPEC
Prints a one-dimensional slice from the array. Must not contain
spaces. Must identify a single of 1-D slice. Specify using the
format "dim1:pos1,dim2:pos2,…"
-allpopulatedcells
Print all populated cells including the navalue of the array.
-format "fmtstr"
If -format is specified, any cells with numeric values are
interpreted as dates.
fmtstr (formatString) determines how dates are interpreted, and
can include:
■
%Y - 4 digit year
■
%m - month number (01 to 12)
■
%d - numeric day of month (01 to 31)
■
%H - 24 hour clock (00 to 23)
■
%M - minute (00 to 59)
■
%S - seconds (00 to 61)
■
%s - milliseconds
-cellsperrow num
For multi-cell output commands (-slice and -allpopulatedcells), indicates how many cells should be
printed on each line.
-noposnames
Suppresses the output of position names, only cell values are
shown.
Informational Utilities 10-5
Printing Data from Measures - printmeasure Utility
Printing Data from Measures - printmeasure Utility
Use the printmeasure utility to print measure information.
printmeasure Usage
printmeasure -d domainPath {-wb wbName} {-m measure} [COMMAND]
The following table provides descriptions of the arguments used by the
printmeasure utility.
Table 10–5
Arguments Used by the printmeasure Utility
Argument
Description
-d pathToDomain
Specifies the domain that contains the measure to print. Requires
the -m parameter.
-m measure
Specifies the measure to print.
-wb workbookName
Specifies the workbook associated with the measure to print.
If -wb is not used, the domain measure information is printed.
Requires the -m parameter.
-list
printMeasure will return a list of all registered measures in
the domain. This argument does not require -d domainPath.
-listHBIMeasures
In a global domain, printMeasure will return a list of all
measures registered at or above the partition dimension.
-specs
printMeasure returns the list of measure properties. Requires
the -m parameter.
-listDataIntersections
printMeasure will return the base intersection of the measure.
10-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
11
Internationalization
11
Internationalization is the process of creating software that can be translated more
easily. Changes to the code are not specific to any particular market. This section
describes configuration settings and features of the software that ensure that the base
application can handle multiple languages.
Oracle Retail applications have been internationalized to support multiple languages.
Translation
Translation is the process of interpreting and adapting text from one language into
another. Although the code itself is not translated, components of the application that
are translated include the following:
■
Graphical user interface (GUI)
■
Error messages
The following components are not translated:
■
Documentation (online help, release notes, installation guide, user guide,
operations guide)
■
Batch programs and messages
■
Log files
■
Configuration tools
■
Reports
■
Demonstration data
■
Training materials
The user interface has been translated into the following languages:
Note: In Table 11–1, the language identifier is used for position
labels. For more information, see the Position Label Translation
section. The Windows Language ID is in the foundation.ini file. For
more information, see the Translation Administration section.
Internationalization
11-1
Translation Administration
Table 11–1
Supported Languages with Language Identifiers
Language
Language Identifier
Windows Language ID
Chinese (Simplified)
CHINESE_SIMPLIFIED
2052
Chinese (Traditional)
CHINESE_TRADITIONAL
1028
Croatian
CROATIAN
26
Dutch
DUTCH
19
English
ENGLISH
9
French
FRENCH
12
German
GERMAN
7
Greek
GREEK
8
Hungarian
HUNGARIAN
14
Italian
ITALIAN
16
Japanese
JAPANESE
17
Korean
KOREAN
18
Polish
POLISH
21
Portuguese (Brazilian)
PORTUGUESE
22
Russian
RUSSIAN
25
Spanish
SPANISH
10
Swedish
SWEDISH
29
Turkish
TURKISH
31
Translation Administration
For information on the translation of position labels, see the
Position Label Translation section.
Note:
Every product, location, and calendar position can be presented in multiple languages,
as can messages presented through the client. However, before translated strings can
be viewed in the client, the following processes must be followed to setup the
environment to support multiple languages.
1.
Build the domains with the Multi-Language setting enabled in the Configuration
Tool properties.
2.
By default, the language of the RPAS Client is determined by the language of the
client-side operating system. You can override this behavior by setting the
Language entry in the Options section of the foundation.ini file:
[Options]
Language=LANGID
LANGID represents a value in the Windows Language ID column of Table 11–1.
11-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Translation Administration
Or, you can set the following option:
[Options]
ResourceDLL=LANG.dll
LANG.dll represents a value in the Language Identifier column of Table 11–1.
If the RPAS Client cannot find the library for the language you specify, it defaults
to English.
3.
Locate the foundation.ini file. It is found in one of the following places. When
RPAS searches for the file, it searches in the following order:
a.
The user's Application Data folder:
–
For Microsoft Windows XP:
C:\Documents and Settings\<user>\Application Data\Oracle Predictive
Solutions
–
For Microsoft Windows 7:
C:\Users\<user>\AppData\Local\Oracle Predictive Solutions
b.
The same folder as the currently loaded foundation.exe file.
c.
The current working folder, which can be one of the following:
d.
–
The debugger's setting, if started by debugger
–
The same folder as the foundation.exe file, if started manually
–
./winnt/system32, if started from automation
C:\Windows
If the file is not found, it is created in the Application Data folder described in
Step a.
4.
Place the solution and RPAS .ovr files for the language selected into the 'input'
directory of your domain. The .ovr files are found in RPAS_HOME/translations.
The input directory should also contain the lngs.dat file that will be loaded prior
to loading the .ovr files. If not packaged with the language .ovr files, the current
lngs.dat file will be in the "input/processed" folder of the domain. Move it back to
the input folder and remove the timestamp extension. Then reload the hierarchy
using loadHier -d /path -load lngs. Make sure that the language you are loading
exists in the lngs.dat file before loading it. Load each .ovr file within the input
directory by using the loadmeasure utility (for example, loadmeasure -d /path measure r_msglabel).
Internationalization
11-3
Translation Administration
Notes:
■
■
■
The files will be removed from your input folder when they are
loaded. Therefore, any file that is left in this directory still needs to
be loaded.
For Japanese, Korean, Chinese Simplified/Traditional, Russian,
you will need to reboot your machine in each of these languages
to properly see text if you changed the Windows regional options
to one of these languages, as described in the next step.
The translated .ovr files are released in UTF-8 encoding. Any
changes to these files should be made with a UTF-8 capable editor
and saved without BOM (Byte Order Mark).
The .ovr files consist of three data columns, as shown below.
Gub_mean_
SPANISH
Media máxima
The data is populated on a specific column and has definite width.
When making any change to this data, you must ensure that the
new data abides by the predefined width and position for that
data for the file.
5.
Set the default language to match.
■
■
On Windows XP, in Regional Options, set the Standards and formats list to
the desired language. Set Location to the appropriate country. Click the
Advanced tab and set Language for non-Unicode programs to the
appropriate language.
On Windows 7, access the Control Panel and click Clock, Language, and
Region, then click Region and Language. In the Region and Language dialog
box, set the Format field to the desired language. Click the Location tab and
set the Current Location field to the desired location. Click the Administrative
tab and click Change System Locale button to set the desired language.
Translation Administration Workbook
The Translation Administration workbook contains worksheets for translating text
used in measure labels, workbook template names, template group names, user group
labels, and general areas (for instance, wizard instructions, and error messages).
RPAS and solution-specific messages to the user should not be
modified. If changes are made to these messages they may be
overwritten when patching occurs.
Note:
Hierarchy Labels Worksheet
The Hierarchy Labels worksheet allows the user to view and edit the translations of
hierarchy labels. Translations are supported for each of the system's allowable
alternative languages.
11-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Translation Administration
Dimension Labels Worksheet
The Dimension Labels worksheet allows the user to view and edit the translations of
dimension labels. Translations are supported for each of the system's allowable
alternative languages.
Workbook Template Group Labels Worksheet
The Template Group Translations worksheet allows the user to view and edit the
translations of template group names. Translations are supported for each of the
system's allowable alternative languages. Translations in this worksheet affect the
labels on the tabs that appear in the File - New dialog (for example (in English),
Administration, Analysis, and Predict).
Workbook Template Labels Worksheet
The Template Translation worksheet allows the user to view and edit the translations
of workbook template names. Translations are supported for each of the system's
allowable alternative languages.
Measure Labels Worksheet
The Measure Translations worksheet allows the user to view and edit the translations
of measure labels. Translations are supported for each of the system's allowable
alternative languages.
Measure Descriptions Worksheet
The Measure Descriptions worksheet allows the user to view and edit the translations
of measure descriptions. Translations are supported for each of the system's allowable
alternative languages.
User Group Labels Worksheet
The User Group Translations worksheet allows the user to view and edit the
translations of user group labels. Translations are supported for each of the system's
allowable alternative languages. The list of user groups includes the Administration,
Default, and Internal user groups, plus any other user group names set up by the
system administrator. For products in the Oracle Retail Predictive Planning Suite, the
list of user groups also includes the various planning roles.
Message Labels Worksheet
The Message Labels worksheet allows the user to view and edit the translations of
messages displayed to users in the RPAS Client. Translations are supported for each of
the system's allowable alternative languages.
RGRP Labels Worksheet
The RGRP Labels worksheet allows the user to view and edit the translations of rule
group labels displayed to users in the RPAS Client. Translations are supported for each
of the system's allowable alternative languages.
Internationalization
11-5
Translation Administration
11-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
12
Commit as Soon as Possible
12
Commit As Soon As Possible (Commit ASAP) allows users to schedule the commit
process of workbook data so that it executes as soon as all the system resources are
available. Commit ASAP is an option in the File menu of the RPAS Client. Procedures
for using Commit ASAP are provided in the RPAS User Guide.
Commit ASAP takes a copy of the data to be committed. Unlike Commit Later, which
adds a workbook commit process to a queue that is run in batch, the data that is
eventually committed is the data that was present at the time the commit instruction
was issued. With Commit Later, if the user makes further changes to the workbook
and saves that workbook before the batch commit process is run, those changes will
also get committed.
Using Commit ASAP
After attempting to commit a workbook using Commit ASAP (File\Commit ASAP),
the user will see a message in the client that the workbook has been scheduled for a
commit. The user can continue with his/her work. The system will then try to commit
the workbook as soon as it can, taking into account any other scheduled commits. If
the commit cannot be done prior to the domain's Commit ASAP deadline, it will be
canceled and listed as failed.
There are four states for commit processes to be added to the Commit ASAP queue.
■
Pending - The commit process is queued up to take place at some point in the
future.
■
Committing - The workbook is currently being committed.
■
Success - The commit succeeded.
■
Failed - The commit failed.
The status of each Commit ASAP process can be viewed by using a dialog window
called Commit Status from the File menu. This dialog window displays all of the
Commit ASAP processes with their respective status for all processes that have not
been purged (see below). This dialog can be used to sort the tasks based on any of the
columns.
Entries can be filtered in a variety of ways. If the checkbox All Users is not checked,
the user will only be able to view his/her entries. If it is checked, you will see the
entries for all users. The checkboxes in the Status To Display group allow you to filter
the output so that the user sees only the processes with the specified statuses. The
window can be updated by using the Refresh button. The dialog remembers the
settings based on the last use.
Commit as Soon as Possible 12-1
Managing the Workbook Queue - showWorkbookQueues
Notes:
■
■
If a user attempts to commit a workbook using the Commit ASAP
option, and the workbook already has a process in the queue, the
original processes is removed from the queue. That means that
there can only ever be one pending Commit ASAP in the queue
for a given workbook/user/template name combination.
Workbooks must have been saved at least once before attempting
a Commit ASAP. A workbook has not been saved if the label says
"untitled."
Managing the Workbook Queue - showWorkbookQueues
The RPAS utility showWorkbookQueues is used for viewing the status of Commit
ASAP processes and for purging entries in the Commit ASAP status window. The
usage of this utility follows below.
The purge option requires a date before which entries will be removed, as well as
specification for which entries to remove: succeeded, failed, or both.
showWorkbookQueue Usage
showWorkbookQueues -version
showWorkbookQueues -d domainPath -show
[all|pending|waiting|working|success|failed]*
showWorkbookQueues -d domainPath -purge date [success | failed]*
The following table provides descriptions of the arguments used by the
showWorkbookQueues utility.
Table 12–1
showWorkbookQueues Arguments
Argument
Description
-version
Prints the RPAS version, revision, and build information of the
utility.
-d domainPath
Specifies the path to the domain.
-show
Lists the contents of the queue in the order in which the
parameter is specified. Possible values: all, pending,
waiting, working, success, and failed.
all
Used with the -show parameter. This lists all of the workbooks
in all statuses.
pending
Used with the -show parameter. This lists all workbooks that
are waiting to be committed.
waiting
For Oracle Retail development use only.
success
Used with the -show parameter. This lists all workbooks that
have been successfully committed.
failed
Used with the -show parameter. This lists all workbooks that
did not successfully commit.
12-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Commit ASAP Settings - configCommitAsap
Table 12–1 (Cont.) showWorkbookQueues Arguments
Argument
Description
-purge date
Purges entries in the Commit ASAP status window. Entries
before the date provided will be removed.
The date should be a string of the following DateTime format:
YYYYMMDDHHmm
For example "200406071529" equals June 7, 2004 3:29 PM.
Administrator must select to purge commit processes that either
succeeded or failed.
Commit ASAP Settings - configCommitAsap
There are two settings for Commit ASAP that are managed by an administrator. Both
are set using the utility configCommitAsap.
■
■
Maximum number of simultaneous commit processes (property MaxProcesses,
default value is 4).
Deadline for which all pending processes must be completed, after which they will
be cancelled and marked as failed.
This deadline will likely be used by administrators before beginning nightly batch
processes (property deadline, default value is 00:01 [meaning 12:01 AM], in 24-hour
time).
A commit process that starts before the deadline is reached will be processed. Commit
requests that were in the queue before the deadline that did not get processed will be
cancelled and marked as failed. Commit requests added to the queue after the
deadline will use the deadline of the following day.
configCommitAsap Usage
configCommitAsap -d pathToDomain [-maxProcs numProcs]
[-deadline time] [-display]
The following table provides descriptions of the arguments used by the
configCommitAsap utility.
Table 12–2
configCommitAsap Arguments
Argument
Description
version
Prints the RPAS version, revision, and build information of the
utility.
-maxProcs numProcs
Sets the maximum number of concurrent commit processes
where numProcs is an integer greater than 0.
Workbooks can be committed in parallel if they do not require
access to the same measure databases.
If they do share databases, they will be committed sequentially.
-deadline time
The time of the day when all outstanding commit ASAP
operations will timeout.
If a commit ASAP operation is submitted after this time, it will
not timeout until the deadline time on the next day.
This string must have the following format:
HH:MM
For example "13:30" refers to 1:30 PM.
Commit as Soon as Possible 12-3
Commit ASAP Settings - configCommitAsap
Table 12–2 (Cont.) configCommitAsap Arguments
Argument
Description
-display
Displays the current commit ASAP settings.
-loglevel level
Use this argument to set the logger verbosity level. Possible
values: all, profile, information, warning, error, or
none.
-noheader
To disable timestamp header use.
Logging and Technical Information
A log file is available in the Commit ASAP directory that should be checked if a user
reports an error with a Commit ASAP submission. The file is named rpasServer.log
and is in the following directory: <Path to domain>/commitAsapQueue.
Another log file is generated for each Commit ASAP process and stored in a user's
directory (users/<userid>/asapLogs). The format of the log file name is
"orig_<original workbook name>asap_<temporary workbook name>.log." RPAS
creates a temporary workbook in this process to capture the snapshot of the data that
needs to be committed. Temporary workbooks are never viewed by a user. An
administrator can use this log if something does not properly commit.
These "snapshot" workbooks cannot be viewed or used in the
RPAS Client.
Note:
An example of this log file is orig_t1_asap_t5 where "t1" is the name of the original
workbook and "t5" is the name of the snapshot workbook.
The following directories are used to store the copies of the workbook as they are
processed through the system:
■
■
■
■
■
Pending directory - Contains one file per submitted Commit ASAP that has not
yet been processed. These files are, in general, binary and cannot be easily read.
Working directory - Contains one file per submitted Commit ASAP that is
currently in the commit process.
Success directory - Contains one file per submitted Commit ASAP that has
successfully completed its commit process.
Failed directory - Contains one file per submitted Commit ASAP that either had a
failure during its commit process or could not be committed prior to the deadline.
Unknown directory - If the Commit ASAP process detects a corrupted queue file, a
message gets logged and the file gets moved into the unknown directory.
12-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
13
Batch Processes and RPAS Utilities
13
Included with an RPAS installation is a collection of stand-alone executables and
scripts that are used for a variety of operations. RPAS utilities are run directly against a
domain. If in a global domain environment, most utilities can only be run on the
master domain. RPAS utilities can be categorized into the following groupings:
■
■
■
■
Hierarchy management - The loading and refreshing of hierarchies, and the
process of updating the data structures in the domain to reflect hierarchy changes
Measure data - Utilities for loading, exporting, and moving data within and
between domains
Miscellaneous - A variety of utilities for performing certain procedures in batch
and for setting a number of parameters on an environment/domain
Information RPAS utilities - A variety of utilities that retrieve information about a
domain, data, the RPAS Server code, or an object used by the server
CSV File Format
For those utilities that use a comma-separated value (CSV) file, the following
formatting applies for any commas or double quotation marks in the data:
■
■
■
If the data does not contain any commas or double quotation marks, it does not
need any special formatting.
If the data contains a comma, the string must be enclosed between opening and
closing double quotation marks.
If the data contains quotation marks, the string must be enclosed between opening
and closing double quotation marks and any embedded quotation marks need to
be paired.
The following table shows examples of the formatting.
Table 13–1
CVS File Format
Data
Formatted Data
Item 001
Item 001
Item 001, Soda
"Item 001, Soda"
"Large Screen" TV
""Large Screen"" TV"
Item 002, "Generic Brand" Cereal
"Item 002, ""Generic Brand"" Cereal"
Batch Processes and RPAS Utilities 13-1
RPAS Utilities Logging Options
RPAS Utilities Logging Options
RPAS has a number of applications used to control or process data. Currently there are
no unified methods for logging output, controlling the level of logging, or directing
logging to a particular file. Instead each utility has its own methods, although many
are similar. The current behavior for each utility follows.
Log Levels
This is a list of the standard log levels, controlled by the -loglevel option. Not all
programs use these levels, but most do. Default logging level is Warning, which means
that any log messages that are specified as a warning or higher will be output:
■
All - Forces all log levels to be output
■
Profile - Performance profiling information
■
■
■
Audit - User-specific domain and workbook activities. These activities include the
following:
■
Workbook build, calculation, save, commit and custom menu operations
■
User login and logout to domain
Information - General status messages that are not problematic. Outputs status
and progress of the operation, in addition to the error and warning messages.
Warning - Messages indicating a potential problem, but not one that is fatal.
Outputs warning messages, in addition to error messages.
■
Error - Messages relating to a fatal problem. Outputs only error messages.
■
None - No messages. There should be no output if the utility successfully executes.
Each of the lines that contain the above types of feedback is normally preceded with a
code that indicates what type of information is being output. Each code should have
an angle bracket ("<") in front of it.
■
E indicates that the message is an error.
■
W indicates that the message is a warning.
■
I indicates that the message is informational.
■
U indicates that the message is audit-relevant information.
■
P indicates that the message is a performance profile.
Audit information related to workbook activities gets recorded
in rpas.log under each user's working directory. Information related to
domain activities, such as user sign-on and sign-off, gets recorded in
DomainDaemon.log.
Note:
13-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS Utilities Logging Options
Utilities with Standard Logging
A number of utilities allow for the -loglevel option to control which messages are
output to the screen. There is no way to log to a file directly. The table below displays
the utilities that can use the -loglevel option.
Table 13–2
loglevel Utilities
alertmgr
regfunction
checkDomain
regmeasattr
configCommitAsap
regtemplate
createdb
regTokenMeasure
createGlobalDomain
reguserdim
dattrmgr
rpasverison
dbdiff
rtkappcnfgmeas
dimensionMgr
showWorkbookQueues
domaininfo
syncNAValue
ldrule
updateArray
listDb
updatestyles
mapData
upgradeDomain
moveDomain
usermgr
printArray
wbmgr
printMeasure
Scripts
Shell scripts cannot use standard logging, but may execute the following programs
that use it:
convertDomain
All output to the screen.
createRpasDomain
The -v option controls the type of messages sent to the screen.
Batch Processes and RPAS Utilities 13-3
RPAS Utilities Logging Options
Utilities with Multi-Process Logging
Some utilities are based on the multi-processes domain utility framework. These
utilities send messages to the screen and a log file master.log. Any child processes
output messages to a log file in the domain/output directory named
subdomain0000.log where the number indicated the sub-domain being processed. This
directory will contain all log files created during the run of that utility. This change has
been updated so that the controlling process logs to the screen as well as to a file in
that directory. The newly created directory name is formatted as
APPNAMEYYYYMMDDHHMIbXX, where APPNAME is the utility name, YYYY is the year,
MM is the month, DD is the day, HH is the hour, MI is the minute, the character b, and XX
is two digits used to make the directory name unique. The framework will attempt to
limit the number of directories created for any single utility to eight. The parameter loglevel can be used to control the type of messages send to the screen and log file.
These utilities are as follows:
■
exportData
■
loadmeasure
■
loadHier
■
exportMeasure
■
reconfigGlobalDomainPartitions
■
wbbatch
■
reindexDomain
domainprop
The domainprop utility only provides logging to the screen.
hierarchyMgr
The hierarchyMgr utility only provides logging to the screen.
configCommitAsap
This utility should be started from the RpasDbServer application when the client
requests a workbook to be committed.
13-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS Utilities Logging Options
Utilities with Special Logging
These utilities may use standard logging with additional features, or may use entirely
different logging methods.
DomainDaemon
The DomainDaemon uses standard logging. Logs output to a file (see below). The file
is created either in the current working directory or in the directory specified by the
RPAS_LOG_PATH environment variable.
The file name depends on the RPAS_LOG_BACKUPS environment variable. If it is set
to 1 or greater, then:
The log file name is Daemon_Dyyyymmddhhmmbxx.log where yyyy is the current
year, mm is the current month, dd is the current day, hh is the current hour, mm is the
current minute and xx is some number used to make the file name unique.
The number of these log files will be limited to the number provided in the
environmental variable RPAS_LOG_BACKUPS.
Otherwise, the log file name will be Daemon.log. Any existing log file is renamed to
Daemon.old.
At midnight the current log file is closed and a new one opened, with naming as
above.
RpasDbServer
This should only be started from the DomainDaemon as a part of a client request to
start an RPAS session. The logging level is controlled by the client's
RPAS_LOG_LEVEL environment variable. If not set then it defaults to logging
messages at the warning level.
This utility creates log files in the domain/users/client directory, where domain is the
current domain path and client is the current client. The actual file name used will be
either rpas Dyyyymmddhhmmbxx.log or rpas.log base on the environmental variable
RPAS_LOG_BACKUPS (c.f. DomainDaemon, above).
loadHier
The loadHier utility uses standard logging. This utility performs part of its processing
in child processes. loadHier provides a list of all hierarchy positions that have been
changed since the previous hierarchy load. The resulting directory name is:
<utility><YYMMDDHHMISS><pXXXXX><bYY>
where utility is the name of the program (for example,-loadmeasure), followed by a
time/date stamp, then the process id (pXXXX), and then a 2 digit number to avoid
conflicts (bYY).
If there are any problems loading specific records that belong to the partition
hierarchy, they are reported in the format as shown below. Note that the record is
completely reproduced in this error report in the log.
<E 2008Jul02 12:04:52.196> Could not find position '90000044' in line number 3:
'2001052090000044 1000 7 '. Skipping!
Batch Processes and RPAS Utilities 13-5
RPAS Utilities Logging Options
Problems with records along non-partition hierarchies are reported as shown in the
following:
<I 2008Jul02 12:04:55.482> MeasureLoader::loadDataFromFile() Loading '.ovr' file
'/vol.nas/u09/rpasqc/qc_testing/aix/1208rc2_test/RDF_12/ldom1/input/psal.ovr'
<D 2008Jul02 12:04:55.514> Error on line 1: '2001031110000044 STR1000 8 '
.Position name: STR_STR1000 not found.
<D 2008Jul02 12:04:55.514> Error on line 2: '2011041510000044 1000 9 ' .Position
name: DAY20110415 not found.
<D 2008Jul02 12:04:55.964> 2 lines had problematic data.
locked
Messages are sent only to the screen.
mace
The mace utility uses standard logging. The -debugRuleEngine option logs some
messages to the file mace.log in the current working directory.
reconfigGlobalDomainPartitions
Uses standard logging. The loadHier process may be spawned as a child process. See
the loadHier entry for additional details. When the loadHier utility is started as a child
process it remaps the screen output of to the log file loadHier.log contained in the
current working directory.
renamePositions
Uses standard logging. The -log option overwrites the default log file name of
hierName and Rename.log in the current working directory. The -loglevel parameter
does not control the types of messages written to this log file.
regmeasureServer
This application should only be started from the RPAS libraries to process measure
registration/deregistration. Each process creates a log file in a newly created directory
in the domain output directory. The newly created directory name will be formatted as
regServerYYYYMMDDHHMIbXX, where YYYY is the year, MM is the month, DD is
the day, HH is the hour, MI is the minute, the character b and XX is two digits used to
make the directory name unique. The RPAS libraries will attempt to create at most
eight directories for any single application.
Utilities and Database Locks
On UNIX and Linux platforms, before running any RPAS program, it is important to
run "umask 0". Otherwise the RPAS databases may be permanently locked out to
access by other users or groups. This applies to any program that accesses any RPAS
database, including, but not limited to:
■
convertDomain
■
createRpasDomain
■
DomainDaemon
■
domaininfo
■
exportMeasure
■
ldrule
■
listDb
13-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Common Information and Parameters for RPAS Utilities
■
loadhier
■
loadmeasure
■
mace
■
printArray
■
printMeasure
■
printMeasureInfo
■
regmeasure
■
rpasInstall
■
RPASODBCAgent
■
RPASODBCDataService
■
usermgr
If database lock files (*.db.lck) have been created with limited permissions that block
other users' access, a workaround is to run the following commands when logged in as
the lock-file-owning user:
$ find {domainPath} -user {owner} -name \*.lck -exec rm -f {} ';'
where {domainPath} is the path to the domain and {owner} is the UNIX user that owns
the lock files.
Using Shell Scripts to Run Batch Processes
Batch processes should be written using scripts that call the RPAS 11 binaries found in
the $RPAS_HOME/bin/ directory. Any log files generated by scripts will be in the
[DOM]/scripts/err/ directory. Examples of tools include Kornshell, Python, and Perl.
A Sample Shell Script
The following is a sample shell script that loads the product and location hierarchies
into a domain. It is assumed that this script is invoked from the [DOM]/scripts/
directory.
1 #!/bin/ksh
2 loadHier -d .. -load prod > ./err/loadhier.prod.log
3 loadHier -d .. -load loc >> ./err/loadhier.loc.log
Line 1 defines the shell that will execute the script. In this example, it is defined to be
the Korn shell. Therefore, this script will always be executed from the Korn shell even
if the user's shell is different.
Lines 2 and 3 call the loadHier utility to load the latest product and location
hierarchy information. Depending on the batch process to be performed by the shell
script, lines 2 and 3 can be replaced by one or more lines to call one or more RPAS
utilities.
Common Information and Parameters for RPAS Utilities
A number of standard arguments are available for most RPAS utilities. Check the
usage of a specific utility to verify whether or not it is available.
Batch Processes and RPAS Utilities 13-7
RPAS Intraday Enabler
Table 13–3
Standard Arguments for RPAS Utilities
Argument
Description
-version
Use this argument to get the version information of the utility
(for instance, RPAS 13.2.0). It does not require -d domainPath.
-d pathtodomain
Common to most utility this specifies the path to the domain
against which the utility will run or from which data will be
used.
-loglevel
See RPAS Utilities Logging Options for more information.
-n
Certain utilities contain this parameter to perform a dry run.
Using this option will show the administrator what would
change, but makes no actual changes to the system or data.
See the usage of a specific utility to see whether this option is
applicable.
-noheader
To disable the use of a timestamp in the header of the log file.
-help
Any of these arguments will output the utility information and
syntax to the terminal window. This can also be accomplished
by running the utility with no arguments.
-?
-usage
Logger verbosity levels determine how much information is generated on the terminal
when running a given utility. An administrator can set these levels for each RPAS
utility. The available logger verbosity levels are as follows:
■
none - There should be no output if the utility successfully executes
■
error - Outputs only error messages
■
warning - Outputs warnings in addition to error messages
■
■
information - Outputs status and progress of the operation in addition to the error
and warning messages
all - Outputs all available information generated by the utility, including error,
warning, and informational messages
Each line, that contains the above type of feedback, is normally preceded with a code
that indicates what type of information is being output. Each code should have an
angle bracket ("<") in front of it. E indicates the message is an error. W indicates the
message is a warning. I indicates the message is informational.
Configuration Tools Log Files
For the RPAS Configuration Tools, information is logged in the files stderr.txt and
stdout.txt, which are located in the bin sub-directory of the Tools directory. If a
problem with the configuration tools is encountered, send these two files to Oracle
Retail Customer Care along with a description of the problem.
RPAS Intraday Enabler
The RPAS Intraday Enabler (ride) functionality enables batch operations to be run over
an RPAS domain while users are accessing workbooks and completing workbook
operations.
13-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS Intraday Enabler
This functionality enables batch operations to be executed over a domain, but does not
prevent users from accessing other components that do not affect or interfere with the
batch operations. The running of an exclusive batch process will not cause any preexisting workbook operations that require domain access to fail or terminate. Users in
domains that are not part of the exclusive process will not be affected in any way.
In domains that have been locked by an exclusive batch process, the users are still able
to perform operations that only require access to the workbook. The operations
include the following:
■
Workbook Edits
■
Workbook Calculations
■
Workbook Saves
■
Workbook Opens
■
Workbook Navigation
■
Commit ASAP Entry
■
Commit Later Entry
Users that enter workbooks into the commit ASAP queue, while an exclusive lock is in
place, will have the entries processed after the exclusive process is complete.
In these same domains, users will not be able to perform operations that require access
to data within the domain. The access can be either read or write. The operations that
are prevented include the following:
■
Workbook Build
■
Workbook Refresh
■
Workbook Custom Menu (unless configured as intraday-concurrent)
■
Workbook Commit Now/Later
■
Insert Measure
■
Dynamic Position Maintenance (DPM)
When a user tries to access one of these operations after the exclusive lock is obtained,
a message is provided stating that an exclusive process is running. A default message
is provided or it can be replaced by providing a message as part of the call to the ride
utility.
When a user is working with a workbook in the master domain, a lock is required on
the master domain and all local domains that are needed for the operation. The
workbook operations in this domain are blocked when the master or local domain
data is accessed by the ride process. See the Examples section for more details on the
domain access during different types of ride processes.
Configuration functionality is provided so that a custom menu can be marked to run
concurrently with a ride process (intraday-concurrent).
Batch Processes and RPAS Utilities 13-9
RPAS Intraday Enabler
Note: See the RPAS Configuration Tools User Guide for details on how
to configure a custom menu to be intra-day-concurrent. A custom
menu that is configured to run concurrently with a ride process
should only access workbook data, run a script that uses the ride
utility, and/or run commits using the commit ASAP functionality.
Custom menus that update or read directly from the domain should
not be configured as intra-day-concurrent as this would conflict with
the ride process.
In order for a batch job to run over a domain without interference by an online activity,
exclusive domain access must be granted to the job that is running. This is achieved by
creating a domain access control using a dual-lock control. The domain access control
manages the lock request from workbooks and ride processes.
Figure 13–1 Domain Access Control
This figure shows the process control that is in place with the locking schema. In this
case, an administrator requests exclusive access to a domain in order to run a batch
job. This requires an exclusive lock on the domain in order for the job to run. After the
lock is received, no other workbook operations are able to get write access to the
domain until the process is complete. If the exclusive lock cannot be obtained, the
process should time out and the administrator notified based on the output of the ride
utility. When the ride utility times out, the domainStatus utility is automatically run
to provide details of the user workbook operations that are blocking the ride process.
See the Domain Lock Status Utility - domainStatus section on for details on that
procedure.
13-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS Intraday Enabler
ride Usage
ride -d domain -process pname|-script sname -args args {-message messageString} {timeout minutes} {-wait minutes} {-partitions pos1,pos2,…} {-masterInBatch}
The following table provides descriptions of the arguments used by the ride utility.
Table 13–4
ride Utility Arguments
Argument
Description
-d domain
Refers to a simple or master domain. When master domain is
specified, all local domains in the global domain environment
are locked as well as the master domain.
-process pname
The name of the process to execute. This parameter cannot be
used with the -script parameter.
-script sname
The name of the script to execute. This parameter cannot be
used with the -process parameter.
-args args
Process arguments passed to the script or process to be
executed. The -args parameter must be the last parameter or
switch for this application. All parameters or switches after the
-args parameter are passed on to the process or script to be
started.
-message messageString
This optional argument is the override message presented to the
user when trying to perform an operation blocked by an intraday batch process. A default message is provided to the user if
this argument is not provided.
-timeout minutes
The utility will time out if it cannot get access to the domains
during this time. By default, there is no timeout. The timeout
starts when the control utility is executed.
-wait minutes
Time to wait before starting the process or script. Even if
domain access is granted, the process does not start until the
end of wait time. The clock starts when the control utility is
executed. The default is 0.
-partitions pos1,pos2,…
Partition positions (such as dept1, dept2, and so on) that
determine the local domains that are accessed by the process or
script.
-masterInBatch
Indicates that, when running over a global domain
environment, the master domain will be accessed by the process
or script in addition to any local domains selected.
Note: If neither -partitions nor -masterInBatch are provided
on the command line, the entire domain will be processed when
running over a global domain environment; that is, all subdomains
and the master.
Scenarios
This section outlines several scenarios that are possible with the ride utility. The
scenarios outline the domain access based on how the ride utility is executed. The
tables indicate whether the specific operations are blocked or allowed.
Batch Processes and RPAS Utilities
13-11
RPAS Intraday Enabler
Scenario 1
This scenario is an example of running ride specifying only the master domain. This
will lock all domains.
Usage example: ride -d master -script script.ksh
Table 13–5
Running the ride Utility Specifying Only the Master Domain
Workbook Operation
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
Build
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Blocked
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Blocked
Commit
Now
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Blocked
Custom
Menu
(not ride
concurrent)
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Blocked
Insert
Measure
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Blocked
NA
Blocked
Blocked
Blocked
Refresh
DPM
Scenario 2
This scenario is an example of running ride specifying only one local domain (local
domain with partition position 100).
Usage example: ride -d master -script script.ksh -partitions 100
Table 13–6
Running the ride Utility Specifying One Local Domain
Workbook Operation
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
Build
HBI Measures
Blocked
Blocked
Allowed
Allowed
No HBI Measures
Blocked
Blocked
Allowed
Allowed
HBI Measures
Blocked
Blocked
Allowed
Allowed
No HBI Measures
Blocked
Blocked
Allowed
Allowed
Commit
Now
HBI Measures
Blocked
Blocked
Allowed
Allowed
No HBI Measures
Blocked
Blocked
Allowed
Allowed
Custom
Menu
(not ride
concurrent)
HBI Measures
Blocked
Blocked
Allowed
Allowed
No HBI Measures
Blocked
Blocked
Allowed
Allowed
Insert
Measure
HBI Measures
Blocked
Blocked
Allowed
Allowed
No HBI Measures
Blocked
Blocked
Allowed
Allowed
NA
Blocked
Allowed
Allowed
Refresh
DPM
13-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS Intraday Enabler
Scenario 3
This scenario is an example of running ride specifying only one local domain (local
domain with partition position 100) and the masterInBatch option.
Usage example: ride -d master -script script.ksh -partitions 100 masterInBatch
Table 13–7
Running the ride Utility Specifying One Local Domain and masterInBatch
Workbook Operation
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
Build
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Allowed
Allowed
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Allowed
Allowed
Commit
Now
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Allowed
Allowed
Custom
Menu
(not ride
concurrent)
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Allowed
Allowed
Insert
Measure
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Allowed
Allowed
NA
Blocked
Blocked
Blocked
Refresh
DPM
Scenario 4
This scenario is an example of running ride specifying two local domains (local
domain 1 with partition position 100 and local domain 2 with partition position 200).
Usage example: ride -d master -script script.ksh -partitions
100,200
Table 13–8
Running the ride Utility Specifying Two Local Domains
Workbook Operation
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
Build
HBI Measures
Blocked
Blocked
Blocked
Allowed
No HBI Measures
Blocked
Blocked
Blocked
Allowed
HBI Measures
Blocked
Blocked
Blocked
Allowed
No HBI Measures
Blocked
Blocked
Blocked
Allowed
Commit
Now
HBI Measures
Blocked
Blocked
Blocked
Allowed
No HBI Measures
Blocked
Blocked
Blocked
Allowed
Custom
Menu
(not ride
concurrent)
HBI Measures
Blocked
Blocked
Blocked
Allowed
No HBI Measures
Blocked
Blocked
Blocked
Allowed
Refresh
Batch Processes and RPAS Utilities
13-13
RPAS Intraday Enabler
Table 13–8 (Cont.) Running the ride Utility Specifying Two Local Domains
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
HBI Measures
Blocked
Blocked
Blocked
Allowed
No HBI Measures
Blocked
Blocked
Blocked
Allowed
NA
Blocked
Blocked
Allowed
Workbook Operation
Insert
Measure
DPM
Scenario 5
This scenario is an example of running ride specifying two local domains (local
domain 1 with partition position 100 and local domain 2 with partition position 200)
and the masterInBatch option.
Usage example: ride -d master -script script.ksh -partitions
100,200 -masterInBatch
Table 13–9 Running the ride Utility Specifying Two Local Domains and the
masterInBatch Option
Workbook Operation
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
Build
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Allowed
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Allowed
Commit
Now
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Allowed
Custom
Menu
(not ride
concurrent)
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Allowed
Insert
Measure
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Blocked
Blocked
Allowed
NA
Blocked
Blocked
Blocked
Refresh
DPM
13-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS Intraday Enabler
Scenario 6
This scenario is an example of running ride to lock the master domain.
Usage example: ride -d master -script script.ksh -masterInBatch
Table 13–10
Running the ride Utility to Lock the Master Domain
Workbook Operation
Master
Domain
Local
Domain 1
Local
Domain 2
Local
Domain 3
Build
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Allowed
Allowed
Allowed
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Allowed
Allowed
Allowed
Commit
Now
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Allowed
Allowed
Allowed
Custom
Menu
(not ride
concurrent)
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Allowed
Allowed
Allowed
Insert
Measure
HBI Measures
Blocked
Blocked
Blocked
Blocked
No HBI Measures
Blocked
Allowed
Allowed
Allowed
NA
Blocked
Blocked
Blocked
Refresh
DPM
Domain Lock Status Utility - domainStatus
The domainStatus utility provides a report on the processes that are locking the
domains. The purpose is to identify the user activities that are preventing a ride
process from running. This information is important since the ride process will not
terminate any existing workbook operation. The utility provides output that includes
the process ID, user ID, operation type, and operation start time.
With the output of this utility, the system administrator can determine the cause for
the ride process not running. This should provide them with enough information to
either notify the user that they are causing a delay or to manually terminate the
process. That will be driven by the specific client and their processes.
Note that this utility reports on domain-level locks used during the ride process. Lowlevel data locks are not exposed by this utility.
domainStatus Usage
domainStatus -d domain -autoRefresh refreshPeriod
The following table provides descriptions of the arguments used by the
domainStatus utility.
Argument
Description
-d domain
Refers to a simple or master domain. When master domain is
specified, all local domains in the global domain environment
are locked as well as the master domain.
-autoRefresh
refreshPeriod
Refreshes the lock status information every number of seconds
specified by the refreshPeriod.
Batch Processes and RPAS Utilities
13-15
RPAS Intraday Enabler
13-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
14
RPAS ODBC/JDBC Driver
14
The RPAS ODBC/JDBC Driver provides a SQL interface to the Oracle RPAS
embedded database (OREDB), which includes both domain data and workbook data.
This driver presents OREDB as a relational database to ODBC and JDBC client
applications. The RPAS ODBC/JDBC Driver enables ODBC 3.51 and JDBC 3.0
compatible applications to connect to OREDB. Connectivity has been verified with the
following applications:
■
Oracle Business Intelligence Enterprise Edition
■
Interactive SQL (ISQL) Utility
■
JDeveloper
The RPAS ODBC/JDBC Driver enables system users to read measure data for stored
measures in an RPAS domain.
■
■
■
■
■
In a global domain environment, connection to local domains is not supported.
Access to local domain data is possible through queries in global domains.
The ODBC/JDBC Driver does not provide support for Forced Non-HBI (FNHBI)
and non-materialized measures.
The ODBC/JDBC Driver reports only external position names in both dimension
tables and fact tables. Internal position names are not reported.
Limited support is provided for conditional queries on measure data.
The driver is not intended to replace the exportData utility, which is used for highspeed data export to ASCII files.
For information on installing the RPAS ODBC/JDBC Driver,
see the RPAS Installation Guide.
Note:
■
The ODBC driver inherits the RPAS user privilege. Note that if a user is not
allowed to view any measures in RPAS, the user cannot view any measures
through the ODBC driver either.
RPAS ODBC/JDBC Driver 14-1
ODBC Configuration
ODBC Configuration
On Windows, UNIX, and Linux platforms, configuring the system to connect the
ODBC drivers and a domain environment consists of the following steps.
1.
Install the ODBC server components. Refer to the RPAS Installation Guide.
2.
Install the ODBC client components. Refer to the RPAS Installation Guide.
3.
Start the RPAS ODBC Agent.
4.
Configure the ODBC server components.
5.
Configure the ODBC client components.
6.
Create the ODBC data source name (DSN). This enables ODBC applications, such
as OBIEE, to connect to the domain environments configured in the ODBC server
and client configuration.
7.
Start the RPAS ODBC Data Service.
8.
Test the connection using Interactive SQL.
Defining the ODBC Server Configuration Settings
On UNIX/Linux platforms, upon completion of the ODBC server installation, a
directory named odbcserver should be created under $RPAS_HOME. An RPAS ODBC
Agent process should be started automatically. This Agent process works with the GUI
ODBC Management Console installed on Windows PC to perform management and
configuration tasks. The Windows version of RPAS ODBC Server must be installed on
the Windows PC to make the ODBC Management Console available.
To define the ODBC Server configuration settings:
14-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
Add RPAS ODBC Manager in the Management Console
To add RPAS ODBC Manager in the Management Console:
1.
From the Start menu, select Oracle RPAS ODBC Server and then Management
Console. The Oracle RPAS ODBC Management Console appears.
When you start the Management Console for the first time, an
error message appears indicating the snap-in is not registered.
Note:
Figure 14–1 Console Manager Window Opened for First Time
RPAS ODBC/JDBC Driver 14-3
ODBC Configuration
2.
To create a new work space, select File and then New.
Figure 14–2 Console Manager Window Showing Console Root Directory
To connect to a remote host, the Management Console is installed on a Windows
PC and the Agent service is installed on a remote server.
14-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
3.
To add a new snap-in, select File and then Add/Remove Snap-in to start the
wizard to add a new snap-in.
Figure 14–3 Add/Remove Snap-in Dialog Box
RPAS ODBC/JDBC Driver 14-5
ODBC Configuration
4.
To add a new snap-in, click Add.
Figure 14–4 Add Standalone Snap-in Dialog Box
14-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
5.
Select Oracle Retail RPAS ODBC Server Manager and click Add.
Figure 14–5 Add Manager Dialog Box Showing Selection of the Mode for a New Manager
RPAS ODBC/JDBC Driver 14-7
ODBC Configuration
6.
Select Local Host or Remote Host depending on the location of the server you
want to manage and then click Next.
Figure 14–6 Add Manager Dialog Box Showing Connection Information to be Added for
the Agent
7.
On the Add Manager window, enter the address of the server host machine and
the TCP port number at which the RPAS ODBC Agent is listening.
8.
If the Agent is not SSL enabled (which is the default), uncheck "Encrypted(SSL)". If
the Agent is SSL enabled, check "Encrypted(SSL)".
9.
Click Finish. You are returned to the previous window. You can click Close or OK
to close the windows.
14-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
Configure Using the ODBC Manager
From the Management Console, use the ODBC Manager to perform the required
configuration.
1.
To configure for a remote host, click + to expand the ODBC Manager you just
added.
Figure 14–7 Console Manager Window Showing Expanded Console Root Directory
2.
To connect to the Agent service, click + in front of "not connected to Unknown
Service". If the Logon to Service dialog box is displayed, log on using the user
name and password of a user who can administer the service on the local or
remote server.
RPAS ODBC/JDBC Driver 14-9
ODBC Configuration
3.
Expand Services by clicking +.
Figure 14–8 Console Manager Window Showing Expanded Connected to
RPAS_ODBC_Agent Directory
4.
Set up the environment variables.
This step only applies to RPAS_Data_Service running on a
Windows platform.
Note:
The PATH environment variable must be configured to include the following
paths:
■
Path to the bin subdirectory of RPAS_Home
■
Path to the ODBC server binary
■
Path to the ODBC server IP binary
14-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
a.
Navigate to the following screen. The following figure shows the exact screen
you should see.
Figure 14–9 Console Manager Window for Configuration
b.
Right-click on the blank space of the right panel.
c.
Select New/Attribute in the menu.
RPAS ODBC/JDBC Driver
14-11
ODBC Configuration
d.
Select ServiceEnvironmentVariable from the list for Attribute. In the Value
field, enter the following:
PATH={pathToRpasHomeLib};{pathToODBCServerBin};{pathToODBCServerI
PBin}
In the sample shown in the following figure, the following values are set:
- {pathToRpasHomeLib} is set to D:/src/rpas_head/rpasHome/lib
- {pathToODBCServerBin} is c:/odbcserver/bin
- {pathToODBCServerIPBin} is c:/odbcserver/ip/bin
Figure 14–10 New Attribute Dialog Box
e.
5.
Click OK.
Expand Data Source Settings on the Console Manager window. You should find a
pre-configured data source named gdom.
When you create a new data source, make sure that most
parameters of the new data source are identical to the parameters of
the pre-configured data source gdom, except for
DataSourceIPProperties and DataSourceIPCustomProperties.
Note:
The DataSourceIPCustomProperties attribute contains pre-registered property
names, which are not to be modified.
14-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
6.
Under gdom, select IP Parameters.
Figure 14–11
7.
Console Manager Window with IP Parameters Selected Under gdom
On the right panel of the window, double click DataSourceIPProperties attribute.
The following window appears.
Figure 14–12
DataSourceIPProperties Properties Dialog Box
Make sure the Value field has the keyword "DOMAIN_PATH=", and the string
after the "=" sign is the absolute path to the RPAS domain you want connect to on
the server side.
To connect to a domain on the local host, the following is an example of the path:
"DOMAIN_PATH=C:\RPAS\11\Test\ODBC\nt_testGlobalDomain"
RPAS ODBC/JDBC Driver
14-13
ODBC Configuration
8.
On the right panel of the window, double click the DataSourceIPCustomProperties
attribute. The following window appears.
Figure 14–13 DataSourceIPCustomProperties Properties Dialog Box
Copy the value from the DataSourceIPCustomProperties of the sample "gdom"
data source to make sure all pre-registered properties are included.
Import the Configuration Changes
1.
To save the configuration, right click Services in the Console Manager window. In
the menu, select All Tasks and then Save Configuration.
2.
To save the snap-in configuration, select File and then Save As. Select
<installdir>\admin\oaadmin60.msc for the file name. This will overwrite the
original file (which was basically empty).
3.
Stop and start the RPAS Data Service.
Right-click RPAS_Data_Service. In the menu, click Stop RPAS_Data_Service or
Start_RPAS_Data_Service. If you have made changes to any of the service
attributes, you need to restart the Data Service.
The RPAS ODBC Data Service is now ready to accept connections.
14-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
Defining the ODBC Client Configuration for Windows
To define the ODBC Client configuration settings:
1.
From the Start menu, select "ODBC Administrator" under the "Oracle RPAS odbc
driver" menu item.
Upon successful installation of RPAS ODBC Client, a sample
DSN named SampleRPAS is automatically created and configured to
connect to the data source gdom on the server side. To create a new
DSN, see the following steps.
Note:
2.
In the ODBC Data Source Administrator window, select Add to add a data source.
Figure 14–14
ODBC Data Source Administrator Dialog Box
RPAS ODBC/JDBC Driver
14-15
ODBC Configuration
3.
In the Create New Data source window, select Oracle RPAS.
Figure 14–15 Create New Data Source Dialog Box
4.
In the Oracle Retail RPAS ODBC Driver Setup window, enter the following
information:
■
■
■
Name and description of the ODBC data source.
In the Service Host field, enter the name of the server. If connecting to a
service running on a local host, enter localhost or the name of the local host
server. If the Agent service is running on a remote server, enter the name of the
remote host server.
In the Service Port field, enter the port number that the data service is listening
on.
This is the port number of the data service and not the Agent
service port number.
Note:
■
■
■
In the Service Data Source field, enter the name of the service data source that
has been configured for the data service. The default for this field is gdom.
If the data service is not SSL enabled, uncheck Encrypted(SSL). If the data
service is SSL enabled, check Encrypted(SSL).
Enter custom properties, if needed. Custom properties are entered in the
format of [name]=[value]. Multiple properties should be separated by a
semicolon. For example:
LANGUAGE=Japanese;WORKBOOK_SCHEMA=DOMAIN_T0
14-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Configuration
Table 14–1 lists the available custom properties (all optional):
Table 14–1
Available Custom Properties
Property Name
Description
LANGUAGE
Name of the language you use. The RPAS ODBC/JDBC driver
is multi-language enabled. If data is in any language other than
English, the LANGUAGE property should be set to the name
of that language. If multiple languages are used in the domain,
set this property to the name of the language other than
English. For example, if some position names are in English
and some are in Japanese, then LANGUAGE should be set to
Japanese.
The default is English.
WORKBOOK_SCHEMA
Name of the workbook you wish to connect to. If not set, the
driver connects to the domain.
SHORT_DATE_FORMAT
Valid short date format used in RPAS.
DEFAULT_SCHEMA
Default schema name if the table name in query is not
qualified. This property is set to DOMAIN by the default
configuration.
AGG_TABLE_NAMES
This property can be set to a list of valid aggregate table names
separated by commas. When this is set, the driver will present
the tables specified in the system tables. When this property is
not set, the valid aggregate tables can still be queried even
though they do not exist in the system tables.
NORMALIZE_DIM_TABLES Valid values are Yes and No. The default value is No.
If set to Yes, the dimension tables will only contain columns for
this dimension and its immediate parent dimension.
If set to No, the dimension tables will contain columns for this
dimension and all parent dimensions within the hierarchy.
Figure 14–16
Oracle Retail RPAS ODBC Driver Setup Dialog Box
RPAS ODBC/JDBC Driver
14-17
ODBC Configuration
5.
Click Test Connect. If the user security of the gdom Data source setting has been
set to DBMSLogon, the Logon to Data Source dialog is displayed. Enter the data
source user name and password configured for the data source.
Figure 14–17 Logon to Data Source Dialog Box
If the connection is successful, the following dialog box is displayed.
Figure 14–18 Oracle Retail RPAS ODBC Driver Setup Dialog Box for Successful
Connection
6.
Click OK.
14-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Starting the RPAS ODBC Server Process
Starting the RPAS ODBC Server Process
The RPAS ODBC Agent and Data Services should have automatically started after
successful completion of the server installation.
The RPAS ODBC Data Service should be stopped and restarted using the Management
Console.
1.
To stop a data service, right-click the service name and then click Stop in the
menu.
2.
Right-click RPAS_Data_Service and then click Start RPAS_Data_Service in the
menu.
Figure 14–19
Console Manager Window with Data Service Selected
Testing the Connection Using Interactive SQL
After the ODBC Server and ODBC Client have been configured, you can test the
connection using Interactive SQL. The RPAS ODBC Server process must be running.
1.
Select Start, All Programs, Oracle RPAS ODBC driver, and then Interactive SQL
(ODBC). The Interactive SQL command window appears.
2.
Enter 'connect <user name>*<password>@<dsn_name>' where <dsn_name> is the
name of the connection defined in the ODBC Server and ODBC Client
configuration. The following is an example.
'connect adm*adm@SampleRPAS'
If the configuration is defined correctly, no errors are displayed.
RPAS ODBC/JDBC Driver
14-19
ODBC Client Configuration for UNIX
ODBC Client Configuration for UNIX
Configuring the UNIX system to connect the ODBC drivers and a domain
environment consists of the following steps:
1.
Install the ODBC Server components. Refer to the RPAS Installation Guide.
2.
Install the ODBC Client components. Refer to the RPAS Installation Guide.
3.
Configure the ODBC Server components.
4.
Configure the ODBC Client components.
5.
Start the RPAS Data Service if it is not already started.
6.
Test the connection using Interactive SQL.
Client Configuration
Both 32-bit and 64-bit ODBC Clients are available. They are delivered in directories
named odbcclient32 and odbcclient64 respectively. The configuration steps are
identical for 32 and 64-bit ODBC Client.
For the remainder of this chapter, the 32 or 64-bit ODBC Client
are referred to as ODBC Client, and odbcclient32 or odbcclient64 are
referred to as odbcclient.
Note:
If it comes with RPAS, then odbcclient directory is under your $RPAS_HOME. If it
comes separately, the installer determines its location.
1.
Set up the environment for the ODBC Client.
If the ODBC client does not come with RPAS (meaning the odbcclient directory is
not under $RPAS_HOME), edit the oaodbc.sh file (oaodbc64.sh for 64-bit Client) in
odbcclient:
a.
Make sure the following environment variables are set correctly:
- LIBPATH and OASDK_ODBC_HOME are set to the full path of the lib
directory inside the odbcclient directory
- ODBCINI is set to the full path of the odbc.ini file (odbc64.ini for 64-bit
Client), including the file name, inside the odbcclient directory
b.
Source oaodbc.sh by running the following command in the odbcclient
directory:
. ./oaodbc.sh
2.
Create and configure the data sources in odbc.ini.
The odbc.ini file in the odbcclient directory has three sections: [ODBC], [ODBC
Data Sources], and [SampleRpas] which is a section for the sample RPAS data
source.
a.
Edit the [ODBC] section: Set TraceDll to the full path to lib/odbctrac.so and
InstallDir to the full path of the odbcclient directory.
b.
Edit the [ODBC Data Sources] section: Add an entry for the new data source
you are creating. The entry has the following format:
MyRPASDataSource= Oracle RPAS ODBC Driver
14-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
ODBC Client Configuration for UNIX
c.
Create a new [MyRPASDataSource] section: The [SampleRPAS] section can be
copied and modified. In the new [MyRPASDataSource] section:
- Set Driver to the full path of odbcclient/lib/ivoa22.so.
- Set Host to the name or IP address of the server.
- Set Port to the port number the RPAS_Data_Service listens at. This is not the
port number used by the RPAS ODBC Agent.
- ServerDataSource should be set to the name of the data source you created in
the server configuration. For [SampleRPAS], this entry is set to "gdom", since
that is the data source created on the server as an example. This is shown in
the following figure.
Figure 14–20
Console Manager Window with gdom Selected
Testing the Connection
After the ODBC Server and ODBC client have been configured, you can test the
connection using Interactive SQL. The RPAS ODBC Data Service must be started.
1.
In the odbcclient directory, source oaodbc.sh if you have not already done so.
2.
Change to the tools directory, run the executable odbcisql. Then at the ISQL
prompt, enter 'connect <user Name>*<password>@<DataSourceName>' where
<DataSourceName> is the name of the data source you defined in odbc.ini as
described in the previous section. The following is an example.
'connect adm*adm@MyRPASDataSource'
If the configuration is correctly defined, no errors are displayed.
RPAS ODBC/JDBC Driver
14-21
Installing and Using the RPAS JDBC Driver
Installing and Using the RPAS JDBC Driver
This section describes how to install, set up, and use the RPAS JDBC driver on all
UNIX/Linux and Windows platforms.
The RPAS JDBC driver is delivered in a single (zipped) jdbcclient directory. The user
has full control on the location of the jdbcclient directory. For installation guidelines,
refer to the RPAS Installation Guide.
After the JDBC driver is installed on your system, you need to update the
CLASSPATH environment variable. This variable ensures that the JDBC client can
access the appropriate Java classes needed to connect to the database.
Updating Environment Variables for the JDBC Driver on Windows
1.
Open System in the Control Panel. The System Properties window appears.
2.
On the Advanced tab, click Environment Variables. The Environment Variables
dialog appears.
Figure 14–21 Environment Variables Dialog Box
14-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Installing and Using the RPAS JDBC Driver
3.
Select the CLASSPATH from the System variables list and click Edit. The Edit
System Variable dialog box appears.
Figure 14–22
4.
Edit System Variable Dialog Box
Add the current working directory ".",driver_home/driver/lib/ORjc.jar,
driver_home/driver/ORssl14.jar, and driver_home/driver/ iaik_jce_full.jar to the
CLASSPATH environment variable and click OK.
Where driver_home is the location where the jdbcclient was installed. If your
jdbcclient was installed in C:/jdbcclient, you would have the following in your
CLASSPATH:
.;C:/jdbcclient/driver/lib/ORjc.jar; C:/jdbcclient/driver/lib/ORssl14.jar; C:/
jdbcclient/driver/lib/iaik_jce_full.jar
Note:
5.
Separate paths with semi-colons (;).
After updating the environment variable, restart your PC.
After you have updated the environment variables and restarted your PC, you are
ready to use the RPAS JDBC driver with any JDBC client.
Updating Environment Variables for JDBC Driver on UNIX/Linux
On UNIX/Linux systems, use "export" (or "set", depending what shell you use) to add
the following to your CLASSPATH:
export CLASSPATH=.:jdbc_home/driver/lib/ORjc.jar: jdbc_home/driver/lib/
ORssl14.jar: jdbc_home/driver/lib/iaik_jce_full.jar:$CLASSPATH
where jdbc_home is the full path of the directory where jdbcclient is installed. If you
installed jdbcclient at /usr/products/oracle, then you should replace jdbc_home with
/usr/products/oracle/jdbcclient.
The above export command can be added to your .profile.
Using the RPAS JDBC Driver
Any JDBC client needs the following information to use a JDBC driver to connect to a
database:
■
■
A driver class
A URL to the database specified in a form that the particular JDBC driver
understands
RPAS ODBC/JDBC Driver
14-23
Installing and Using the RPAS JDBC Driver
For the RPAS JDBC driver, this information is specified as follows:
■
Driver Class: com.oracle.ard.jdbc.openaccess.OpenAccessDriver
■
URL: "jdbc:RPAS://<host>:<port>;ServerDataSource=<DataSourceName>"
<host> is the name or IP address of the server, <port> is the port number the RPAS
Data Service listens at, and <DataSourceName> is the name of data source you created
for the RPAS Data Server (it is "gdom" in the default configuration).
Enabling Spy for RPAS JDBC Driver
Spy is a logging facility for JDBC driver. To enable spy for the RPAS JDBC connection:
1.
Add jdbc_home/spy/lib/ORy.jar to your CLASSPATH where jdbc_home is the
installation directory of jdbcclient.
2.
Set your driver class to com.oracle.ard.jdbcspy.SpyDriver.
3.
Use the following URL:
"jdbc:spy:{jdbc:RPAS://
<host>:<port>;ServerDataSource=<DataSourceName>};load=com.oracle.ard.jdbc.
openaccess.OpenAccessDriver;[key=value];…"
<host> is the name or IP address of the server, <port> is the port number the RPAS
Data Service listens at, and <DataSourceName> is the name of data source you
created for the RPAS Data Server (it is "gdom" in the default configuration). The
key and value pairs are the attributes of the Spy class.
Table 14–2 lists the available attributes:
Table 14–2
Attributes Available
Key and Value
Description
log=System.out
Redirects logging to the Java output standard, System.out.
log=(file)filename
Redirects logging to the file specified by filename. For example,
C:\temp\spy.log
linelimit=numberofchars
The maximum number of characters, specified by numberofchars,
that Spy will log on one line.
When set to no (default), there is no maximum limit on the number
of characters.
logLobs={yes | no}
Specifies whether Spy logs activity on Blob / Clob. The initial
default is no.
logIS={yes | no |
nosingleread}
Specifies whether Spy logs activity on InputStreams.
When logIS=nosingleread, logging on InputStream and Reader
objects is active; however, logging of the single-byte read
InputStream.read or single-character Reader.read is suppressed to
prevent generating large log files that contain single-byte or single
character read messages.
When set to no (default), Spy does not log activity on InputStreams.
logTName={yes | no}
Specifies whether Spy logs the name of the current thread.
When set to no (default), Spy does not log the name of the current
thread.
timestamp={yes | no}
Specifies whether a timestamp should be included on each line of
the Spy log.
When set to no (default), Spy does not include a timestamp on each
line.
14-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Installing and Using the RPAS JDBC Driver
Using the jdbcisql Utility Provided with RPAS JDBC Driver
Oracle Retail suggests that you use the jdbcisql.bat (for Windows) or jdbcisql.sh (for
UNIX/Linux) located in jdbcclient/isql to start jdbcisql. Edit jdbcisql.bat or jdbcisql.sh
to make sure it uses the appropriate URL (the argument of -u option):
java jdbcisql -d com.oracle.ard.jdbc.openaccess.OpenAccessDriver -u "jdbc:RPAS://
<host>:<port>;ServerDataSource=gdom"
The value of the ServerDataSource setting in the URL is casesensitive on Windows and UNIX systems and has to match the "Data
source setting" defined for the data service.
Note:
When the application starts, enter the following to log in and make the connection
(user name = adm; password = adm) as shown below.
Connect adm*adm@
To enable Spy for jdbcisql, use a command line similar to the following:
java jdbcisql -d com.oracle.ard.jdbcspy.SpyDriver -u "jdbc:spy:{jdbc:RPAS:// ://
<host>:<port>;;ServerDataSource=gdom};load=com.oracle.ard.jdbc.openaccess.OpenAcce
ssDriver;log=(file)C:\temp\spy.log;logIS=yes;logTName=yes;timestamp=yes"
Using Oracle SQL Developer
Create an XML file with the following content:
<?xml version = '1.0'?>
<!DOCTYPE connections>
<connections>
<connection>
<URL>"jdbc:RPAS://<host>:<port>;ServerDataSource=<DataSourceName>"</URL>
<ConnectionName>MyConnection</ConnectionName>
<user>adm</user>
<ConnectionType>OTHER_JDBC</ConnectionType>
<JdbcDriver>com.oracle.ard.jdbc.openaccess.OpenAccessDriver</JdbcDriver>
</connection>
</connections>
■
■
■
■
The URL should correspond to the URL specification required by the RPAS JDBC
Driver as specified in the preceding sections.
ConnectionName can be anything you like. This field can be changed later using
the client application.
Enter a user name for the connection. This field can also be changed later using the
application.
Leave the remaining information as shown in the code sample above.
RPAS ODBC/JDBC Driver
14-25
Installing and Using the RPAS JDBC Driver
To set up the connection:
1.
Save this XML file with any name you like.
2.
In SQL Developer, using the Tools/Preferences/Database/Third Party Drivers,
add the ORjc.jar, Orssl14.jar, and iaik_jce_full.jar files to the list of third party
drivers used by SQL Developer (SQL Developer does not look in the classpath for
drivers).
3.
Go to the Connection Navigator and right-click on Connections. Select Import
Connections.
4.
Browse to the XML file. The dialog displays the list of connections you specified in
the file. Choose your connection, in the sample code, MyConnection.
Using Oracle JDeveloper
Perform the following procedure to use Oracle JDeveloper with the JDBC driver:
1.
Start JDeveloper.
2.
From the JDeveloper left panel, select the Connections tab.
3.
Right-click on Databases, and select New Database Connection. The Create New
Database Connection wizard appears.
4.
On the first screen of the Create New Database Connection wizard, enter a
connection name, and choose Third Party JDBC driver for Connection Type.
5.
On the second screen, enter the user name and password, and then click Next.
6.
On the third screen, perform the following:
7.
a.
Click New to add the driver.
b.
Locate the library ORjc.jar, Orssl14.jar, and iaik_jce_full.jar files and their path.
These jar files are available from the installation of the RPAS JDBC Client.
c.
Enter the RPAS JDBC Driver connection URL as specified at the beginning of
this section.
d.
In the Driver Class field, enter
com.oracle.ard.jdbc.openaccess.OpenAccessDriver.
Follow the instructions to finish creating the connection.
Using a Java Program
You can instantiate oadriver in your application by one of following methods:
■
■
new oadriver();
Class.forName
("com.oracle.ard.jdbc.openaccess.OpenAccessDriver").newInstance();
Make sure driver_home/driver/lib/ORjc.jar, driver_home/driver/lib/Orssl14.jar, and
driver_home/driver/lib/iaik_jce_full.jar are included in the CLASSPATH.
The Java code snippet below shows you how you can write a program that uses the
driver.
14-26 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Installing and Using the RPAS JDBC Driver
Java Code Sample:
import java.sql.*;
public class RPASDriverTest {
public RPASDriverTest() {}
public static void main(String[] args)
{
try
{
if (args.length != 3)
{
System.out.println("Format:\n" +
"java RPASDriverTest <Database> <UID> <PWD>\n");
return;
}
Connection conn = null;
Driver d =
(Driver)Class.forName("com.oracle.ard.jdbc.openaccess.OpenAccessDriver").newInstan
ce();
String url = "jdbc:RPAS://";
String database = args[0];
String uid = args[1];
String pwd = args[2];
url += database;
System.out.println("Trying to connect to url: " + url );
conn = DriverManager.getConnection(url, uid, pwd);
DatabaseMetaData dma = conn.getMetaData();
System.out.println("\nConnected to " + dma.getURL());
System.out.println("Driver " +
dma.getDriverName());
System.out.println("Version " +
dma.getDriverVersion());
System.out.println("");
// sample query
String query = "SELECT * FROM DIM_YEAR";
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(query);
rs.close();
stmt.close();
}
catch (SQLException ex)
{
System.out.println ("\n*** SQLException caught ***\n");
while (ex != null) {
System.out.println ("SQLState: " + ex.getSQLState ());
System.out.println ("Message: " + ex.getMessage ());
System.out.println ("Vendor: " +
ex.getErrorCode ());
ex = ex.getNextException ();
System.out.println ("");
}
}
catch (java.lang.Exception ex)
{
//Got some other type of exception. Dump it.
ex.printStackTrace ();
}
}
}
RPAS ODBC/JDBC Driver
14-27
Data Query
Running the Program
After compilation, run the program as:
java RPASDriverTest.class "<host>:<port>;ServerDataSource=<DSN>" <uid> <pwd>
Where <host> is the IP of the server box where RPAS ODBC Server is running and
where <port> is port number of the ODBC Server. <DSN> is the data source name
that is created on the server. Please note the double quotes must be included due to the
semicolon.
Data Query
This section provides the details of data query, including the limitations, metadata,
and dimension tables.
Limitations
It is important to note the following limitations when performing data queries.
Contention
Workbook commit requests issued by RPAS users compete with real-time intra-day
reports (ODBC queries) on accessing the domain data. Commit requests imply 'write'
locks on certain measures in the domain. While such 'write' locks are in place,
reporting tools cannot access the same data. In such situations both reporting and
workbook users can experience latencies or, in more sever scenarios, they can
encounter system feedback informing them that their last operation did not succeed
and they need to re-execute their last request. The likelihood of such concurrency
issues depends on a number of factors such as hardware capabilities (CPU and IO
capacity), reporting volume, reporting granularity, number of reporting users, number
of workbook users, and the commit data volume. To minimize the chance of such
concurrency issues, all workbook commits should leverage the commit ASAP
framework. Additionally, RPAS allows reporting from workbooks which is less prone
to concurrency issues that may be experienced while reporting from domains.
Workbook Queries
All workbook queries must be performed against saved workbooks. The workbook
can be open or closed. The user must save the workbook before reporting.
14-28 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Data Query
Metadata
The following figure shows the metadata tables available in a domain or workbook.
These tables can be used to examine the structure of the domain, such as:
■
Which measures and dimensions exist within the database
■
Which hierarchies exist and what is their rollup structure
■
Which fact tables are available
■
Which measures exist at the intersections that they represent
When connected to a domain, an additional table (MD_WORKBOOK_SCHEMAS) is
available to list all accessible workbooks within the domain with their schema names.
Figure 14–23 Database Diagram for All Metadata Tables in a Domain or in Each Workbook
The MD_WORKBOOK_SCHEMAS table is not included in
workbooks.
Note:
RPAS ODBC/JDBC Driver
14-29
Data Query
Fact and Dimension Tables
The following figure shows an example of the structure of fact and dimension tables
and the relationships between them. A fact table represents an intersection where one
or more measures' data is stored. Each measure is represented by a column in the
table. Additionally, each dimension on the intersection is represented by a column. A
record in the fact table is uniquely identified by a unique combination of position
names for the intersecting dimensions.
A dimension table represents a dimension. It includes a column to list all position
names, their labels, and their rollup mapping to each dimension at higher levels in the
hierarchy.
The fact and dimension tables have foreign key relationships between them to
represent the intersection and maintain data integrity between the dimensions and the
facts. Dimension tables have foreign key relationships with other dimension tables to
represent the hierarchical relationships between them.
Figure 14–24 Example of Star - Denormalized Schema to Represent Facts and Dimensions in RPAS
At connection time, all intersections at which any measure is stored at its base level are
available as fact tables within the database. Additional aggregate level intersections
may be made available in the database by specifying them in a custom connection
property. These fact tables are a part of the set of database entities that will be visible to
reporting tools at connection time.
14-30 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Measure Security in the ODBC Driver
However, the RPAS ODBC/JDBC driver supports dynamic aggregate level fact tables
that can be queried even though they are not available at connection time. These tables
include all intersections that are logically above the base intersection fact tables and
have at least one measure in them when manifested. If the measure existence condition
is not met, the driver returns an error that the fact table could not be found.
These dynamic fact tables are queried in the same fashion as the tables that are
available at connection time. The name of the fact table can be constructed by piecing
together dimension names (not labels) that make up the intersection in the order in
which they would exist within the domain. For example, if someone wants to query
facts at the store/class/day level but the fact table is not available at connection time,
they can construct the fact table name as: FACT_STR_CLSSDAY_. Note that dimension
names have been concatenated in the same order as the intersection and have been
prefixed with 'FACT_'. Also, note that a dimension name is assumed to be four
characters long and if the dimension name is less than four characters, it is padded
with '_' characters to make it four characters long.
For information on limitations when performing queries, see the Limitations section.
Measure Security in the ODBC Driver
Before the existence of the ODBC/JDBC driver, an RPAS user could only use RPAS
workbooks to access measures. Consequently, the ODBC/JDBC driver emulates the
RPAS workbook security model to manage access rights to RPAS measures. It allows
users to view all measures that they could view using the templates to which they
have access.
This means that when users connect to a domain, they can see all the measures that
they could insert into a workbook. These include all measures that their templates
have access rights to (managed through the use of the Workbook Template Measure
Rights worksheet in the Security Administration workbook) and all measures to which
the users have explicitly been given access rights using the Measure Rights worksheet
in the Security Administration workbook. All other measures are not accessible to the
users.
When users connect to a workbook, they can access all measures in the workbook,
irrespective of how those measures were brought into the workbook and irrespective
of whether access rights to some of those measures were removed after the workbook
was created. Since those measures exist in the workbook that the users can access,
those measures (their workbook copies) are accessible to the users.
RPAS ODBC/JDBC Driver
14-31
Use Cases
Use Cases
This section describes some use cases of RPAS.
Using Metadata Tables to Explore the Structure of a Domain or a Workbook
1.
Fetch the list of workbook schema names. In this example, the workbook is owned
by 'USER01', built using the template 'TestTemplate', and labeled 'MyWorkbook'.
Select
SCHEMA_NAME, CREATION_TIME, MODIFICATION_TIME
From
MD_WORKBOOK_SCHEMAS
Where
OWNER_NAME = 'USER01' and
WORKBOOK_LABEL = 'MyWorkbook' and
WORKBOOK_TEMPLATE = 'TestTemplate'
The SCHEMA_NAME obtained using this query can be directly used in the custom
properties of the driver configuration to enable direct connection to a workbook
instead of a domain.
2.
List all measures in the domain or workbook (default schema).
Select
*
From
MD_MEASURES
3.
List all measures in a specific schema (for example, 'DOMAIN_T0').
Select
*
From
DOMAIN_T0.MD_MEASURES
4.
List all dimensions in the domain or workbook (default schema).
Select
*
From
MD_DIMENSIONS
5.
List all fact tables in the domain or workbook (default schema).
Select
*
From
MD_FACT_TABLES
6.
List all hierarchies in the domain or workbook (default schema).
Select
*
From
MD_HIERARCHIES
14-32 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Use Cases
7.
List all fact tables with the measures that are represented in those tables (default
schema).
Select
*
From
MD_TABLE_MEASURES
List all fact tables with the dimension table names that intersect in the fact table
(default schema).
Select
*
From
MD_TABLE_INTERSECTIONS
8.
To understand the structure of a particular hierarchy (for example: CLND) the
following table will list the hierarchy with each of its dimensions and the roll up
dimension name for each one of them (default schema).
Select
*
From
MD_HIERARCHY_SPECS
Where
HIERARCHY_NAME = 'CLND'
Querying Fact Data
1.
Query fact data for all measures at the STR-SKU-DAY intersection with the unique
position names for these dimensions.
Select
*
From
FACT_STR_SKU_DAY_
2.
Query fact data for specific measures at the STR-SKU-DAY intersection and list
them with the position labels for each dimension.
Select
DS.POSITION_LABEL, DU.POSITION_LABEL, DD.POSITION_LABEL, R_EX_LBLOWINTR,
R_EX_UBLOWINTR
From
FACT_STR_SKU_DAY_ F,
DIM_STR DS,
DIM_SKU DU,
DIM_DAY DD
Where
DS.POSITION_NAME = F.STR and
DU.POSITION_NAME = F.SKU and
DD.POSITION_NAME = F.DAY
Hint Join (FACT_STR_SKU_DAY_, DIM_STR, DIM_SKU, DIM_DAY);
The optional "Hint" clause in the above SQL statement is not
ANSI SQL standard, but the ODBC/JDBC Driver supports it. This
"Hint" tells the driver to process the join tables in the specified order
(fact table first, and then dimension tables).
Note:
RPAS ODBC/JDBC Driver
14-33
Clients
Connecting to a Workbook
1.
Select Start, Settings, Control Panel, Administrative Tools, and then Data
Sources (ODBC).
2.
Select the System DSN tab. Select the appropriate DSN and click Configure.
3.
In the Options frame, enter WORKBOOK_SCHEMA=<workbook schema name>.
Replace '<workbook schema name>' with the workbook schema name for the
workbook to which you want to connect. The workbook schema names can be
obtained by first connecting to the domain and then examining the
MD_WORKBOOK_SCHEMAS table to obtain the schema name for the
appropriate workbook (may be identified by owner name, template, creation and
last modification time). For example: 'WORKBOOK_SCHEMA=DOMAIN_T0' or
'WORKBOOK_SCHEMA=SD0_T0'
4.
Click OK.
Requesting Additional Aggregate Tables
1.
Select Start, Settings, Control Panel, Administrative Tools, and then Data
Sources (ODBC).
2.
Select the System DSN tab. Select the appropriate DSN and click Configure.
3.
In the Options frame, enter AGG_TABLE_NAMES=<comma-separated list of any
additional aggregate fact table names>.
By default, the database includes every fact table (a fact table represents an
intersection) that one or more measures have as their base intersection. Any other
fact tables can be specifically requested by adding a comma-separated list as the
value for this custom property. For example, to see a fact table for the intersections
'DEPT' and 'DEPT_YEAR', the value of this custom property would be
'AGG_TABLE_NAMES=FACT_DEPT, FACT_DEPT_YEAR'.
4.
Click OK.
If entering more than one connection property (that is, both the
WORKBOOK_SCHEMA and AGG_TABLE_NAMES properties), the property key
value pairs must be separated by a semicolon. Using examples above, the content
of the custom properties input box would appear as follows:
WORKBOOK_SCHEMA=DOMAIN_T0;AGG_TABLE_NAMES= FACT_DEPT,
FACT_DEPT_YEAR
Clients
This section lists some sample ODBC/JDBC client applications that can connect to the
RPAS datastore through the RPAS ODBC/JDBC Driver. The examples in this section
do not include all client applications that can connect to the RPAS ODBC/JDBC
Driver.
Note: In client/server configuration, the server (executable) must be
started before a client can connect to it.
14-34 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Clients
Oracle Business Intelligence Enterprise Edition (OBIEE)
This section outlines how to connect to the defined DSN using the OBIEE
Administration Tool and how to import data from the DSN. For more information
about OBIEE, refer to OBIEE documentation. The user must install and configure the
ODBC client first on the OBIEE server host (refer to section ODBC Client
Configuration for UNIX) and test the connection. The ODBC client and the OBIEE
server must both be 32-bit or 64-bit. The administrator must source the oaodbc.sh or
oaodbc64.sh script under the ODBC client home directory before (re)starting the
OBIEE server.
Configuring the ODBC Client for OBIEE
The following example provides a sample of configuring the ODBC client for OBIEE.
This example was developed for OBIEE on AIX, but the process is the same for other
environments.
1.
Open the $BIEE_HOME/setup/odbc.ini file where $BIEE_HOME is the directory
where OBIEE is installed.
2.
Set the TraceDll to the odbctrac.so that comes with RPAS odbcclient. Set InstallDir
to the RPAS odbcclient installation directory.
3.
In the [ODBC Data Sources] section, insert an entry for RPAS domain.
Example:
rpas_domain=This is the name of the data source for RPAS.
The name here (rpas_domain) should be the same as the data source name
configured in the RPAS ODBC Server.
4.
Create a section in the file for the rpas_domain. The following example is subject
to changes. Refer to the [SampleRPAS] section in odbc.ini or odbc64.ini under
ODBC client home directory for all up-to-date settings.
Example:
[rpas_domain]
Driver= absolute_path_to_odbc_client/lib[64]/ivoa22.so
Description=Oracle Retail RPAS ODBC Driver
Host=<RPAS ODBC Server host>
Port=<odbc_data_service_port>
ServerDataSource=<data_source_name>
UseLDAP=0
DistinguishedName=
Encrypted=0
LoadBalancing=0
AlternateServers=
ConnectionRetryCount=0
ConnectionRetryDelay=3
CustomProperties=
Save your changes to the file.
RPAS ODBC/JDBC Driver
14-35
Clients
Connecting OBIEE to an RPAS Domain
To connect OBIEE to a predefined DSN for an RPAS Domain:
1.
Make sure the following Windows services are running:
■
Oracle BI Java Host
■
Oracle BI Server
2.
Start the OBIEE Administration Tool. Select Start, All Programs, Oracle Business
Intelligence, and then Administration.
3.
From the File menu, select open - online. A window appears to enter login
credentials.
4.
Enter the administrator's user name and password, and then click open.
Three panels now appear in the Admin Tool window: Presentation, Business
Model and Mapping, and Physical.
5.
From File menu, select Import-From database. A window appears to select the
connection type and RPAS user information.
6.
Select ODBC 3.5 for Connection Type, choose the appropriate DNS for the RPAS
domain, enter the RPAS user name and password, and then click OK.
The RPAS schemas and tables appear in a new window.
7.
Select the objects you want to import, and then click import. After the import is
complete, click Close.
A new physical model is created and listed in the Physical panel of the Admin
Tool window.
8.
Expand the physical model. Double-click on connection to open "connection"
properties. Make sure the Connection Type is set to ODBC 3.5. Click OK to exit.
9.
In the Admin Tool window, click Save to save your physical model.
Now that you have a basic physical model, you can build the business model and
presentation layer on top of it. For more information on the business model,
presentation layer, and OBIEE Web interface, refer to OBIEE documentation.
Microsoft Access
To connect using Microsoft Access:
1.
Start Microsoft Access.
2.
Create a new (or open an existing) Access file (.mdb file).
3.
From the File menu, select Get External Data- Link Tables (or Import if you want
to import the data from RPAS datastore to Access). A dialog box appears.
4.
In the Files of type box, select ODBC Databases().
5.
Click the Machine Data Source tab, and then double-click the pre-configured
ODBC data source from which you want to link.
6.
At the logon prompt, enter your user ID and password, and then click OK.
At this point, MS Access connects to the RPAS data source and displays the list of
schemas/tables that you can import or link.
14-36 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Clients
7.
Click each table that you want to import or link, and then click OK. If you are
linking a table that does not have an index that uniquely identifies each record,
then Microsoft Access displays a list of the fields in the linked table. Select a field,
or a combination of fields, that will uniquely identify each record, and then click
OK.
JDeveloper
JDeveloper works best with a native JDBC driver, which is included in the RPAS
ODBC/JDBC Driver package.
To connect using JDeveloper:
1.
Start JDeveloper.
2.
On the JDeveloper left panel, select the Connections tab.
3.
Right-click on Databases, and select New Database Connection.
4.
On the first screen of the Create New Database Connection wizard, enter a
connection name and select Third Party JDBC driver for Connection Type.
5.
On the second screen, enter the user name and password, and then click Next.
6.
On the third screen, click New to add the driver. It opens up the following dialog.
You need to find the jar files ORjc.jar, ORssl14.jar, iaik_jce_full.jar, and ORy.jar and
their paths (they are made available from the installation of the JDBC Driver).
Then, create a library group "RPAS JDBC Driver" with those four jar files.
In the Driver Class field, entercom.oracle.ard.jdbc.openaccess.OpenAccessDriver.
Then enter in the URL field: jdbc:RPAS://
{host_name}:{port_number};ServerDataSource={data_source_name} , where
host_name is the host name or IP address of the ODBC server, port_number is the
RPAS_Data_Service port number and data_source_name is the Data Source Name
which is configured on the ODBC server.
Figure 14–25
7.
Register JDBC Driver Dialog Box
Follow the instructions to finish creating the connection.
After the connection is established, a user can expand the Connection (and the
nodes under the Connection) to browse the objects in the RPAS datastore. A user
can also open a SQL worksheet (by selecting SQL Worksheet from the Tools
menu) to write/execute SQL statements.
RPAS ODBC/JDBC Driver
14-37
Clients
XML Publisher
This section describes how to make the connection from XML Publisher to RPAS using
JDBC driver (XML only supports JDBC).
1.
Install and configure the JDBC client driver and ODBC/JDBC server. Start the
server.
2.
Copy the JDBC client jar files ORjc.jar, ORssl14.jar, iaik_jce_full.jar, and ORy.jar
(from JDBC client installation) to D:\OraHome_1\oc4j\j2ee\home\applib, where
D:\OraHome_1 is the root directory where XML Publisher was installed.
3.
Start the XML Publisher server (Select Start, All Programs, Oracle XML Publisher
Server, OUIHome1, and then Oracle XML Publisher Enterprise Start).
4.
Start a Web browser and go to the URL: http://localhost:15101/xmlpserver/
This URL is only an example. Contact the XML Publisher administrator/installer
for the actual URL. The actual URL is recorded in
D:\OraHome_1\xmlpserver\setupinfo.txt file of the XML Publisher server
machine.
5.
Log in as admin/admin.
6.
Select the Admin tab and then select JDBC Connection under Data Sources to
create a JDBC connection.
7.
Click Add Connection to create a new connection and provide the following
information:
■
■
■
■
Enter a display name for Data Source Name.
Enter jdbc:RPAS://
{host_name}:{port_number};ServerDataSource={data_source_name} for the
URL, where host_name is the host name or IP address of the ODBC server,
port_number is the RPAS_Data_Service port number and data_source_name
is the Data Source Name which is configured on the ODBC server.
Enter adm for user name and password.
Enter "com.oracle.ard.jdbc.openaccess.OpenAccessDriver" for Database
Driver Class.
8.
Click Test Connection. The confirmation message: "connect established
successfully" should appear.
9.
Click Apply to save the connection.
14-38 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Interactive SQL (ISQL) Utility
ISQL is an interactive SQL tool that is provided by the ODBC/JDBC SDK.
To connect to remote ODBC/JDBC server, use odbcisql.exe (with ODBC client
installed) or jdbcisql.class (with JDBC client installed).
Note:
Users are expected to know basic SQL to use ISQL.
To connect to the ODBC/JDBC server using odbcisql, start odbcisql and then, at the
SQL prompt, issue the connect command as follows:
connect john/doe@rpasDomain
Where john/doe is a predefined administrator account in RPAS, and rpasDomain is a
pre-configured Data Source Name.
Issue the connect command for jdbcisql.class as follows:
connect john*doe@rpasDomain
After you are connected to the server, you can issue various SQL DML and DDL
statements to inspect and modify the data in the RPAS datastore.
Supported and Unsupported SQL Functions
This section contains the following information:
■
Detailed descriptions of various functions supported by the RPAS ODBC Driver.
■
Descriptions of the SQL92 and SQL99 functionalities that are not supported.
Supported SQL Functions
Use extreme caution when applying functions to any dimension name or label
columns, because the driver is not able to use the corresponding internal indexes to
optimize row selection when functions are applied to those columns (which could be a
significant performance hit).
It is suggested that users avoid applying functions to dimension name or label
columns, whenever possible.
Consider the following query:
Select * from fact_str_sku_day
where convert(day, SQL_DATE) = curdate();
Even though this query selects the data for only one day, the driver has to scan the
entire fact table, and then apply the convert function to every row of the table.
Working with OBIEE, the same can be achieved using a variable, which holds the
converted string value of the current date (in the same format as the "day" column).
The query then becomes:
Select * from fact_str_sku_day
Where day = @curDateString;
The driver only reads the rows that meet the condition.
RPAS ODBC/JDBC Driver
14-39
Supported and Unsupported SQL Functions
Numeric Functions
Table 14–3
Numeric Functions
Function
Description
ABS(numeric_exp)
Returns the absolute value of numeric_exp. For example:
SELECT ABS(-1.0), ABS(0.0), ABS(1.0) FROM emp WHERE
empno = 1;
This returns 3 result columns with values 1, 0, and 1.
ACOS(float_exp)
Returns the arccosine of float_exp as an angle, expressed in
radians. For example:
SELECT ACOS(-1) FROM emp WHERE empno = 1;
This returns 3.14159.
ASIN(float_exp)
Returns the arcsine of float_exp as an angle, expressed in
radians. For example:
SELECT ASIN(-1.0) FROM emp WHERE empno = 1;
This returns -1.57079.
ATAN(float_exp)
Returns the arctangent of float_exp as an angle, expressed in
radians. For example:
SELECT ATAN(45.0) FROM emp WHERE empno = 1;
This returns 1.54857.
ATAN2(float_exp1,
float_exp2)
Returns the arctangent of the x and y coordinates, specified by
float_exp1 and float_exp2, respectively, as an angle, expressed in
radians. For example:
SELECT ATAN2(35.175, 129.44) FROM emp WHERE empno = 1;
This returns 0.2653399.
CEILING(numeric_exp)
Returns the smallest integer greater than or equal to
numeric_exp. The return value is of the same data type as the
input parameter. For example:
SELECT CEILING(123.45), CEILING(-123.45), CEILING(0.0)
FROM
emp WHERE empno = 1;
This returns 124, -123 and 0.
COS(float_exp)
Returns the cosine of float_exp, where float_exp is an angle
expressed in radians. For example:
SELECT COS(14.78) FROM emp WHERE empno = 1;
This returns -0.59946542.
COT(float_exp)
Returns the cotangent of float_exp, where float_exp is an angle
expressed in radians. For example:
SELECT COT(124.78) FROM emp WHERE empno = 1;
This returns -0.82045588.
DEGREES(numeric_exp)
Returns the number of degrees converted from numeric_exp
radians. For example:
SELECT DEGREES(3.143) FROM emp WHERE empno = 1;
This returns 180.0806.
EXP(float_exp)
Returns the exponential value of float_exp. For example:
SELECT EXP(378.615) FROM emp WHERE empno = 1;
This returns 2.69404760606322E+164
14-40 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Table 14–3 (Cont.) Numeric Functions
Function
Description
FLOOR(numeric_exp)
Returns the largest integer less than or equal to numeric_exp. The
return value is of the same data type as the input parameter. For
example:
SELECT FLOOR(123.45), FLOOR(-123.45) FROM emp WHERE
empno = 1;
This returns 123 and -124.
LOG(float_exp)
Returns the natural logarithm of float_exp. For example:
SELECT LOG(5.175643) FROM emp WHERE empno = 1;
This returns 1.64396358.
LOG10(float_exp)
Returns the base 10 logarithm of float_exp. For example:
SELECT LOG10(145.175643) FROM emp WHERE empno = 1;
This returns 2.161893758.
SELECT LOG10(0), LOG10(-1), LOG10(1) FROM emp WHERE
empno =
1;
This returns -1.#INF, -1.#IND and 0
MOD(integer_exp1,
integer_exp2)
Returns the remainder (modulus) of integer_exp1 divided by
integer_exp2. For example:
SELECT mod(empno, 2) FROM emp WHERE empno = 11;
This returns 1.
PI( )
Returns the constant value of pi as a floating-point value. For
example:
SELECT PI() FROM emp WHERE empno = 1;
This returns 3.14159265358979.
POWER(numeric_exp,
integer_exp)
Returns the value of numeric_exp to the power of integer_exp. For
example:
SELECT POWER(2, -5), POWER(2, 5) FROM emp WHERE
empno = 1;
This returns 0, 32.
RADIANS(numeric_exp)
Returns the number of radians converted from numeric_exp
degrees. For example:
SELECT RADIANS(45.0) FROM emp WHERE empno = 1;
This returns 0.785398.
RAND([integer_exp])
Returns a random floating-point value using integer_exp as the
optional seed value. For example:
SELECT RAND(0) FROM emp WHERE empno = 1;
This returns 38.
RPAS ODBC/JDBC Driver
14-41
Supported and Unsupported SQL Functions
Table 14–3 (Cont.) Numeric Functions
Function
Description
ROUND(numeric_exp,
integer_exp)
Returns numeric_exp rounded to integer_exp places right of the
decimal point. If integer_exp is negative, numeric_exp is rounded
to |integer_exp| places to the left of the decimal point. For
example:
SELECT ROUND(123.344, 2), ROUND(123.345, 2) FROM emp
WHERE
empno = 1;
This returns 123.34 and 123.35.
SELECT ROUND(748.58, -1), ROUND(748.58, -2),
ROUND(748.58,
3), FROM emp WHERE empno = 1;
This returns 750, 700 and 1000.
SIGN(numeric_exp)
Returns the positive (+1), zero (0), or negative (-1) sign of the
given expression. For example:
SELECT SIGN(empno) FROM emp WHERE empno = 11;
This returns 1.
SELECT SIGN(-1 * empno), SIGN(0) FROM emp WHERE
empno = 1;
This returns two result columns with values -1 and 0.
SIN(float_exp)
Returns the sine of float_exp, where float_exp is an angle
expressed in radians. For example:
SELECT SIN(1.570796) FROM emp WHERE empno = 11;
This returns 0.999999.
SQRT(float_exp)
Returns the square root of float_exp. For example:
SELECT SQRT(45.35) FROM emp WHERE empno = 11;
This returns 6.7342.
TAN(float_exp)
Returns the tangent of float_exp, where float_exp is an angle
expressed in radians. For example:
SELECT TAN(0.785398) FROM emp WHERE empno = 11;
This returns 0.999999.
TRUNCATE(numeric_exp,
integer_exp)
Returns numeric_exp truncated to integer_exp places right of the
decimal point. If integer_exp is negative, numeric_exp is truncated
to |integer_exp| places to the left of the decimal point.
NCHAR(code)
Returns the Unicode character that has the specified code as a
SQL_WCHAR value. The valued of code should be between 0
and 65535. Example: "SELECT NCHAR(945)" returns the
character α.
String Functions
Table 14–4
String Functions
Function
Description
ASCII(string_exp)
Returns the ASCII code value of the leftmost character of
string_exp as an integer. For example:
SELECT ASCII(ename) FROM emp WHERE ename = 'Adam';
This returns 65 which is the ASCII code of A.
14-42 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Table 14–4 (Cont.) String Functions
Function
Description
BIT_LENGTH(string_exp)
Returns the length in bits of the string expression. For example:
SELECT BIT_LENGTH(ename) FROM emp WHERE ename =
'John';
This returns 32, which is the number of bits.
CHAR(code)
Returns the character that has the ASCII code value specified by
code. The value of code should be between 0 and 255; otherwise,
the return value is data source-dependent. For example:
SELECT CHAR(65) FROM emp;
This returns A which is the character for ASCII code A.
CHAR_LENGTH(string_exp Returns the length in characters of the string expression, if the
)
string expression is of a character data type; otherwise, returns
the length in bytes of the string expression (the smallest integer
CHARACTER_LENGTH(str
not less than the number of bits divided by 8). (This function is
ing_exp)
the same as the CHARACTER_LENGTH function.) For example:
SELECT CHAR_LENGTH(ename) FROM emp where ename =
'John';
This returns 4.
CONCAT(string_exp1,
string_exp2)
Returns a character string that is the result of concatenating
string_exp2 to string_exp1. If either of string_exp1 or
string_exp2 is NULL value, it returns NULL string.
If either of string_exp1 or string_exp2 is wide character string,
the return value is a wide character string. For example:
SELECT CONCAT('Name is: ', ename) FROM emp WHERE
ename =
'John';
This returns 'Name is: John'
SELECT CONCAT(N'Name is: ', ename) FROM emp WHERE
ename
= N'John';
This returns wide character string N'Name is: John'.
INSERT(string_exp1, start,
length, string_exp2)
Returns a character string where length characters have been
deleted from string_exp1, beginning at start, and where
string_exp2 has been inserted into string_exp, beginning at start.
If string_exp1 is wide character string, the return value is a wide
character string. Offsets (start and length) must be specified in
number of characters. For example:
SELECT INSERT(ename, 1, 0, 'Name is: ') FROM emp WHERE
ename = 'John';
This returns 'Name is: John'
SELECT INSERT(ename, 1, 0, N'Name is: ') FROM emp WHERE
ename = N'John';
If ename is a column of wide character data type, this returns
wide character string: N'Name is: John'.
LCASE(string_exp)
LOWER(string_exp)
Returns a string equal to that in string_exp, with all uppercase
characters converted to lowercase. For example:
SELECT LCASE(ename) FROM emp WHERE ename is 'John';
This returns 'john'.
RPAS ODBC/JDBC Driver
14-43
Supported and Unsupported SQL Functions
Table 14–4 (Cont.) String Functions
Function
Description
LEFT(string_exp, count)
Returns the leftmost count characters of string_exp.
If string_exp is wide character string, the return value is a wide
character string. Offset (count) must be specified in number of
characters. For example:
SELECT LEFT(ename, 2) FROM emp WHERE ename = 'John';
This returns 'jo'.
SELECT LEFT(ename, 2) FROM emp WHERE ename = N'John';
If ename is a column of wide character data type, this returns
wide character string N'jo'.
LENGTH(string_exp)
Returns the number of characters in string_exp, excluding
trailing blanks.
If string_exp is wide character string, the return value is a
number of wide characters in string_exp. Trailing blanks are not
checked in wide character implementation. For example:
SELECT LENGTH('John '), LENGTH('John') FROM emp;
This returns 4 for both result columns as trailing blanks are
excluded.
SELECT LENGTH(N'John '), LENGTH(N'John') FROM emp;
This returns 7 for the first result column and 4 for the second
result column. Trailing blanks are not checked in wide character
implementation.
LOCATE(string_exp1,
string_exp2[, start])
Returns the starting position of the first occurrence of
string_exp1 within string_exp2. The search for the first
occurrence of string_exp1 begins with the first character position
in string_exp2 unless the optional argument, start, is specified. If
start is specified, the search begins with the character position
indicated by the value of start. The first character position in
string_exp2 is indicated by the value 1. If string_exp1 is not
found within string_exp2, the value 0 is returned.
If string_exp2 is a wide character string, returns the starting
position of the first occurrence of string_exp1 within the wide
character string string_exp2. Offset (start) must be specified in
number of characters. If string _exp2 is a wide character exp, the
result is computed by treating both arguments as wide character
string. For example:
SELECT LOCATE('h', 'John', 1) FROM emp;
This returns 3 as 'h' is the found at the third position.
SELECT LOCATE(N'h', N'John', 1) FROM emp;
This returns 3 as N'h' is the found at the third position.
LTRIM(string_exp)
Returns the characters of string_exp, with leading blanks
removed. For example:
SELECT LTRIM(' ABC') FROM emp;
This returns 'ABC'.
OCTET_LENGTH(string_ex
p)
Returns the length in bytes of the string expression. The result is
the smallest integer not less than the number of bits divided by
8. For example:
SELECT OCTET_LENGTH(ename) FROM emp WHERE ename
=
'John';
This returns 4.
14-44 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Table 14–4 (Cont.) String Functions
Function
Description
POSITION(character_exp1
character_exp2)
Returns the position of the first character expression in the
second character expression. The result is an exact numeric with
an implementation-defined precision and a scale of 0.
If character_exp1 and character_exp2 are wide character strings,
returns the position of the first wide character expression in the
second wide character expression. If character_exp2 is a wide
character string, the result is computed by treating both
arguments as wide character strings. For example:
SELECT POSITION('abc', '1234abc def') FROM emp;
This returns 5.
SELECT POSITION(N'abc', N'1234abc def') FROM emp;
This returns 5.
REPEAT(string_exp, count)
Returns a character string composed of string_exp repeated
count times.
If string_exp is wide character string, the return value is a wide
character string. For example:
SELECT REPEAT(ename, 2) FROM emp WHERE ename =
'John';
This returns 'JohnJohn'
SELECT REPEAT(ename, 2) FROM emp WHERE ename =
N'John';
If ename is a column of wide character data type, this returns
N'JohnJohn'.
REPLACE(string_exp1,
string_exp2, string_exp3)
Search string_exp1 for occurrences of string_exp2, and replace
with string_exp3.
If string_exp1 is wide character string, the return value is a wide
character string. For example:
SELECT REPLACE(address, 'San Francisco', 'SFO') FROM emp
where address = '100 Vanness, San Francisco';
This returns '100 Vanness, SFO'.
SELECT REPLACE(address, N'San Francisco', N'SFO') FROM
emp WHERE address = N'100 Vanness, San Francisco';
If address is a column of wide character data type, this returns
N'100 Vanness, SFO'.
RIGHT(string_exp, count)
Returns the right-most count characters of string_exp.
If string_exp is wide character string, the return value is a wide
character string. Offset (count) must be specified in number of
characters. For example:
SELECT RIGHT(ename, 2) FROM emp WHERE ename = 'John';
This returns 'hn'.
SELECT RIGHT(ename, 2) FROM emp WHERE ename =
N'John';
If ename is a column of wide character data type, this returns
N'hn'.
RTRIM(string_exp)
Returns the characters of string_exp with trailing blanks
removed. For example:
SELECT RTRIM('abc ') FROM emp;
This returns 'abc'.
RPAS ODBC/JDBC Driver
14-45
Supported and Unsupported SQL Functions
Table 14–4 (Cont.) String Functions
Function
Description
SPACE(count)
Returns a character string consisting of count spaces. For
example:
SELECT ename+space(5)+ename FROM emp WHERE ename =
'John';
This returns 'John John'.
SUBSTRING(string_exp,
start, length)
SUBSTR(string_exp, length)
Returns a character string that is derived from string_exp,
beginning at the character position specified by start for length
characters.
If string_exp is wide character string, the return value is a wide
character string. Offset (start and length) must be specified in
number of characters. For example:
SELECT SUBSTR(ename, 1, 3) FROM emp WHERE ename
='John';
This returns 'Joh'
SELECT SUBSTR(ename, 1, 3) FROM emp WHERE ename =
N'John';
If ename is a column of wide character data type, this returns
N'Joh'
UCASE(string_exp)
UPPER(string_exp)
Returns a string equal to that in string_exp, with all lowercase
characters converted to uppercase. For example:
SELECT UCASE(ename) FROM emp WHERE ename = 'John';
This returns 'JOHN'.
UNICODE(string_exp)
Returns the Unicode code of the first character of the string_exp
as a SQL_INTEGER value. Example: "SELECT UNICODE('αβγ')"
returns an integer value of 945.
Time / Date Functions
Table 14–5
Time / Date Functions
Function
Description
CURDATE()
Returns the current date. For example:
SELECT CURDATE() FROM emp;
Returns the current date as: 2008-10-25
CURTIME()
Returns the current local time. For example:
SELECT CURTIME() FROM emp;
Returns the current time as: 10:20:05
CURTIMESTAMP()
Returns the current local date and local time as a timestamp
value. For example:
SELECT CURTIMESTAMP() FROM emp;
Returns current date and time as: 2003-03-31 14:08:57
14-46 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Table 14–5 (Cont.) Time / Date Functions
Function
Description
DATEADD( datepart ,
number ,date )
Returns a new date time value based on adding an interval to
the specified date. The return date-time data type is same as the
input date value.
TIMESTAMPADD( datepart ,
number , date )
datepart: the parameter that specifies on which part of the date to
return a new value. Both ODBC notation and SQL Server
notation for datepart are supported.
Datepart Abbreviations
Year SQL_TSI_YEAR , year, yy, yyyy,
quarter SQL_TSI_QUARTER, quarter, qq, q
Month SQL_TSI_MONTH, month, mm, m
dayofyear DAYOFYEAR, dy, y
Day SQL_TSI_DAY, day, dd, d
Week SQL_TSI_WEEK, week, wk, ww
Hour SQL_TSI_HOUR, hour, hh
minute SQL_TSI_MINUTE , minute, mi, n
second SQL_TSI_SECOND, second, ss, s
The current implementation does not support millisecond and
fractional second specifications.
number: the value used to increment the datepart. If value is not
an integer, the fractional part of the value is discarded. For
example, if you specify day for datepart and1.75 for number, date
is incremented by 1.
date: an expression that returns a date or timestamp value or a
character string in a date-time format.
RPAS ODBC/JDBC Driver
14-47
Supported and Unsupported SQL Functions
Table 14–5 (Cont.) Time / Date Functions
Function
Description
DATEDIFF( datepart ,
startdate , enddate )
Returns the number of date and time boundaries crossed
between two specified dates. startdate is subtracted from enddate.
If startdate is later than enddate, a negative value is returned.
TIMESTAMPDIFF( datepart ,
startdate , enddate )
datepart: the parameter that specifies on which part of the date to
calculate the difference. Both ODBC notation and SQLServer
notation for datepart are supported.
Datepart Abbreviations
Year SQL_TSI_YEAR, year, yy, yyyy,
quarter SQL_TSI_QUARTER, quarter, qq, q
Month SQL_TSI_MONTH, month, mm, m
dayofyear DAYOFYEAR, dy, y
Day SQL_TSI_DAY, day, dd, d
Week SQL_TSI_WEEK, week, wk, ww
Hour SQL_TSI_HOUR, hour, hh
minute SQL_TSI_MINUTE, minute, mi, n
second SQL_TSI_SECOND, second, ss, s
The current implementation does not support dayofyear,
millisecond and factional second specifications. For example:
SELECT DATEDIFF(year, hiredate, curdate())
FROM emp WHERE hiredate = '2000-10-01';
SELECT DATEDIFF(SQL_TSI_YEAR, hiredate, curdate())
FROM emp WHERE hiredate = '2000-10-01';
This returns 2 (assuming that the curdate() returns year 2002).
DAYNAME(date_exp)
Returns a character string containing the data source-specific
name of the day (for example, Sunday through Saturday or Sun.
through Sat. for a data source that uses English, or Sonntag
through Samstag for a data source that uses German) for the day
portion of date_exp. For example:
SELECT DAYNAME('2002-01-01'), DAYNAME('2002-01-02')
FROM
emp;
This returns 'Tuesday' and 'Wednesday'.
DAYOFMONTH(date_exp)
Returns the day of the month based on the month field in
date_exp as an integer value in the range of 1-31. For example:
SELECT DAYOFMONTH('2002-01-05') FROM emp;
This returns 5.
DAYOFWEEK(date_exp)
Returns the day of the week based on the week field in date_exp
as an integer value in the range of 1-7, where 1 represents
Sunday. For example:
SELECT DAYOFWEEK('2002-01-05') FROM emp;
This returns 7.
DAYOFYEAR(date_exp)
Returns the day of the year based on the year field in date_exp as
an integer value in the range of 1-366. For example:
SELECT DAYOFYEAR('2002-01-05') FROM emp;
This returns 5.
14-48 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Table 14–5 (Cont.) Time / Date Functions
Function
Description
HOUR(time_exp)
Returns the hour based on the hour field in time_exp as an
integer value in the range of 0-23. For example:
SELECT HOUR('22:20:20') FROM emp;
This returns 22.
MINUTE(time_exp)
Returns the minute based on the minute field in time_exp as an
integer value in the range of 0-59. For example:
SELECT MINUTE('22:21:20') FROM emp;
This returns 21.
MONTH(date_exp)
Returns the month based on the month field in date_exp as an
integer value in the range of 1-12. For example:
SELECT MONTH('2002-01-05') FROM emp;
This returns 1.
MONTHNAME(date_exp)
Returns a character string containing the data source-specific
name of the month (for example, January through December or
Jan. through Dec. for a data source that uses English, or January
through Dezember for a data source that uses German) for the
month portion of date_exp. For example:
SELECT MONTHNAME('2002-01-05') FROM emp;
This returns January.
NOW( )
Returns current date and time as a timestamp value. For
example:
SELECT NOW() FROM emp;
This returns the current date and time: 2002-10-25 10:20:05.
QUARTER(date_exp)
Returns the quarter in date_exp as an integer value in the range
of 1-4, where 1 represents January 1 through March 31. For
example:
SELECT QUARTER('2002-01-05') FROM emp;
This returns 1.
SECOND(time_exp)
Returns the second based on the second field in time_exp as an
integer value in the range of 0-59. For example:
SELECT SECOND('22:21:20') FROM emp;
This returns 20.
WEEK(date_exp)
Returns the week of the year based on the week field in date_exp
as an integer value in the range of 1-53. For example:
SELECT WEEK('2002-01-05') FROM emp;
This returns 1.
YEAR(date_exp)
Returns the year based on the year field in date_exp as an integer
value. For example:
SELECT YEAR('2002-01-01') FROM emp;
This returns 2002.
RPAS ODBC/JDBC Driver
14-49
Supported and Unsupported SQL Functions
System Functions
Table 14–6
System Functions
Function
Description
DATABASE( )
Returns the name of the database corresponding to the
connection handle. (The name of the database is also available
by calling SQLGetConnectOption with the
SQL_CURRENT_QUALIFIER connection option.)
USER( )
Returns the user name in the DBMS. (The user name is also
available using SQLGetInfo by specifying the information type:
SQL_USER_NAME.) This can be different than the login name.
Aggregate Functions
Aggregate functions return a single row based on groups of rows, rather than on single
rows.
Table 14–7
Aggregate Functions
Function
Description
AVG([ALL | DISTINCT]
expression)
Returns the average of the values in a group. Null values are
ignored.
SUM([ALL | DISTINCT]
expression)
Returns the sum of all the values, or only the DISTINCT values,
in the expression. SUM can be used with numeric columns only.
Null values are ignored.
COUNT({[ALL |
DISTINCT] expression] | *})
Returns the number of items in a group.
COUNT(*) returns the number of items in a group, including
NULL values and duplicates.
COUNT(ALL expression) evaluates expression for each row in a
group and returns the number of non-null values.
COUNT(DISTINCT expression) evaluates expression for each row
in a group and returns the number of unique, non-null values.
MAX([ALL | DISTINCT]
expression)
Returns the maximum value in the expression.
MIN([ALL | DISTINCT]
expression)
Returns the minimum value in the expression.
Aggregate functions can appear in SELECT lists and HAVING clauses. If you use the
GROUP BY clause in a SELECT statement, OpenAccess SDK divides the rows of a
queried table or view into groups. In a query containing a GROUP BY clause, all
elements of the SELECT list must be expressions from the GROUP BY clause,
expressions containing aggregate functions, or constants. OpenAccess SDK applies the
aggregate functions in the SELECT list to each group of rows and returns a single
result row for each group.
If you omit the GROUP BY clause, OpenAccess SDK applies aggregate functions in the
SELECT list to all the rows in the queried table or view.
Many aggregate functions accept these options:
■
■
DISTINCT causes an aggregate function to consider only distinct values of the
argument expression.
ALL causes an aggregate function to consider all values, including all duplicates.
14-50 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
For example:
SELECT max(sal), MIN(sal), AVG(sal) FROM emp;
SELECT deptno, MAX(sal), SUM(sal) FROM emp GROUP BY deptno;
SELECT deptno, COUNT(empno) FROM emp GROUP BY deptno;
Other Functions
DECODE
Syntax
DECODE (expr, [search, result]..., default)
Example
SELECT DECODE (deptno,10, 'ACCOUNTING',
20, 'RESEARCH',
30, 'SALES',
40, 'OPERATION',
'NONE')
FROM dept
To evaluate this expression, the OpenAccess SDK SQL engine compares expr to each
search value one by one. If expr is equal to a search, the OpenAccess SDK SQL engine
returns the corresponding result. If no match is found, the OpenAccess SDK SQL
engine returns default, or if default is omitted, returns null. The return value is the
same data type as the first result expression. The search, result, and default values can
be derived from expressions.
The OpenAccess SDK SQL engine evaluates each search value only before comparing
it to expr, rather than evaluating all search values before comparing any of them with
expr. Consequently, OpenAccess SDK SQL engine never evaluates a search if a
previous search is equal to expr.
The OpenAccess SDK SQL engine automatically converts expr and each search value
to the datatype of the first search value before comparing. The OpenAccess SDK SQL
engine automatically converts the return value to the same datatype as the first result.
If the first result has the datatype CHAR or if the first result is null, then the
OpenAccess SDK SQL engine converts the return value to the datatype of CHAR.
In a DECODE expression, the OpenAccess SDK SQL engine considers two nulls to be
equivalent.
If expr is null, the OpenAccess SDK SQL engine returns the result of the first search
that is also null. The maximum number of components in the DECODE expression,
including expr, searches, results, and default is 255.
Examples:
SELECT DECODE(empno, 1, 'E1', 2, 'E2', 'DEFAULT') FROM emp;
# First Result expression is NULL. Result should be type
XO_TYPE_CHAR
SELECT DECODE(empno, 1, NULL, 2, 'E2', 'DEFAULT') FROM emp;
# Input expression is NULL, Result should match the result
of NULL search expr
SELECT DECODE(ename, 'Bob', 'My Bob', 'Mary', 'My Mary',
NULL, 'New Name', 'Default Name') FROM emp;
# no default value, so return NULL for non-match values
SELECT DECODE(empno, 1, 'E1', 2, 'E2') FROM emp;
RPAS ODBC/JDBC Driver
14-51
Supported and Unsupported SQL Functions
# ERROR CHECKING
# Invalid number of arguments
# Invalid syntax used with scalar function:DECODE. Function
expects 3 arguments.
SELECT DECODE() FROM emp;
SELECT DECODE(empno, 1) FROM emp;
# Conversion errors
# decode() Error converting value of result expression to
XoType:<4>
SELECT DECODE(empno, 1, 10, 2, 20, 'abc') FROM emp;
IFNULL, ISNULL, NVL
These functions allow NULL value to be replaced by a default value. OpenAccess SDK
supports IFNULL as defined by ODBC, ISNULL as defined by SQL Server, and NVL
as defined by Oracle.
Syntax
IFNULL (expr, default_val)
ISNULL (expr, default_val)
NVL (expr, default_val)
The OpenAccess SDK SQL engine evaluates the input expression and returns the
expression value if it is non-NULL. If the expression value is NULL, default_val is
returned. The return value is of the same data type as the input expression.
Example
SELECT ename, IFNULL (sal, 1000) FROM emp;
SELECT ename, ISNULL (sal, 1000) FROM emp;
SELECT ename, NVL (sal, 1000) FROM emp;
SELECT ename, IFNULL (hiredate, '2001-01-01') FROM emp;
CAST
Syntax
CAST (value_exp AS data_type)
Example
SELECT empno, CAST(empno AS VARCHAR) FROM emp
SELECT empno, CAST(empno AS SMALLINT) FROM emp
The function returns the value specified by value_exp converted to the specified
data_type, where data_type is one of the following:
■
CHAR
■
NUMERIC
■
DECIMAL
■
INTEGER
■
SMALLINT
■
FLOAT
■
REAL
■
DOUBLE
14-52 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
■
DATE
■
TIME
■
TIMESTAMP
■
VARCHAR
■
LONGVARCHAR
■
BINARY
■
VARBINARY
■
LONGVARBINARY
■
TINYINT
■
BIT
■
WCHAR,
■
WVARCHAR
■
WLONGVARCHAR
The following table defines the precision, length, and scale keywords of the CAST
function.
Table 14–8
CAST Function
Keyword
Value
CHAR
255
BINARY
255
BIT
1
DATE
6
DOUBLE
8
FLOAT
8
INTEGER
4
LONGVARBINARY
1000000
LONGVARCHAR
1000000
NUMERIC
34
SMALLINT
2
REAL
4
TIME
6
TIMESTAMP
16
TINYINT
1
VARBINARY
1024
VARCHAR
1024
WLONGVARCHAR
2000000
WVARCHAR
512
WVARCHAR
2048
CHAR, BINARY
255
RPAS ODBC/JDBC Driver
14-53
Supported and Unsupported SQL Functions
Table 14–8 (Cont.) CAST Function
Keyword
Value
DATE
10
DOUBLE
15
FLOAT
15
INTEGER
10
LONGVARBINARY
1000000
LONGVARCHAR
1000000
NUMERIC
32
REAL
7
SMALLINT
5
TIME
6
TINYINT
3
VARBINARY
1024
VARCHAR
1024
WCHAR
255
WVARCHAR
1024
WLONGVARCHAR
1000000
NUMERIC
5
All other types
0
CONVERT
Syntax
CONVERT (value_exp, data_type)
Example
SELECT empno, CONVERT(empno, SQL_VARCHAR) FROM emp
SELECT empno, CONVERT(empno, SQL_SMALLINT) FROM emp
The function returns the value specified by value_exp converted to the specified
data_type, where data_type is one of the following:
■
SQL_CHAR
■
SQL_NUMERIC
■
SQL_DECIMAL
■
SQL_INTEGER
■
SQL_SMALLINT
■
SQL_FLOAT
■
SQL_REAL
■
SQL_DOUBLE
■
SQL_DATE
■
SQL_TIME
14-54 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
■
SQL_TIMESTAMP
■
SQL_VARCHAR
■
SQL_LONGVARCHAR
■
SQL_BINARY
■
SQL_VARBINARY
■
SQL_LONGVARBINARY
■
SQL_TINYINT
■
SQL_BIT
■
SQL_WCHAR
■
SQL_WVARCHAR
■
SQL_WLONGVARCHAR
The following tables define the length, precision, and scale keywords of the CONVERT
function.
Table 14–9
CONVERT Function-Length
Keyword
Length
SQL_CHAR
256
SQL_BINARY
256
SQL_BIT
1
SQL_DATE
6
SQL_DOUBLE
8
SQL_FLOAT
8
SQL_INTEGER
4
SQL_LONGVARBINARY
1000000
SQL_LONGVARCHAR
1000000
SQL_NUMERIC
34
SQL_SMALLINT
2
SQL_REAL
4
SQL_TIME
6
TIMESTAMP
16
TINYINT
1
VARBINARY
1024
VARCHAR
1024
WLONGVARCHAR
2000000
WVARCHAR
512
WVARCHAR
2048
RPAS ODBC/JDBC Driver
14-55
Supported and Unsupported SQL Functions
Table 14–10
CONVERT Function-Precision
Keyword
Precision
SQL_BINARY
255
SQL_BIT
1
SQL_CHAR
255
SQL_DATE
10
SQL_DOUBLE
15
SQL_FLOAT
15
SQL_INTEGER
10
SQL_LONGVARBINARY
1000000
SQL_LONGVARCHAR
1000000
SQL_NUMERIC
32
SQL_REAL
7
SQL_SMALLINT
5
SQL_TIME
8
SQL_TINYINT
3
SQL_VARBINARY
1024
SQL_VARCHAR
1024
SQL_WCHAR
255
SQL_WVARCHAR
2048
SQL_WLONGVARCHAR
1000000
Table 14–11
CONVERT Function-Scale
Keyword
Scale
SQL_NUMERIC
5
All other types
0
14-56 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Unsupported SQL Functions
The SQL engine of the RPAS ODBC Server implements a large portion of the entry
level SQL as defined in the X3.135-1992, "Database Language SQL" specification and
commercial databases like SQL Server and Oracle. It is compliant with the ODBC
minimal grammar specification.
This section describes the unsupported features.
Handling of NULLS
NOT IN should return FALSE if any member of the set is NULL. When evaluating the
IN condition, the OpenAccess SDK SQL engine treats the comparison of any value
with NULL as FALSE, so NOT IN will become TRUE.
SELECT * FROM emp WHERE job NOT IN
(SELECT job FROM emp WHERE job IS NULL)
This example should return no results if there is an emp record with NULL value for
Job.
Schema Information
The SQL engine of the RPAS ODBC Driver does not support the following:
■
Collate sequence and character set
■
DEFAULT clause for column values
Data Definition Language (DDL)
The only DDL that is supported is "create view".
Insert
■
Insert statements are not supported.
■
Update measure data on fact table is supported.
SELECT Syntax
Subqueries are not supported in a SELECT list.
Example:
SELECT
(SELECT a.empno FROM emp a WHERE a.deptno = b.deptno)
FROM
dept b
Value Expressions
Special Values- The SQL engine does not support the use of special values
(CURRENT_USER, SESSION_USER, CURRENT_TIMESTAMP) in value specification.
RPAS ODBC/JDBC Driver
14-57
Supported and Unsupported SQL Functions
Value Functions
The SDK SQL engine does not support the following functions:
■
TRANSLATE
■
TRIM
The OpenAccess SDK SQL engine supports LTRIM and
RTRIM.)
Note:
■
DIFFERENCE
■
SOUNDEX
Date/Time Functions
The OpenAccess SDK SQL engine does not support the following Date/Time
functions:
■
CURRENT_TIME[(time-precision)] - The SQL engine does not support timeprecision argument.
■
CURRENT_TIMESTAMP[(time-precision)]
■
EXTRACT(extract-field FROMextract-source)
Advanced Value Expressions
NULLIF
NULLIF is shorthand for a frequently used variation of CASE.
Syntax
NULLIF(value1, target_value)
is equivalent to
CASE
WHEN value1 = = target_value THEN NULL
ELSE value1
END
Example:
.. WHERE sales_revenue / NULLIF(our_cost, -1) > 50
COALESCE
Coalesce is shorthand for a frequently used variation of CASE.
Syntax:
COALESCE (value1, value2, value3)
is equivalent to:
CASE
WHEN value1 IS NOT NULL THEN value1
WHEN value2 IS NOT NULL THEN value2
ELSE value3
END
14-58 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Supported and Unsupported SQL Functions
Example:
SELECT name, job_title, COALESCE (salary, commission,
subsistence)
FROM job_assignments
Row Value Constructor
A row value constructor is a parenthesized list of values.
Example:
The following expression:
WHERE c1=CA AND c2=CB AND c3=CC
can be written using row value constructor as:
WHERE (c1, c2, c3) = (CA, CB, CC)
Predicates
The SQL engine does not support the following predicates.
■
■
OVERLAPS predicate: Determines whether two intervals of time overlap with one
another.event-information OVERLAPS event-information
MATCH predicate
Join Operators
This section explains which Join operations are supported by the RPAS SQL engine,
and which are not.
Supported Join Operators
The OpenAccess SDK SQL engine supports the following join operations:
■
■
Implicit JOIN. The WHERE clause explicitly specifies the join condition.
INNER JOIN. All joins that are not OUTER JOINS are considered in SQL
terminology as INNER joins. The use of keyword INNER has no additional effects,
but helps the statement to be completely self-documenting.
■
■
■
SELECT * FROM t1 INNER JOIN t2 ON t1.c1 = t2.c3 WHERE search-LEFT
OUTER JOIN - This join preserves unmatched rows from the left table.
SELECT * FROM t1 LEFT OUTER JOIN t2 ON t1.c1 = t2.c3 WHERE searchcondition
UNION and UNION ALL operators. UNION is used for combining two result
tables that are union compatible.
SELECT c1, c2 FROM t1 UNION SELECT c3, c4 FROM t2
RPAS ODBC/JDBC Driver
14-59
Supported and Unsupported SQL Functions
Unsupported Join Operators
The following join operations (syntax) are not supported in this release:
■
CROSS JOIN: Functionally similar to the implicit joins.
SELECT * FROM t1 CROSS JOIN t2
■
NATURAL JOIN: Also referred to as natural, equi-join selects rows from the tables
that have same value for columns with the same name.
SELECT * FROM t1 NATURAL JOIN t2
■
Condition JOIN: Uses the keyword ON to specify the JOIN condition between
tables. The scope of fields referred in the ON condition is restricted.
SELECT * FROM t1 JOIN t2 ON t1.c1 = t2.c3 WHERE search-condition
■
Column Name JOIN: Specifies a more restricted form of NATURAL join.
NATURAL joins use all columns with the same names to manage the matching
process. The column name JOIN specifies which column values should be
matched.
SELECT * FROM t1 JOIN t2 USING (c1, c2)
■
RIGHT OUTER JOIN: Preserves unmatched rows from the right table.
SELECT * FROM t1 RIGHT OUTER JOIN t2 ON t1.c1 = t2.c3 WHERE searchcondition
■
FULL OUTER JOIN: Preserves unmatched rows from both the left and right tables.
SELECT * FROM t1 FULL OUTER JOIN t2 ON t1.c1 = t2.c3 WHERE searchcondition
■
UNION JOIN: Creates a new virtual table with the union of all columns from the
source tables. The UNION join has no provision for column matching.
14-60 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
15
Publishing Measure Change Events
15
Event driven planning requires the ability to identify events when they arise. This
includes events that result from changes in plans and those that arise because of
advancement in the planning activity, for example, approval of a plan or creation of
new items. The ability to get notification of the event when it occurs is therefore
essential. In the context of RPAS applications, many measure changes result from
business activities and therefore fall into the category of notification-worthy events.
RPAS Publishing Measure Changes (PMC) provides a mechanism to monitor measure
changes and receive notification messages through a standard JMS messaging service.
A measure change event is defined as the measure data being written by any means.
The following is the list of the sources for PMC events:
1.
MACE: all left hand side measures in the expression or expressions of the rule
group specified in the command line.
2.
Workbook Commit: all left hand side measures in the commit rule group.
3.
loadMeasure: all successfully loaded measures.
4.
loadHier: measures whose base intersection contains at least one affected
dimension. "Affected" means adding and deleting one or more logical positions.
5.
Dynamic Position Management (DPM): measures whose base intersection contains
a dimension affected by DPM. Adding or removing positions to a dimension or its
lower level children constitutes a change in the measure.
The following diagram demonstrates a JMS system in the context of RPAS. The JMS
system consists of four basic components:
■
■
■
■
JMS Provider: The central daemon which accepts connections from clients and
routes and queues messages. It is sometimes called JMS Broker.
Java Naming and Directory Interface (JNDI) Service: A service that provides
mapping between names and objects. It adds abstraction to the more complex
structure of underlying objects.
JMS Client (Publisher): A standalone daemon process running with the other
RPAS server side processes such as DomainDaemon and RpasDbServer.
JMS Client (Subscriber): Any applications interested in getting notifications of
measure changes.
Publishing Measure Change Events 15-1
Configuring Subjects and Measures for Monitoring
Figure 15–1 JMS System in RPAS
Configuring Subjects and Measures for Monitoring
A subject is defined as a logical grouping of measures. A subject is mapped to one or
more measures in one domain, while a measure can belong to one or more subjects.
For example, a subject named PlanningMeasures can include all measures associated
with planning.
The configuration file of measure change monitoring serves two purposes:
■
Defines the mappings between subjects and measures.
■
Defines the inclusion filters for monitored measures.
By default, no measures are monitored unless they are specifically included in the
configuration.
For each domain, there is one measure change monitor configuration file. It is named
MeasureChangeMonitor.properties and must be located under {domainPath}/config/.
There is only one property file for a global domain. It is placed
under the config directory of the master domain.
Note:
This configuration file is in standard Java properties file format. Each line defines the
relationship between one subject and one measure:
Subject.MeasureName=true
■
■
true means inclusion in monitoring.
false is used to exclude a subject/measure from monitoring. Use of false is not
recommended since, by default, a measure is not monitored and such a line can be
deleted or commented out from the file. Comments are any contents on a line from
"#" to the end of the line.
15-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Configuring the RPAS JMS Publisher
Example:
TestMeasures.R_EX_DEMOA=true
TestMeasures.R_EX_DEMOB=true
LanguageMeasures.R_MsgLabel=true
The following are defined in the above example:
■
■
■
Two subjects: "TestMeasures" and "LanguageMeasures".
The subject "TestMeasures" represents two measures: "R_EX_DEMOA" and "R_
EX_DEMOB".
The subject "LanguageMeasures" represents one measure: "R_MsgLabel".
A subject name must be a valid hierarchical variable name, that is, consists of only
alphanumeric characters, underscores, and periods. RPAS does not enforce any
naming convention for a subject. It is up to the retailer to define their own naming
convention.
After the configuration file is modified, RPAS processes can detect that the file has
changed and automatically reload it. There is no need to restart any RPAS processes.
Configuring the RPAS JMS Publisher
JMS Publisher for measure change events is implemented in Java and runs as a
standalone process. It is decoupled from any other RPAS server side processes in terms
of interprocess communications and domain data file locking.
Each JMS Publisher process is tied to a domain and a JMS topic. When the publisher
detects an event for its domain, it generates a JMS message and sends the message to a
JMS provider. The format of the JMS message is defined by a template file which can
contain any of the macros listed in the following table. The macros are replaced by
actual values at run time.
Table 15–1
Configuration Macros
Macro Name
Format
Notes
__EventDateTime__
YYYY-MM-DDThh:mm:ss
Local time of the server.
__SourceURI__
RPAS/JMS/{hostname}
{hostname} is the name of the
server where the publisher is
running.
__SUBJECT__
String
Subject of the event as defined
in
MeasureChangeMonitor.prope
rties.
__TYPE__
"MeasureChange"
Type is a constant string.
__DOMAIN__
String
Path to the domain.
__MEASURE__
String
RPAS internal measure name.
__ORIGINUSER__
String
RPAS User ID, only available
for workbook commit or DPM.
Use "-" if not available.
Publishing Measure Change Events 15-3
Configuring the RPAS JMS Publisher
Below are two examples of a JMS message template.
Example 1 - Simple name/value pairs:
type=__TYPE__
domain=__DOMAIN__
measure=__MEASURE__
time=__EventDateTime__
user=__ORIGINUSER__
Example 2 - XML-based Notification Event Architecture for Retail (NEAR) format:
<?xml version="1.0" encoding="UTF-8" ?>
<AlertEvent MajorVersion="1" MinorVersion="0" TypeCode="RPASEvent"
Priority="0" Severity="Information" Mode="Test" FixVersion="0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.retail.oracle.com/workspace/alerts/AlertEventV1.0.0
.xsd"
xmlns="http://www.retail.oracle.com/workspace/alerts/">
<SequenceNumber>0</SequenceNumber>
<EventDateTime>__EventDateTime__</EventDateTime>
<EventDescription>RPAS Measure Change Event</EventDescription>
<SourceName>RPAS</SourceName>
<SourceURI>__SourceURI__</SourceURI>
<Instance>1</Instance>
<RoutingInfo TypeCode="SubjectInfo">__SUBJECT__</RoutingInfo>
<AlertData><![CDATA[<type>__TYPE__</type>
<domain>__DOMAIN__</domain>
<measure>__MEASURE__</measure>
<originUser>__ORIGINUSER__</originUser>]]></AlertData>
</AlertEvent>
Command Line
The following command line is used for JMS Publisher:
java -cp {classpath} oracle.rpas.pmc.MCPublisher -d {domainPath} [-c
{configFileName}] [name1=value1 [name2=value2 [...]]]
The following table provides descriptions of the arguments used in the command line.
Table 15–2
Arguments Used in the Command Line
Argument
Description
classpath
Should include rpaspmc.jar and jms.jar under $RPAS_
HOME/lib and any vendor-specific JMS implementation jar
files.
-d domainPath
Path to the monitored domain. It must be a simple or master
domain.
-c configFileName
Configuration file in Java properties file format. This argument
is optional.
name1=value1
name2=value2 …
name/value pairs. If the configuration file is not specified, the
name/value pairs are used.
If the configuration file is specified, the name/value pairs are
added to the configuration and overwrite any value with the
same name already present in the file. This argument is optional.
15-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Configuring the RPAS JMS Publisher
Configuration Settings
The configuration settings for the JMS Publisher can be categorized into general and
vendor-specific settings.
General Settings
The following table lists all vendor neutral configuration settings for the JMS
Publisher:
Table 15–3
Vendor Neutral Configuration Settings for the JMS Publisher
Setting Name
Description
Required
Value
topic
JMS topic lookup name.
Yes
A string with only alphanumeric
characters, underscores, and periods.
Maximum length is 100 bytes.
Yes
A string with only alphanumeric
characters, underscores, and periods.
Maximum length is 100 bytes.
topicConnection JMS topic connection
Factory
factory lookup name.
Yes
messageTempla Template file name for
te
the JMS message. This
file must be placed under
the config directory of
the domain.
logLevel
Logging level. A log level No
is a cut-off level which
means logs with a lower
level are filtered out.
Standard template file
PMCMessageTemplate.xml is
available under $RPAS_
HOME/domain/config. This file
needs to be copied to the config
directory of the domain.
Specify one of the following values,
in low to high order.
"VERBOSE": All logs.
"DEBUG": Debug logs.
"INFO": Informational logs.
"WARN": Warning logs.
"ERROR": Error logs.
"SUPPRESS": No logs.
If not specified, the default is "INFO".
logFile
The path to the log file.
Can be a relative or
absolute path.
restartAfterExce Flag to restart after
ption
encountering any JMS
related exceptions.
No
If not specified, output to the
console.
No
If true, the publisher will try to
restart after catching any JMS related
exceptions. Interval between retries
is 180 seconds. To stop the publisher
from trying to restart, the process
must be ended manually.
Default is true.
message.deliver Delivery mode.
yMode
message.priorit
y
No
A priority number for the No
JMS message.
message.timeTo Time to live in
Live
milliseconds.
No
"NON_PERSISTENT" or
"PERSISTENT". Default is
"PERSISTENT"
0 to 9. Default is 4.
0 or any positive integer. Default is 0
(unlimited).
Publishing Measure Change Events 15-5
Configuring the RPAS JMS Publisher
Vendor-Specific Settings
Sun Open Message Queue is used as an example for these settings. For further details,
consult the vendor documentation for your JMS implementation.
File Based JNDI Object Store
File based JNDI object store is used primarily for development and testing. It is very
easy to set up, but has weak built-in security.
Table 15–4
File Based JNDI Object Store
Property Name
Description
Required
Value
java.naming.factor
y.initial
Initial context for
JNDI lookup.
Yes
For Open Message Queue, it must
be:
com.sun.jndi.fscontext.RefFSCont
extFactory
java.naming.provi
der.url
Directory path to
the object store.
Yes
Example:
file:///C:/myapp/mqobjs
LDAP Based JNDI Object Store
An LDAP server is the recommended object store for production JMS messaging
systems. LDAP servers are designed for use in distributed systems and provide
security features that are required in production environments.
Table 15–5
LDAP Based JNDI Object Store
Property Name
Description
Required
Value
java.naming.factor
y.initial
Initial context for
JNDI lookup.
Yes
For Open Message Queue, it must
be:
com.sun.jndi.ldap.LdapCtxFactor
y
java.naming.provi
der.url
Server URL and
directory path to
the object store.
Yes
Example:
ldap://myD.com:389/ou=mq1,o=
App
where administered objects are
stored in the directory /App/mq1
java.naming.securit Identity of the
y.principal
principal for
authenticating
callers.
No
The format of this attribute
depends on the authentication
scheme.
For example:
uid=homerSimpson,ou=People,o=
mq
If this attribute is not specified, the
behavior is determined by the
LDAP service provider.
java.naming.securit Credentials of the
y.credentials
authentication
principal.
No
The value of this attribute
depends on the authentication
scheme. For example, it might be a
hashed password, clear-text
password, key, or certificate.
If this property is not specified,
the behavior is determined by the
LDAP service provider.
15-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Configuring the RPAS JMS Subscriber
Table 15–5 (Cont.) LDAP Based JNDI Object Store
Property Name
Description
java.naming.securit Security level for
y.authentication
authentication.
Required
Value
No
Specify one of these options:
"none": No security
"simple": Simple security
"strong": Strong security
For example, if you specify
"simple", you are prompted for
any missing principal or
credential values. This enables a
more secure way of providing
identifying information.
If this property is not specified,
the behavior is determined by the
LDAP service provider.
The following is a sample configuration file for RPAS JMS Publisher:
java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file:///C:/Temp
topic=RPASEventTopic
topicConnectionFactory=RPASEventTopicConnectionFactory
messageTemplate=PMCMessageTemplate.xml
Configuring the RPAS JMS Subscriber
A sample JMS Subscriber is implemented to use for testing or trouble-shooting. This
subscriber is packaged and deployed along with the publisher. It simply writes the
messages it receives to logging output which can be console or a log file.
Command Line
Here is the command line for the sample JMS Subscriber:
java -cp {classpath} oracle.rpas.pmc.MCSubscriber [-c {configFileName}]
[name1=value1 [name2=value2 [...]]]
■
■
■
{classpath} should include rpaspmc.jar and jms.jar under $RPAS_HOME/lib and
any vendor-specific JMS implementation jar files.
{configFileName} is a configuration file in Java properties file format. It is optional.
name/value pairs - If the configuration file is not specified, the name/value pairs
are used. Otherwise, the name/value pairs are added to the configuration file and
any value with the same name already present in the file is overwritten.
Publishing Measure Change Events 15-7
Configuring the RPAS JMS Subscriber
Configuration Settings
Vendor-specific settings are the same as the JMS publisher. Refer to the Configuring
the RPAS JMS Publisher section for details.
The following table lists all the general settings for the JMS Subscriber:
Table 15–6
General Settings for the JMS Subscriber
Property Name
Description
Required
Value
topic
JMS topic lookup
name.
Yes
A string with only alphanumeric
characters, underscores, and
periods. Maximum length is 100
bytes.
topicConnectionFa JMS topic connection
ctory
factory lookup name.
Yes
A string with only alphanumeric
characters, underscores, and
periods. Maximum length is 100
bytes.
logLevel
No
Specify one of the following
values, in low to high order.
Logging level. A log
level is a cut-off level
which means logs
with a lower level are
filtered out.
■
"VERBOSE": All logs.
■
"DEBUG": Debug logs.
■
"INFO": Informational logs.
■
"WARN": Warning logs.
■
"ERROR": Error logs.
■
"SUPPRESS": No logs.
If not specified, default is "INFO".
logFile
The path to the log
file. Can be a relative
or absolute path.
clientID
No
JMS Client ID. Only
required for a durable
subscription. Not
recommended for
other use.
durableSubscriptio A unique name for a
nName
durable subscription.
No
No
If not specified, output to the
console.
This must be a unique string for
all JMS clients using the same
connection factory.
If a name is not provided, the
subscription will be a transient
subscription. This means
messages are not queued up if the
connection for the subscriber is
lost or the subscriber is not
running.
The following is a sample configuration file for RPAS JMS Subscriber:
java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file:///C:/Temp
topic=RPASEventTopic
topicConnectionFactory=RPASEventTopicConnectionFactory
15-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
16
In-Context Launch
16
In-Context Launch (ICL) is an RPAS feature that provides retailers with a planning
centered, integrated UI solution for responding to events by adjusting the affected
plans within the context of the changed circumstances and interacting plans. A
planner's workspace can be developed where relevant events are announced in
role-specific dashboards. The planner can drill down into the event report to identify
the context of the event. Appropriate planning applications can be launched to react to
the event by either replanning or deriving further insight from the plans, in order to
justify the event.
RPAS launches a planning application given a context, that is, the template or
workbook to launch and the wizard parameters that define the scope if a new
workbook is to be built. Launching the planning application involves the following
steps:
1.
Start the RPAS client if it is not already running.
2.
Log in the user, if the user is not already logged in.
3.
Create the workbook, if a new workbook is being built.
4.
Open the new or existing workbook, if that is what the context specified.
The following topics are covered in this chapter:
■
Opening a pre-built workbook.
■
Building a new workbook given a specification of the wizard parameters.
■
Issuing the open or build requests from a web application running in a Web portal.
Launching RPAS
A system integrator is responsible for creating a web-based application that can launch
RPAS. Creating an application involves the following steps:
1.
Configure the navigational pane to appropriately launch RPAS.
2.
Create static or dynamic web reports and dashboards, including OBIEE and other
Oracle Fusion technologies, to present integrated data to the end-user with links or
buttons that launch RPAS in-context.
3.
Create alerts or alert reports, using BPM, OBIEE, or other Oracle Fusion
technologies, that have links or other UI mechanisms that can launch RPAS
in-context.
RPAS provides the framework that system integrators can use to launch any
RPAS-based workbook, independent of whether the workbook uses a standard wizard
or a custom wizard.
In-Context Launch
16-1
Launching RPAS
RPAS supports launching workbooks that are built using the dynamic-template API.
This includes all templates built using RPAS Configuration Tools, but does not include
templates that have been coded in C++ using an API lower that the Dynamic
Template.
Successfully launching RPAS administrative templates that are
not built using RPAS Configuration Tools is not guaranteed.
Note:
Issuing a Launch Request from a Web Page
RPAS ICL is implemented as an extension of the RPAS Web Launch feature. As a
prerequisite, a RPAS Web Launch Servlet and RPAS Client web installation package
must be deployed to a web server and made available to system integrators. For more
information, see the "RPAS Classic Client Web Deployment" chapter in the RPAS
Installation Guide.
System integrators must design the report page to have a link, or other web GUI
widget, which invokes client-side JavaScript code to initiate an RPAS ICL. The page
embeds a Java applet from RPAS Web Launch (RWL Applet).
Note:
Java 1.6_10 or above is required.
The applet performs the following operations:
1.
Find the required RPAS client installation on the user's workstation, if it was
installed by the applet in a previous web session.
Note that a standalone RPAS client installation is not recognized because the
installation is tracked by a browser cookie. However, the applet can be forced to
use a preinstalled client by setting a parameter for the applet.
2.
Download and install the appropriate version of the RPAS client if the required
RPAS client installation cannot be found or a new build of the client is available on
the web server.
3.
Start the RPAS client.
4.
Route the ICL request to the RPAS server through the RPAS client and wait for a
response. The response can be a success or failure code, and a corresponding
message.
The applet makes a call back to a JavaScript function to return the response. It is
the responsibility of the system integrators to provide code to handle the response
in the JavaScript function.
16-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
Embedding an RWL Applet on a Web Page
System integrators can embed the applet in a web page using the regular HTML
<Applet> tag. The following attributes are required in the <Applet> tag:
Table 16–1
Attributes Required in the <Applet> Tag
Attribute
Description
Value
code
Applet class name
com.retek.mdap.client.launch.LaunchApplet.clas
s
codebase
URL location to
download the applet
archive
The URL must point to the RPAS Web Launch
Web server instance, for example:
"http://mspdev43.us.oracle.com:7777/RPAS4/"
archive
Applet archive file name
mdap.jar
mayscript
Enable JavaScript
interaction
NA
The following parameters are used to control the behavior of the RWL Applet:
Table 16–2
Parameters Used to Control the Behavior of the RWL Applet
Parameter
Description
Required
Example
AutoStart
Launch the client automatically Yes
when the applet starts. Must be
set to false for ICL.
Must be set to false if the
launch is initiated by
JavaScript code.
defaultInstallDi
r
Default installation location for No
the RPAS client. The client
version number is
automatically appended to the
end of this string.
C:\Oracle RPAS Client
Debug
Debug flag. If true, more
logging information is printed
in the Java Console of the web
browser.
No
true
launchPreinstall Launch the preinstalled RPAS No
edOnly
client only. Do not install an
RPAS client. The preinstalled
path is determined by the
server side setting in the
configuration file clientPath.txt.
For more information, refer to
the RPAS Installation Guide.
false
supportMultiple Support multiple RPAS client
Versions
versions on the same
workstation. Must be set to
true for ICL.
Yes
Must be set to true.
WebLaunchBase The URL for the Web Launch
Servlet. If not specified, the
applet will generate a URL by
appending "/web" to it's
codebase property.
No
http://mspdev43.us.oracle.
com:7777/RPAS4/web
It is recommended that the applet is embedded with the height and width set to zero.
When the height and width are set to non-zero values, a text area is shown that gets
updated with status information from the RPAS client.
In-Context Launch
16-3
Launching RPAS
The following figure shows the applet UI if the RWL Applet is embedded in the web
page with non-zero width and height. The message window in the applet is updated
with status information from the RPAS client. Status information includes the success
or failure of building or opening a workbook and any error messages returned by
RPAS.
It is assumed that when using non-zero height and width, system integrators
appropriately size the applet in order for the UI to be user-friendly. For example, a
width and height of 5 is unrealistic for any user interface returning messages to the
end-user.
Figure 16–1 UI of the RWL Applet when Height and Width Values are Non-zero
Using JavaScript with the RWL Applet
System integrators embed the RWL Applet in an HTML web page. The launch context
can be passed to the applet by the JavaScript-enabled active content of the web page.
Real-time status is passed back. The communication between the applet and the active
content is achieved by a JavaScript invocation of an applet method.
To launch an instance of an RPAS client, the active content makes a JavaScript call:
document.appletName.launchRPASClient(id, xmlstring [, user, password]);
■
id - RPAS client process identifier, which can be any string.
16-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
■
xmlstring - launch context in XML format encoded by Base64 scheme. Base64
encoding is a popular scheme used in e-mail contents, readily available in
JavaScript public domain source code.
For purposes of quick manual testing or prototyping, the MIME Tools plug-in in
Notepad++ 4.8.5 and above may be used to encode any text to Base64 and back.
■
user and password - optional arguments. For details on ICL supported
mechanisms for user authentication, see the User Authentication section.
The applet notifies active content regarding the status of the RPAS client through a
JavaScript callback function. The following JavaScript function may be defined if a
custom callback is desired:
function RPASStatusListener(id, code, message)
{
…
}
■
id - same RPAS client process identifier previously passed by the
launchRPASClient()call.
■
code - status code (0 - success, 1 - failure, -1 - applet exception)
■
message - a descriptive status message.
If the callback function is not defined, RWL Applet displays status messages on the
status bar of the browser in the following format: "id - [OK|Error|Exception] message".
The following figure shows the interactions between Active Content, RWL Applet, and
RPAS client processes. Note that one embedded RWL applet can be invoked multiple
times using JavaScript to launch multiple RPAS client processes using different context
XML data. The figure shows the case where two RPAS client processes are launched.
Figure 16–2 Two RPAS Clients Being Launched
Since the status listener function RPASStatusListener(id, code, message)
can be invoked multiple times by multiple status listener threads in the applet, the
JavaScript developer should use the function id argument to identify where the status
message came from and act accordingly.
In-Context Launch
16-5
Launching RPAS
The web page must stay active to enable the communication between the RPAS client
processes and RWL Applet. The web page can become inactive, for example, if the
user clicks the Back button of the web browser or closes the active tab or window.
If the web page becomes inactive, the communication channel between the applet and
client process is terminated and cannot be recovered. If this happens, the RPAS client
process becomes orphaned and then acts like a regular RPAS client. It will continue to
function, but its status will not be displayed on the web page.
The following sample code demonstrates the integration of RWL Applet and
JavaScript-enabled active content. Note that the width and height of the applet are set
to zero so that the applet is hidden on the web page. The JavaScript function
launchRPASClient() simply invokes the corresponding applet method. The status
callback function RPASStatusListener() is implemented to display the status
information in the web browser status bar that is generally at the bottom of the
browser window.
<HTML>
<HEAD>
<META http-equiv=Content-Type content="text/html; charset=UTF-8">
<TITLE>Launch RPAS Client</TITLE>
</HEAD>
<SCRIPT>
var idcomplete = "BuildComplete";
var xmlcomplete =
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiID8+DQo8UlBBU0xh\
dW5jaENvbnRleHQ+ICAgDQo8U2VydmVyPg0KCTxkZXNjcmlwdGlvbj5UZXN0RG9t\
YWluPC9kZXNjcmlwdGlvbj4NCiAgICA8cHJvZmlsZT5mYWxzZTwvcHJvZmlsZT4N\
Cgk8ZGVidWc+ZmFsc2U8L2RlYnVnPg0KICAgIDxkYkRhZW1vblBvcnQ+MTIzNDg8\
L2RiRGFlbW9uUG9ydD4NCgk8ZGJTZXJ2ZXJIb3N0TmFtZT5tc3BkZXY0My51cy5v\
cmFjbGUuY29tPC9kYlNlcnZlckhvc3ROYW1lPg0KCTxkYlNlcnZlclBvcnRTdGFy\
dD4xMDI1PC9kYlNlcnZlclBvcnRTdGFydD4NCgk8ZGJTZXJ2ZXJQb3J0RW5kPjY1\
NTM1PC9kYlNlcnZlclBvcnRFbmQ+DQoJPGRlZmF1bHREYlVzZXIgLz4NCgk8ZGVm\
YXVsdERiUGFzc3dvcmQgLz4NCgk8ZG9tYWluUm9vdERpcmVjdG9yeSAvPg0KPC9T\
ZXJ2ZXI+DTxDbGllbnQ+DSAgIDx2ZXJzaW9uPjEzLjEuMDwvdmVyc2lvbj4NPC9D\
bGllbnQ+DQo8RG9tYWluPg0KCTxkZXNjcmlwdGlvbj5UZXN0RG9tYWluPC9kZXNj\
cmlwdGlvbj4NCgk8ZGlyZWN0b3J5TmFtZT4vdm9sLm5hcy9ycGFzX3NlL2h1YW5n\
bWEvZG9tYWlucy9UZXN0RG9tYWluPC9kaXJlY3RvcnlOYW1lPg0KICAgPHVzZXI+\
YWRtPC91c2VyPg0KCTxwYXNzd29yZD5hZG08L3Bhc3N3b3JkPg0KPC9Eb21haW4+\
DQo8V29ya2Jvb2s+DQoJPGJ1aWxkPg0KCQk8dGVtcGxhdGVOYW1lPk1FQVNVUkVB\
TkFMWVNJUzwvdGVtcGxhdGVOYW1lPg0KCQk8V2l6YXJkUGFnZXM+DQoJCQk8V2l6\
YXJkUGFnZSBpZD0iRXh0cmFNZWFzdXJlc1BhZ2UiIGZhbGxiYWNrPSJub25lIj4N\
CgkJCQk8TGlzdGJveCBuYW1lPSJsYjEiPg0KCQkJCQk8dmFsdWU+DQoJCQkJCQk8\
c2VsZWN0aW9uPlJfRVhfREVNT0E8L3NlbGVjdGlvbj4NCiAgICAgICAgICAgICAg\
ICAgIDxzZWxlY3Rpb24+Ul9FWF9ERU1PQjwvc2VsZWN0aW9uPg0KICAgICAgICAg\
ICAgICAgICAgPHNlbGVjdGlvbj5SX0VYX0RFTU9DPC9zZWxlY3Rpb24+DQoJCQkJ\
CTwvdmFsdWU+DQoJCQkJPC9MaXN0Ym94Pg0KCQkJPC9XaXphcmRQYWdlPg0KCQkJ\
PFdpemFyZFBhZ2UgaWQ9IkRBWSIgZmFsbGJhY2s9Im5vbmUiPg0KCQkJCTxTdXBl\
clRyZWUgbmFtZT0idHJlZTEiIGZhbGxiYWNrPSJhbGwiPg0KCQkJCQk8dmFsdWU+\
DQoJCQkJCQk8ZGltIG5hbWU9IldFRUsiPg0KCQkJCQkJCTxzZWxlY3Rpb24+VzAx\
XzE5OTc8L3NlbGVjdGlvbj4NCgkJCQkJCQk8c2VsZWN0aW9uPlcwMV8xOTk4PC9z\
ZWxlY3Rpb24+DQoJCQkJCQkJPHNlbGVjdGlvbj5XMDFfMTk5OTwvc2VsZWN0aW9u\
Pg0KCQkJCQkJCTxzZWxlY3Rpb24+VzAxXzIwMDA8L3NlbGVjdGlvbj4NCgkJCQkJ\
CTwvZGltPg0KCQkJCQkJPGRpbSBuYW1lPSJEQVkiPg0KCQkJCQkJCTxzZWxlY3Rp\
b24+MTk5NzAxMDg8L3NlbGVjdGlvbj4NCgkJCQkJCTwvZGltPg0KCQkJCQk8L3Zh\
bHVlPg0KCQkJCQk8ZGVmYXVsdD4NCgkJCQkJCTxkaW0gbmFtZT0iREFZIj4NCgkJ\
CQkJCQk8c2VsZWN0aW9uPjE5OTcwMTA4PC9zZWxlY3Rpb24+DQoJCQkJCQk8L2Rp\
bT4NCgkJCQkJPC9kZWZhdWx0Pg0KCQkJCTwvU3VwZXJUcmVlPg0KCQkJPC9XaXph\
cmRQYWdlPg0KCQkJPFdpemFyZFBhZ2UgaWQ9IlNUUiIgZmFsbGJhY2s9Im5vbmUi\
Pg0KCQkJCTxTdXBlclRyZWUgbmFtZT0idHJlZTEiPg0KCQkJCQk8dmFsdWU+DQoJ\
16-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
CQkJCQk8ZGltIG5hbWU9IlNUUiI+DQoJCQkJCQkJPHNlbGVjdGlvbj4wMTAyPC9z\
ZWxlY3Rpb24+DQoJCQkJCQkJPHNlbGVjdGlvbj4wMTQ0PC9zZWxlY3Rpb24+CQkJ\
CQkJDQoJCQkJCQkJPHNlbGVjdGlvbj4wMTUyPC9zZWxlY3Rpb24+CQkJCQkJDQoJ\
CQkJCQkJPHNlbGVjdGlvbj4wNTU3PC9zZWxlY3Rpb24+CQkJCQkJDQoJCQkJCQkJ\
PHNlbGVjdGlvbj4wNTk0PC9zZWxlY3Rpb24+CQkJCQkJDQoJCQkJCQkJPHNlbGVj\
dGlvbj4wOTU5PC9zZWxlY3Rpb24+CQkJCQkJDQoJCQkJCQk8L2RpbT4NCgkJCQkJ\
PC92YWx1ZT4NCgkJCQk8L1N1cGVyVHJlZT4NCgkJCTwvV2l6YXJkUGFnZT4NCgkJ\
CTxXaXphcmRQYWdlIGlkPSJTS1UiIGZhbGxiYWNrPSJub25lIj4NCgkJCQk8U3Vw\
ZXJUcmVlIG5hbWU9InRyZWUxIj4NCgkJCQkJPHZhbHVlPg0KCQkJCQkJPGRpbSBu\
YW1lPSJDTFNTIj4NCgkJCQkJCQk8c2VsZWN0aW9uPjAyMTwvc2VsZWN0aW9uPg0K\
CQkJCQkJPC9kaW0+DQoJCQkJCTwvdmFsdWU+DQoJCQkJPC9TdXBlclRyZWU+DQoJ\
CQk8L1dpemFyZFBhZ2U+DQoJCTwvV2l6YXJkUGFnZXM+DQoJCTxzYXZlPg0KCQkJ\
PGxhYmVsPlRlc3R3YjwvbGFiZWw+DQoJCQk8YWNjZXNzPkdyb3VwPC9hY2Nlc3M+\
DQoJCQk8Z3JvdXA+QURNSU48L2dyb3VwPg0KCQk8L3NhdmU+DQoJPC9idWlsZD4N\
CjwvV29ya2Jvb2s+DQo8L1JQQVNMYXVuY2hDb250ZXh0Pg0K";
function launchRPASClient(id, xmlstring)
{
document.LaunchApplet.launchRPASClient(id, xmlstring);
}
function RPASStatusListener(id, code, message)
{
status = id + " - Status: code(" + code + ") message(" + message + ")";
}
</SCRIPT>
<BODY>
<CENTER>
<H3>Launch RPAS Client</H3>
Click on the button to launch RPAS client and build a new workbook!
<P>
<INPUT type="button" value="Build A New Measure Analysis Workbook"
onClick = "launchRPASClient(idcomplete, xmlcomplete)">
<APPLET name="LaunchApplet"
code="com.retek.mdap.client.launch.LaunchApplet.class"
codebase="http://mspdev43.us.oracle.com:7777/RPAS4/"
archive="mdap.jar"
align="center" width="0" height="0" mayscript VIEWASTEXT>
<PARAM name="AutoStart" value="false">
<PARAM name="supportMultipleVersions" value="true">
<PARAM name="launchPreinstalledOnly" value="false">
<PARAM name="Debug" value="true">
<PARAM name="defaultInstallDir" value="C:\Oracle RPAS Client">
Your web browser is not currently Java-enabled.
</APPLET>
</CENTER>
</BODY>
</HTML>
In-Context Launch
16-7
Launching RPAS
The following figure shows this sample code rendered by a web browser. Note that the
status bar shows the current status of the RPAS client.
Figure 16–3 Example HTML Code Rendered by a Web Browser
User Authentication
This section describes Oracle Single Sign-On (OSSO) and non-OSSO authentication of
users.
OSSO-Based Authentication
If the HTML active content is protected by OSSO, it can be assumed that the user has
already been authenticated when the applet is started. However, it cannot be assumed
that the user has the privileges to launch the RPAS client. The privileges can only be
confirmed by RWL Servlet. The applet, therefore, makes a query to the servlet to
confirm the privileges of the user before launching the RPAS client.
When OSSO is being used, a user name and password is not needed and should not be
used for the call to document.appletName.launchRPASClient(). System
integrators should rely on OSSO credentials and mechanisms to authenticate the user.
16-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
The following figure shows the flow of OSSO support for ICL.
Figure 16–4 OSSO Support Flowchart for ICL
Non-OSSO Authentication
When OSSO is not used, the authentication for the RPAS client login is done by RPAS
itself. There are several ways to pass user credentials, user name and password, to the
RPAS client through the RWL Applet:
■
Directly embed the user name and password in the XML data. The domain section
of launch context can contain user and password information.
This may pose a security issue depending on the lifecycle of
the launch contextual data.
Note:
■
■
Do not pass the user name and password to the applet. The RPAS client will
prompt the user to log in every time the client starts. This may be inconvenient,
but may be acceptable if only one RPAS session is needed.
Use JavaScript code to pass in the user name and password in the applet method
call launchRPASClient(id, xmlstring, user, password). The user
name and password can be obtained from the user input fields of the web page.
The user only needs to enter the user name and password once for one browser
session. Multiple RPAS client sessions can then be launched without entering the
user name and password again.
In-Context Launch
16-9
Launching RPAS
Deploying In-Context Launch
The following diagram shows how an RPAS In-Context Launch enabled application is
deployed. Note that the RPAS Web Launch Servlet has to be deployed on a web server.
This web server does not have to be the same as the web server that is used for any
reporting, dashboard or BAM applications. In this release, RPAS ICL is able to interact
with the dynamic content of the web page using mechanisms described in the
previous sections. As long as system integrators can ensure that the RPAS Web Launch
Servlet is available, ICL can be achieved from any web-based application.
Figure 16–5 ICL Deployment Diagram
Use Cases
This section lists some use cases.
Launching without Context
A system integrator may want to launch RPAS without any context. This means
starting up an RPAS client and logging on automatically, but without opening or
building a workbook. This type of launch is required to support a generic link in the
navigation pane where an end-user can simply launch RPAS to do planning using
RPAS Today. The navigation pane only serves as a launchpad for RPAS where RPAS
can be started and logged into by clicking a static link or button.
To code this type of launch, the user must either remove the <Workbook> tag from
the context or ensure that the <Workbook> tag does not include an <open> or
<build> request.
Launching With Context
An RPAS launch that includes more than a simple login into RPAS is considered an
in-context launch. This includes launching an RPAS client to open an existing
workbook or build a workbook given the template and wizard parameters.
16-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
Opening an Existing Workbook
A system integrator may want to design an application that opens a pre-built
workbook. This workbook may have been built by a system integrator, the user,
workbook build batch, or previous in-context launch request.
It is assumed that system integrators are aware of either the internal, unique workbook
name that RPAS uses or the workbook label, and optionally, the template name and
creation datetime of the workbook. These parameters can be specified in the XML
context specification to have RPAS open the workbook. For information, see the "Open
Workbook" section.
To enable opening the latest workbook from a nightly auto-workbook-build batch,
system integrators can provide the label and template name. ICL will automatically
default to the latest workbook of the same label.
The last workbook that was created is opened; not the last
workbook that was modified.
Note:
Building a New Workbook
A system integrator may want to ensure that a new workbook is built for the end-user
depending on what the end-user is or has been doing in the web application. The
following examples illustrate this concept.
■
■
If a link for "Merchandise Financial Planning" is clicked in the navigation pane,
RPAS is launched to build a workbook for the "Merchandise Financial Planning"
template. The end-user is required to make all the wizard selections.
If the user is navigating a report and had drilled down to identify some outliers at
the SKU/Store level, RPAS is launched to automatically build a workbook for
those SKU/Stores without requiring the end-user to reselect them in the wizard.
This can be achieved using the build context detailed in the "Build Workbook" section.
RPAS Launch Context Format
The launch context is described in XML format. It consists of four components: client,
server, domain, and workbook.
■
The client component identifies the RPAS client to be launched. It is needed to
support multiple client versions on the same workstation.
■
The server component identifies the server to connect to.
■
The domain component identifies the domain to log in to.
■
The workbook component contains information for opening or building a
workbook.
In-Context Launch
16-11
Launching RPAS
Client Settings
Table 16–3
Client Settings
Setting
Description
Type
version
String
RPAS client version number. RPAS Web
Launch supports multiple client versions. This
version number is used to determine which
client binary will be launched. If not specified,
the default client for RPAS Web Launch is
used.
Required
No
allowConcurrent Allow the same user to open multiple
Sessions
concurrent RPAS client sessions connecting to
the same domain without prompting for
confirmation.
Boolean
No
sslWalletLocatio The absolute path to the Oracle wallet for the
n
Classic Client.
String
No
Type
Required
Server Settings
Table 16–4
Server Settings
Setting
Description
description
Descriptive name for this server configuration. String
No
profile
Enable profiling for the RPAS client.
Boolean
No
debug
Enable debug logging for the RPAS client.
Boolean
No
dbDaemonPort
The port number of DomainDaemon.
Integer
Yes
dbServerHostN
ame
The host name where DomainDaemon is
running.
Integer
Yes
dbServerPortSta The starting port number of the RpasDbServer Integer
rt
listening port range.
No
dbServerPortEn The ending port number of the RpasDbServer
d
listening port range.
Integer
No
defaultDbUser
String
No
defaultDbPassw The encrypted password for the default user
ord
ID.
String
No
domainRootDir
ectory
String
No
The default user ID for RpasDbServer.
The root directory of RPAS domains. If
specified, it is prepended to the
directoryName in Domain Settings.
Domain Settings
Table 16–5
Domain Settings
Setting
Description
Type
Required
description
Descriptive name for this domain
configuration. It is displayed as the title of the
RPAS client main window.
String
Yes
directoryName
The domain path.
String
Yes
16-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
Table 16–5 (Cont.) Domain Settings
Setting
Description
Type
Required
user
The user ID used to log in. If not specified, a
login dialog prompts for user input.
String
No
password
The encrypted password for the user ID. If not String
specified, a login dialog prompts for user
input.
No
Workbook Settings
The Workbook section has two options to open or build a workbook. If the options or
the whole Workbook section is not specified, the RPAS client logs in to the domain
without any workbook operation. For information on opening a workbook, see the
Open Workbook section. For information on building workbook, see the Build
Workbook section.
XML Schema
The following is the full schema for RPAS Launch Context.
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:complexType name="BooleanDataType">
<xs:sequence>
<xs:element name="value" type="xs:boolean" />
<xs:element name="default" type="xs:boolean" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="fallback" type="xs:string" use="optional" />
</xs:complexType>
<xs:complexType name="StringDataType">
<xs:sequence>
<xs:element name="value" type="xs:string" />
<xs:element name="default" type="xs:string" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="fallback" type="xs:string" use="optional" />
</xs:complexType>
<xs:complexType name="SelectionType">
<xs:sequence>
<xs:element name="selection" type="xs:string" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="StringSetDataType">
<xs:sequence>
<xs:element name="value" type="SelectionType" />
<xs:element name="default" type="SelectionType" minOccurs="0" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="fallback" type="xs:string" use="optional" />
</xs:complexType>
<xs:complexType name="StringVectorDataType">
<xs:sequence>
In-Context Launch
16-13
Launching RPAS
<xs:element name="value" type="SelectionType" />
<xs:element name="default" type="SelectionType" minOccurs="0" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="fallback" type="xs:string" use="optional" />
</xs:complexType>
<xs:complexType name="DimDataType">
<xs:sequence>
<xs:element name="dim" maxOccurs="unbounded">
<xs:complexType>
<xs:complexContent>
<xs:extension base="SelectionType">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PQDDataType">
<xs:sequence>
<xs:element name="pqd">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="type" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
name="Checkbox" type="BooleanDataType" />
name="RadioButton" type="BooleanDataType" />
name="DatePicker" type="StringDataType" />
name="DropDownList" type="StringDataType" />
name="Edit" type="StringDataType" />
name="Listbox" type="StringSetDataType" />
name="SingleHierSelect" type="StringVectorDataType" />
name="Tree" type="StringSetDataType" />
<xs:element name="SuperTree">
<xs:complexType>
<xs:choice>
<xs:sequence>
<xs:element name="value" type="DimDataType"/>
<xs:element name="default" type="DimDataType" minOccurs="0" />
</xs:sequence>
<xs:sequence>
<xs:element name="value" type="PQDDataType"/>
<xs:element name="default" type="PQDDataType" minOccurs="0" />
</xs:sequence>
</xs:choice>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="fallback" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
16-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
<xs:element name="open">
<xs:complexType>
<xs:choice>
<xs:element name="name" type="xs:string" />
<xs:sequence>
<xs:element name="label" type="xs:string"/>
<xs:element name="templateName" type="xs:string" minOccurs="0"/>
<xs:element name="createdTime" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="build">
<xs:complexType>
<xs:sequence>
<xs:element name="templateName" type="xs:string" />
<xs:element name="allowManualOverride" type="xs:boolean" minOccurs="0"/>
<xs:element name="customErrorMessage" type="xs:string" minOccurs="0"/>
<xs:element name="customWaitMessage" type="xs:string" minOccurs="0"/>
<xs:element réf="WizardPages" />
<xs:element réf="save" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="save">
<xs:complexType>
<xs:sequence>
<xs:element name="label" type="xs:string" />
<xs:element name="access" type="xs:string" minOccurs="0"/>
<xs:element name="group" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="WizardPage">
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element ref="Checkbox" />
<xs:element ref="DatePicker" />
<xs:element ref="DropDownList" />
<xs:element ref="Edit" />
<xs:element ref="Listbox" />
<xs:element ref="RadioButton" />
<xs:element ref="SingleHierSelect" />
<xs:element ref="SuperTree" />
<xs:element ref="Tree" />
</xs:choice>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required" />
<xs:attribute name="option" type="xs:string" use="optional" />
<xs:attribute name="fallback" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
<xs:element name="WizardPages">
<xs:complexType>
In-Context Launch
16-15
Launching RPAS
<xs:sequence>
<xs:element ref="WizardPage" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Client">
<xs:complexType>
<xs:sequence>
<xs:element name="version" type="xs:string" />
<xs:element name="allowConcurrentSessions" type="xs:boolean"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Server">
<xs:complexType>
<xs:sequence>
<xs:element name="description" type="xs:string" />
<xs:element name="profile" type="xs:boolean" />
<xs:element name="debug" type="xs:boolean" />
<xs:element name="dbDaemonPort" type="xs:integer" />
<xs:element name="dbServerHostName" type="xs:string" />
<xs:element name="dbServerPortStart" type="xs:integer" />
<xs:element name="dbServerPortEnd" type="xs:integer" />
<xs:element name="defaultDbUser" type="xs:string" />
<xs:element name="defaultDbPassword" type="xs:string" />
<xs:element name="domainRootDirectory" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Domain">
<xs:complexType>
<xs:sequence>
<xs:element name="description" type="xs:string" />
<xs:element name="directoryName" type="xs:string" />
<xs:element name="user" type="xs:string" minOccurs="0"/>
<xs:element name="password" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Workbook">
<xs:complexType>
<xs:choice>
<xs:element ref="open" />
<xs:element ref="build" />
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="RPASLaunchContext">
<xs:complexType>
<xs:sequence>
<xs:element ref="Client" />
<xs:element ref="Server" />
<xs:element ref="Domain" />
<xs:element ref="Workbook" minOccurs="0"/>
16-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Open Workbook
In any retail planning scenario, a particular workbook or, more likely, an auto-build
workbook may be used to plan for a specific grouping of products and locations.
When reacting to an event or alert related to these products and locations, it may be
necessary to always open a particular workbook or auto-build workbook. System
integrators configuring an application can configure and code an in-context opening of
the specific workbook.
System integrators can programmatically specify the parameters that RPAS needs to
open a pre-built workbook. Programmatically does not imply the use of an API, but
implies program application logic that constructs the XML specification that ICL can
use to identify and open the desired workbook.
System integrators can identify the target workbook by either of the following ways:
■
■
By the RPAS name of the workbook.
By the auto-build parameters, that is, user, template name, label, and creation date.
Template name and creation date are optional parameters. If template name or
creation date are not specified and multiple workbooks with the same label are
found, RPAS chooses the workbook that was created last and then further breaks
the tie based on alphabetical ordering of the template name.
Specifications
There are two options that can be specified when a workbook is opened.
Option 1
Table 16–6
Option 1- Workbook Specification
Setting
Description
Type
Required
name
The RPAS name of the workbook, such as
"t1" and "t18" which is the root directory
name of the workbook)
String
Yes
Option 2
Table 16–7
Option 1- Workbook Specification
Setting
Description
Type
Required
label
The workbook label
String
Yes
templateName
The template name of the workbook
String
No
createdTime
The created time of the workbook in the
format YYYY-MM-DD hh:mm:ss
String
No
In-Context Launch
16-17
Launching RPAS
Examples
Here is sample launch context for opening a workbook by RPAS name:
<?xml version="1.0" encoding="UTF-8" ?>
<RPASLaunchContext>
<Server>
<description>TestDomain</description>
<profile>false</profile>
<debug>false</debug>
<dbDaemonPort>12348</dbDaemonPort>
<dbServerHostName>mspdev43.us.oracle.com</dbServerHostName>
<dbServerPortStart>1025</dbServerPortStart>
<dbServerPortEnd>65535</dbServerPortEnd>
<defaultDbUser />
<defaultDbPassword />
<domainRootDirectory /></Server>
<Client>
<version>13.2</version></Client>
<Domain>
<description>TestDomain</description>
<directoryName>/vol.nas/rpas_se/huangma/domains/TestDomain</directoryName>
<user>adm</user>
<password>…</password>
</Domain>
<Workbook>
<open>
<name>t1</name>
</open>
</Workbook>
</RPASLaunchContext>
Here is sample launch context for opening a workbook by label and template name:
<RPASLaunchContext>
… … (Same as above, omitted here.)
<Workbook>
<open>
<label>wb2</label>
<templateName>MEASUREANALYSIS</templateName>
</open>
</Workbook>
</RPASLaunchContext>
16-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
Build Workbook
RPAS users generally build workbooks through a manual process using RPAS Wizard
Pages from workbook templates. This process is automated in ICL by specifying the
contents and selections of the wizard pages in the launch context.
The automated process enables system integrators to programmatically specify the
parameters that RPAS needs to build a new workbook. The integrator can program
RPAS web launch to build virtually any workbook from any workbook templates,
simple or complex, by constructing an XML string according to the launch context
schema and the configuration of the wizard pages.
Users can think of the XML specifications as macro definitions of what they do when
they build the same workbook manually. The specifications for building workbook
start from a workbook template, which contains a list of wizard pages. Each wizard
page has a set of pre-defined widgets:
■
RadioButton
■
Checkbox
■
Edit
■
DropDownList
■
SingleHierSelect
■
DatePicker
■
Listbox
■
Tree
■
SuperTree
Each widget has its own specifications depending on its type.
The fallback option can be specified on the widget and wizard page level. The widget
level fallback option is considered first when the specifications for that widget are
incomplete or incorrect. If a specification cannot be resolved on the widget level, the
wizard page fallback option is used. If the fallback option on the wizard page is not
specified or the option has errors, an error message is displayed to the user.
If any unrecoverable errors occur on a wizard page, the workbook build process falls
back to manual mode if the allowManualOverride option is set to true. The wizard
starts from the first page. All selections prior to the problematic page are preserved
and the user can click Next to skip them and go to the page with errors, which is blank
along with all subsequent pages.
Specifications
The specifications to build a workbook consist of basic settings and a list of wizard
pages. Each wizard page contains a list of widget specifications.
Table 16–8
Basic Settings
Setting
Description
Type
Required
templateName
The template name for the workbook to be
built.
String
Yes
Boolean
No
allowManualOv Allow manual override in case of fatal errors
erride
in the XML data. The default is true. The
wizard starts from the first page.
In-Context Launch
16-19
Launching RPAS
Table 16–8 (Cont.) Basic Settings
Setting
Description
Type
Required
customErrorMe
ssage
Custom error message to display in case of
fatal errors in the launch context data.
String
No
customWaitMes Custom wait message to display while the
sage
workbook is being built.
String
No
Table 16–9
Wizard Page Specifications
Setting
Description
Type
Required
option
(attribute)
Wizard page handling option. Can be one of
the following values:
String
No
Wizard page level fall back option. Can be one String
of the following values:
No
"manual": forces manual selection for all
widgets. This option forces manual input for
this and all subsequent pages. However, the
wizard still starts from the first page.
"skippable": this page can be skipped.
Normally used for a conditional wizard page.
This page only exists if some particular value
is selected for some widget on the previous
page.
fallback
(attribute)
"default": use values from the default settings
for all widgets.
"cache": use selections from the cache selection
file. Cache files are from last successful
workbook build of the same template.
Table 16–10
Wizard Widget Specifications
RadioButton and Checkbox
Setting
Type
Required
name (attribute) Widget name.
String
Yes
fallback
(attribute)
Widget level fallback option. Can be:
String
No
value
Boolean type: selected value for the widget.
Value must be either "false" or "true".
XML section
Yes
default
Default value for the widget. Must be a
Boolean type.
XML section
No
Type
Required
name (attribute) Widget name.
String
Yes
fallback
(attribute)
Widget level fallback option. Can be:
String
No
value
String type: selected value for the widget.
XML section
Yes
Table 16–11
Description
"default": use value from the default setting.
Wizard Widget Specifications (2)
Edit, DropDownList, SingleHierSelect, and DatePicker
Setting
Description
"default": use value from the default setting.
16-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
Table 16–11
(Cont.) Wizard Widget Specifications (2)
Edit, DropDownList, SingleHierSelect, and DatePicker
Setting
Description
Type
Required
default
Default value for the widget. Must be a String
type.
XML section
No
Type
Required
name (attribute) Widget name.
String
Yes
fallback
(attribute)
String
No
Table 16–12
Wizard Widget Specifications (3)
Listbox and Tree
Setting
Description
Widget level fall back option. Can be one of
the following values:
■
■
■
"default": use value from the default
setting.
"all": select all available items or
positions.
"intersection": use intersection of the
specified items/positions and all
available items/positions if any of the
specified items/positions do not exist.
value
String Set type: selected value for the widget.
Value is a set of selections.
XML section
Yes
default
Default value for the widget. Must be a String
type.
XML section
No
Type
Required
name (attribute) Widget name.
String
Yes
fallback
(attribute)
String
No
XML section
Yes
Table 16–13
Wizard Widget Specifications (4)
SuperTree
Setting
Description
Widget level fall back option. Can be one of
the following values:
■
■
■
value
"default": use value from the default
setting.
"all": select all available items or
positions.
"use intersection of specified positions
and all available positions if any of the
specified positions do not exist.
String to String Set Map Type/PQD File Type:
selected value for the widget. Can be one of
the following values:
■
■
Value is one or more dimensions, each
having a set of selections.
Value is a Position Query Definition
(PQD) file name in the format: <pqd
type="{pqd_type}"> pqd_file_name
</pqd> where {pqd_type} must be either
PointAndClickPQD or
RollingCalendarPQD.
In-Context Launch
16-21
Launching RPAS
Table 16–13
(Cont.) Wizard Widget Specifications (4)
SuperTree
Setting
Description
Type
Required
default
Default value for the widget. Must be a String
to String Set Map type or PQD file type.
XML section
No
Workbook Save Specifications
These save specifications are optional. If specified, the workbook is immediately saved
after it is built.
Table 16–14
Workbook Save Specifications
Setting
Description
Type
Required
label
Workbook label.
String
Yes
access
Workbook access. Must be "user", "group" or
"world". If not specified, the default is "user".
String
No
group
Workbook group. Required when workbook
access is "group". There is no default.
String
Conditional
String
No
customWaitMes Custom wait message to display while the
sage
workbook is being built.
Example
The following example shows a sample launch context for building a workbook. It
specifies a new "Measure Analysis" workbook for a simple domain ("TestDomain").
The domain is created by using the RPAS utility createRpasDomain with the command
line option "-x".
<?xml version="1.0" encoding="UTF-8" ?>
<RPASLaunchContext>
<Client>
<version>13.2</version>
</Client>
<Server>
<description>mspdev43-65535</description>
<profile>false</profile>
<debug>false</debug>
<dbDaemonPort>12348</dbDaemonPort>
<dbServerHostName>mspdev43.us.oracle.com</dbServerHostName>
<dbServerPortStart>1025</dbServerPortStart>
<dbServerPortEnd>65535</dbServerPortEnd>
<defaultDbUser />
<defaultDbPassword />
<domainRootDirectory />
</Server>
<Domain>
<description>TestDomain</description>
<directoryName>/vol.nas/rpas_se/domains/TestDomain</directoryName>
</Domain>
<Workbook>
<build>
<templateName>MEASUREANALYSIS</templateName>
<WizardPages>
<WizardPage id="ExtraMeasuresPage" fallback="none">
<Listbox name="lb1">
16-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Launching RPAS
<value>
<selection>R_EX_DEMOA</selection>
<selection>R_EX_DEMOB</selection>
<selection>R_EX_DEMOC</selection>
</value>
</Listbox>
</WizardPage>
<WizardPage id="DAY" fallback="none">
<SuperTree name="tree1" fallback="all">
<value>
<dim name="WEEK">
<selection>W01_1997</selection>
<selection>W01_1998</selection>
<selection>W01_1999</selection>
<selection>W01_2000</selection>
</dim>
<dim name="DAY">
<selection>19970108</selection>
</dim>
</value>
<default>
<dim name="DAY">
<selection>19970108</selection>
</dim>
</default>
</SuperTree>
</WizardPage>
<WizardPage id="STR" fallback="none">
<SuperTree name="tree1">
<value>
<dim name="STR">
<selection>0102</selection>
<selection>0144</selection>
<selection>0152</selection>
<selection>0557</selection>
<selection>0594</selection>
<selection>0959</selection>
</dim>
</value>
</SuperTree>
</WizardPage>
<WizardPage id="SKU" fallback="none">
<SuperTree name="tree1">
<value>
<dim name="CLSS">
<selection>021</selection>
</dim>
</value>
</SuperTree>
</WizardPage>
</WizardPages>
<save>
<label>Testwb</label>
<access>Group</access>
<group>ADMIN</group>
</save>
</build>
</Workbook>
</RPASLaunchContext>
In-Context Launch
16-23
Launching RPAS
buildWorkbookContext Utility
The buildWorkbookContext utility is a server side command line utility. It runs
under both global domains and local domains.
Before running this utility, you should first manually create a workbook using the
workbook template you intend to use in the context. This step generates selection files.
In order to capture as much information as possible in the selection files, you can
choose to select all for the widgets on wizard pages. This is especially useful for listbox
widgets.
After the XML file is generated, you can use the data in the file directly if you want to
build an identical workbook. Or, you can use it as a starting point and tailor it to meet
some specific requirements.
buildWorkbookContext Usage
buildWorkbookContext -d [domain_path] -user [user_name] -wbt [wbt_name] -out
[output_file]
■
■
■
■
[domain_path]: The path to the global or local domain.
[user_name]: The username whose selection files are used. This is the user who
has manually run the workbook template wizard.
[wbt_name]: The name of the workbook template for which the XML context is
built. This is the internal name for the template. It can be identified by looking at
the selection files under DOMAIN_PATH/users/[user]/selections. The names of
the selection files are in this format: [templateName]_[wizpageID].sel.
[output_file]: Output file name for the XML context.
16-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
A
Appendix: Curve Administration Guide
A
This chapter provides the details of the utilities used in Curve administration.
curvevalidate
Curvevalidate automatically executes during the domain install, and it can also be
run at any time against a Master or one subdomain. If run against the Master Domain,
it checks the master and all subdomains. If run against a subdomain, it checks the
Master and only the subdomain (not all other subdomains). This function verifies that:
■
Profile and Source intersections and source data are properly defined
■
Profile intersections respect the partition dimension
curvevalidate Usage
curvevalidate -d domainpath [-s]
The following table provides descriptions of the arguments used by the
curvevalidate utility.
Table A–1
Arguments Used by the curvevalidate Utility
Argument
Description
-d domainpath
Path to the domain.
-s
Set defaults.
-debug
This argument causes temporary measures to be retained for
debugging purposes.
-h
Standard information argument to display information about
curvebatch in the terminal screen.
-version
Standard argument that displays version information.
-loglevel
Used to set the logger verbosity level. Available verbosity levels
are as follows:
-noheader
■
all
■
profile
■
information
■
warning
■
error
■
none
Standard argument to disable the use of timestamp header.
Appendix: Curve Administration Guide
A-1
curvevalidate
1.
Each Profile must have at least one Source Level.
2.
For each Profile:
a.
For global domains, ALL intersections {Data Intersection, Profile Intersection,
Stored Intersection, Aggregation Intersection, and Approval Intersection} must
be below the partition (NOT HBI).
b.
Data Intersection (if a data source is specified) must conform to X in {Profile
Intersection, Stored Intersection, Aggregation Intersection, and Approval
Intersection}.
c.
Profile Intersection must conform to the Stored Intersection.
d.
Aggregation Intersection must conform to the Approval Intersection.
e.
Aggregation Intersection must not be below the Approval Intersection.
f.
Aggregation Intersection must be above the Data Intersection (if data source
specified).
g.
If the Aggregation Intersection conforms to Profile Intersection:
- The Profile Type must NOT be diff(8).
- The Aggregation Intersection must be above the Profile Intersection.
- The Aggregation Intersection must be above the Stored Intersection.
h.
If Aggregation Intersection does not conform to Profile Intersection:
- The Profile Type must be Diff (8).
- There must be at least one common hierarchy between the Aggregation
Intersection and X in {Profile Intersection, Stored Intersection}.
- For each common non-PROD hierarchy H of Aggregation Intersection and X
in {Profile Intersection, Stored Intersection}: Aggregation Intersection's H
dimension must not be below X's H dimension.
3.
For each Source Level:
a.
For global domains, ALL intersections {Profile Intersection, Stored
Intersection, and Aggregation Intersection} must be below the partition (NOT
HBI).
b.
Parent Profile's Data Intersection (if data source specified) must conform to X
in {Profile Intersection, Stored Intersection, and Aggregation Intersection}.
c.
Profile Intersection must conform to Stored Intersection.
d.
Aggregation Intersection must be above parent Profile's Data Intersection (if
data source specified).
e.
If Aggregation Intersection conforms to Profile Intersection:
- The Profile Type must NOT be diff(8).
- The Aggregation Intersection must be above the Profile Intersection.
- The Aggregation Intersection must be above the Stored Intersection.
A-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
curvebatch
f.
If Aggregation Intersection does not conform to Profile Intersection:
- The Parent Profile Type must be Diff (8).
- There must be at least one common hierarchy between the Aggregation
Intersection and X in {Profile Intersection and Stored Intersection}.
- For each common non-PROD hierarchy H of Aggregation Intersection and X
in {Profile Intersection and Stored Intersection}: Aggregation Intersection's H
dimension must not be below X's H dimension.
curvebatch
This section provides the details of the curvebatch utility.
curvebatch Usage
curvebatch -d domainpath [-level # ] [-debug] | -h | -version
The following table provides descriptions of the arguments used by the curvebatch
utility.
Table A–2
Arguments Used by the curvebatch Utility
Argument
Description
-d domainpath
Path to the domain.
-level #
The # signifies the profile ID. When using level, a valid profile
ID must be provided.
-debug
This argument causes temporary measures to be retained for
debugging purposes.
-h
Standard information argument to display information about
curvebatch in the terminal screen.
-version
Standard argument that displays version information.
-loglevel
Used to set the logger verbosity level. Available verbosity levels
are as follows:
■
all
■
profile
■
information
■
warning
■
error
■
none
Appendix: Curve Administration Guide
A-3
curvebatch
A-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
B
Appendix: RPAS Test Driver
B
This appendix describes the RPAS Test Driver (RTD).
Support
Support for the RTD library is limited to its basic understanding and usage of the
published XML-based APIs. This library is available on specific versions of the
Windows platform where the RPAS release is officially supported.
Oracle does not provide support for compilation or linkage of this library. Also, Oracle
does not support LoadRunner scripts or any other scripts used to run the rtd.dll
library.
Introduction
This appendix covers the use of rtd.dll provided for the purpose of performance
testing of the Oracle Retail RPAS server.
Audience
This DLL allows a user to create, open, alter, save, commit, and refresh workbooks by
sending commands directly to the RPAS server through an XML structure.
Knowledge of the usage of the Oracle Retail RPAS client is assumed. A user must have
a working domain, which can be connected to with a client. A user must also know the
internal names of dimensions, positions, workbook templates, worksheets, and
windows.
Although the interface provided by this library could be used by any testing tool, it
has most frequently been used with HP LoadRunner. The use of RTD with
LoadRunner is outlined in later sections.
Finding Required Information
The majority of interactions with RTD assume knowledge of names rather than labels.
In order to easily find dimensions and position names, the RPAS client
(foundation.exe) can be made to display the internal names rather than labels.
This is accomplished by adding "ShowPositionNames=1" under the [Options] section
in %windir%\foundation.ini, for example, C:\Windows\foundation.ini. (The
foundation.ini file may be in another location, as described step 3 in the Translation
Administration section.) Then, when building and displaying a workbook, the client
displays position names instead of labels.
Appendix: RPAS Test Driver B-1
Interface
To find template, worksheet, and window names, make a search under your domain's
"repos" directory for files named "tmpl.cfg" with the label (displayed name) of your
template. The template name, worksheet, and window names are contained within
this file.
Compatibility
The version of RTD must be compatible with the RPAS server version. If an RPAS hot
fix or upgrade requires a client update, then it is likely a matching RTD build will be
required. Contact support for further information.
Interface
The C interface provided by the library is simple to interact with, the majority of
interactions being with rtd_send() and rtd_getResponse() functions. The complexity
arises in the messages sent and received by these functions, detailed in the next
section.
To log on to the server:
int rtd_logon(const char* user, const char* password, const char* connection,
const char* domain, const char* fcfPath, const char* language, const char*
logLevel)
Or,
int rtd_logon_ex(const char* user, const char* password, const char* connection,
const char* domain, const char* fcfPath, const char* language, const char*
logLevel, const char* domainRootDirectory)
The following table provides descriptions of the arguments used by int rtd_logon.
Table B–1
Arguments Used by int rtd_logon
Argument
Description
const char* user
User name.
const char* password
User password.
const char*
connection
Connection defined in the .fcf file.
const char* domain
Domain defined in the .fcf file.
const char* fcfPath
Path to the .fcf file.
const char* language
Language of the domain, usually "english". (Currently unused.)
const char* logLevel
Log level of the RPAS server, defaults to "debug" if blank.
const char*
domainRootDirectory
The domain path in foundation.fcf that will be prepended with
this string. This allows the foundation.fcf to specify a relative (or
empty) domain path.
To log off the server:
void rtd_logoff()
To send an XML request to the server:
int rtd_send(const char* request)
B-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Interface
To get the XML response from the server request:
char* rtd_getResponse()
To get a particular property from the response XML tag:
char* rtd_getResponseProperty(const char* property)
To free the char buffer that was allocated by rtd_getResponse() or rtd_
getResponseProperty():
void rtd_freeCharPtr(char*)
Note:
Freeing the char buffer is necessary to prevent memory leaks.
The functions rtd_logon, rtd_logon_ex, and rtd_send indicate success by returning 1
and failure by returning 0.
The following figure shows an example of the expected use of the library. RTD
function calls are indicated in the shaded blocks.
Figure B–1 RTD Example Workflow
Appendix: RPAS Test Driver B-3
XML Requests
XML Requests
This section describes requests that can be sent as XML strings to the server. All tags
and attributes are case-sensitive.
Connection Messages
There are two connection messages.
<Logon>
Description:
Log a user into a domain, alternative to rtd_logon().
Properties:
user, password, connection, domain, fcfPath, logLevel, and language.
<Logoff>
Description:
Log the current user off, alternative to rtd_logoff().
Wizard Messages
The messages below appear in the order in which they are called. They are repeated as
necessary for the wizard pages. The wizard pages can be determined by creating the
same workbook in the client.
<WizardInitialize>
Description:
Start wizard to create a new workbook. Some wizards do not have any wizard pages.
After calling this, call rtd_getResponseProperty("skipDisplay") will be true
if this wizard does not have any wizard pages.
Properties:
templateName - Internal name of the workbook template, as defined in tmpl.cfg.
<GetNextWizardDialog>
Description:
Move to the next page in a wizard. This must be called after <WizardInitialize>
to navigate to the first wizard page. After calling this, call rtd_
getResponseProperty("nextDialog") to return the name of the new wizard
page.
Properties:
templateName - Internal name of the workbook template, as defined in tmpl.cfg.
currentDialog [optional] - Not currently used.
forward - Direction to move the wizard. Values are "true" to go forward or "false" to go
backward, but this should almost always be true.
B-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
XML Requests
<GetWizardLayout>
Description:
Returns the layout of a wizard page. The output will be a tag called <wizardPage>.
Inside that tag is a collection of <control> tags. Each of the <control> tags has
attributes for name, class, windowText, styles, xStart, yStart, width, height, enabled,
data, option, and associations of a control on the wizard page.
Properties:
templateName - Internal name of workbook template, as defined in tmpl.cfg.
currentDialog - Name of wizard page as defined in tmpl.cfg or returned by
<GetNextWizardDialog>.
<SelectPositions>
Description:
Select which positions should be included in the workbook. The <position> child
tags are sent in the same message as the <SelectPositions> tag.
<GetNextWizardDialog> must be called to navigate to the correct wizard page
before calling <SelectPositions>. This is typically used on two-tree wizard pages.
Properties:
templateName - Internal name of workbook template, as defined in tmpl.cfg.
currentDialog - Name of wizard page defined by the template configuration file.
Children:
<position>
Properties:
dimension - Dimension that contains the position.
name - Name of the position.
<SetWizardData>
Description:
This allows explicit control over the UI elements within each page of the wizard. This
enables operations beyond simple workbook builds. This is typically used on custom
wizard pages.
Properties:
templateName - Internal name of workbook template, as defined in tmpl.cfg.
currentDialog - Name of wizard page defined by the template configuration file.
name - UI control name.
class - UI control class.
The control classes include Edit, DropDownList, Listbox, Groupbox, Checkbox,
RadioButton, Text, SingleHierSelect, Tree, SuperTree, DatePicker.
The string "true" or "false" is used set radio buttons and checkboxes.
Appendix: RPAS Test Driver B-5
XML Requests
The following example illustrates this use in the context of AutoWorkbook builds.
<!-- Create the workbook -->
<WizardInitialize templateName="AutoWb" />
<!-- AutoWorkbookPage0 - select action -->
<GetNextWizardDialog templateName="AutoWb" forward="true" />
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage0"
name="addWb" class="RadioButton">true</SetWizardData>
<!-- AutoWorkbookPage1 - select template -->
<GetNextWizardDialog templateName="AutoWb" forward="true" />
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage1"
name="ListBox" class="Listbox">R_TEST</SetWizardData>
<!-- AutoWorkbookPage2 - select owner -->
<GetNextWizardDialog templateName="AutoWb" forward="true" />
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage2"
name="ListBox" class="Listbox">adm</SetWizardData>
<!-- AutoWorkbookPage3 - enter scheduling data -->
<GetNextWizardDialog templateName="AutoWb" forward="true" />
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3"
name="BuildLabel" class="Edit"><value>RTD Auto Build WB</value></SetWizardData>
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3"
name="BuildFrequency" class="Edit">1000</SetWizardData>
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3"
name="NextBuildDate" class="Edit">05/05/2010</SetWizardData>
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3"
name="GroupAccess" class="RadioButton">true</SetWizardData>
<SetWizardData templateName="AutoWb" currentDialog="AutoWorkbookPage3"
name="groupNames" class="Listbox">adm</SetWizardData>
<!-- … workbook build details omitted … -->
<WizardFinish templateName="AutoWb />
<WizardFinish>
Description:
Finish the wizard and build the workbook. After calling this, call rtd_
getResponseProperty("workbookName") to get the internal name of the newly
created workbook. Wizard-only templates do not have a workbookName and often
provide an INFO message. If the workbook cannot be built, an ERROR message is
returned. Use rtd_getResponseProperty("ERROR") to check the error message and
rtd_getResponseProperty("INFO") to check the info message.
Properties:
templateName - Internal name of workbook template, as defined in tmpl.cfg.
B-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
XML Requests
Workbook Messages
After a workbook has been created through the wizard process, it must be opened and
manipulated. These functions do this for any created workbook.
<OpenWorkbook>
Description:
Open an existing workbook.
Properties:
workbookName - Internal name of a stored workbook of the form "txxx" where the x's
represent a variable number of digits. If the workbook was just created by the wizard
process, use the value returned by rtd_getResponseProperty(). See
<WizardFinish> above.
access [optional] - Currently unused.
<Fetch>
Description:
Fetch data from the workbook.
Properties:
workbookName - Internal name of a stored workbook. See <OpenWorkbook> for
more information.
windowName - Internal name of the window on which this measure is located as
defined by tmpl.cfg.
Children:
<WindowContext> - Tag that defines what hierarchies and dimensions would be
visible if there was a screen. At a minimum, the dimensions of the current cell need to
be specified. There should only be one tag per hierarchy.
Properties:
hierarchy - Name of hierarchy.
Children:
<dimension> - Tag that represents the name of a dimension.
Properties:
value - Name of the dimension.
<position> - Tag that represents a position of the cell.
Properties:
dimension - Dimension that contains the position.
name - Name of the position.
hier - Hierarchy that contains the dimension.
axis - Location of this position in the grid if this was on the screen. Values are "row",
"column" or "page".
Appendix: RPAS Test Driver B-7
XML Requests
<SetValues>
Description:
Set the values of cells in the workbook.
Properties:
worksheet - Name of sheet as defined in tmpl.cfg.
measure - Measure whose value should be set.
spreadMeasure [optional] - Currently unused.
spreadMethod - Method to use when spreading this cell to lower level cells. See the
RPAS Configuration Tools User Guide for more information.
value - Desired value of the cell.
type - Type of cell. More accurately, this is the type of the measure. Locate this by
examining the configuration of the domain with the Oracle RPAS Configuration Tools.
Children:
<WindowContext> - Tag that defines what hierarchies and dimensions would be
visible if there was a screen. At a minimum, the dimensions of the current cell need to
be specified. There should only be one tag per hierarchy.
Properties:
hierarchy - Name of hierarchy.
Children:
<dimension> - Tag that represents the name of a dimension.
Properties:
value - Name of the dimension.
<position> - Tag that represents a position of the cell.
Properties:
dimension - Dimension that contains the position.
name - Name of the position.
<CommitWorkbook>
Description:
Transfer the data in the workbook back to the domain.
Properties:
synchronous [optional] - If "true", the workbook commits the data now. Otherwise, it is
the same as "commit later".
asap [optional] - If "true", the workbook is added to the server's commit ASAP queue.
If the 'synchronous' option is "true", then the 'asap' option is ignored. If both
'synchronous' and 'asap' are omitted or blank, then the default is to commit data now.
B-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
XML Requests
<RefreshWorkbook>
Description:
Overwrite the data in the workbook with data from the domain.
Properties:
refreshGroup [optional] - If a workbook has several refresh groups, you may specify
the one to use here. If omitted or blank, the default group is used.
<MenuEvent>
Description:
Execute a custom menu event in the current workbook.
Properties:
id - The numeric ID of the custom menu event. The IDs start at 1 and are in the same
order as they appear in the Dynamic Template configuration file.
expectedCaption [optional] - Specifies the caption that should be returned. Success is
false if the returned caption is different. The return caption is not validated if this is
blank.
expectedText [optional] - Specified the text that should be returned. Success is false if
the returned text is different. The returned text is not validated if this is blank.
<CreatePOPMeasure>
Description:
Create a new percent of parent measure (also known as percent participation).
Properties:
window - The name of the window that the new measure will be added to.
measure - The name of the "parent" measure for the new percent of parent measure.
hier [optional] - Specifies the hierarchy name for a relative percent of parent measure.
hiers [optional] - Specifies all hierarchies for an absolute percent of parent measure.
Hierarchy names are delimited by a space.
dims [optional] - Specifies all dimensions for an absolute percent of parent measure.
Dimension names are delimited by a space.
Either 'hier' or both 'hiers' and 'dims' must be specified. Both
may not be specified. Specifying 'hier' indicates that the percent of
parent measure will be relative. Specifying both 'hiers' and 'dims'
indicates that the percent of parent measure will be absolute. 'hiers'
and 'dims' are parallel arrays and their order must match.
Note:
Appendix: RPAS Test Driver B-9
XML Requests
<SaveWorkbook>
Description:
Save the workbook to work on later.
Properties:
workbookLabel - Label (displayed name) for the workbook
workbookName - Internal name of a stored workbook. See <OpenWorkbook> for
more information.
user - Access for the current user. Values are "NONE", "READ" or "WRITE".
group - Access for the named group. Values are "NONE", "READ" or "WRITE".
groupName - Name of the group for the above access value.
world - Access for the rest of the world. Values are "NONE", "READ" or "WRITE".
close - Close workbook. Values are "true" or "false".
<CloseWorkbook>
Description:
Close the currently open workbook.
Properties:
method - If "forward", save and close the workbook. If "backward", close but do not
save the workbook.
B-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Header File
RTD use with HP LoadRunner
In this section, familiarity with HP LoadRunner is assumed. For further information
on this topic, consult the HP LoadRunner documentation.
The RTD library is not a LoadRunner extension, and as such does not provide support
for record/replay functionality. Scripts must be hand-coded to suit the RPAS workflow
under test and only then can they be replayed using the message passing functions
outlined in the previous section.
Prerequisites
RTD functions can be called from any C-based virtual user (vuser). The script needs to
reference a header which contains the RTD function prototypes. Additionally, certain
LoadRunner replay settings must be set in order to assure correct behavior.
Header File
This file contains the functions exported by the RTD library; these are in a format
usable by the LoadRunner C runtime engine.
lr_rtd.h
#ifndef _RTD_RTD_H_
#define _RTD_RTD_H_
int
rtd_logon(const char* user,
const char* password,
const char* connection,
const char* domain,
const char* fcfPath,
const char* language,
const char* logLevel);
int
rtd_logon_ex(const char* user,
const char* password,
const char* connection,
const char* domain,
const char* fcfPath,
const char* language,
const char* logLevel,
const char* domainRootDirectory);
void rtd_logoff();
int
rtd_send(const char* request);
char* rtd_getResponse();
char* rtd_getResponseProperty(const char* property);
void rtd_freeCharPtr(char* ptr);
#endif // _RTD_RTD_H_
Appendix: RPAS Test Driver B-11
LoadRunner Scripting
LoadRunner Scripting
This section contains the details of LoadRunner scripting.
Script Settings
RTD is not thread-safe and so the virtual user script must be run as a process rather
than a thread:
■
Open run-time settings
■
Miscellaneous section
■
Select "Run Vuser as a process"
Failure to do this will result in unpredictable and often
inexplicable failures at runtime.
Note:
Script Sections
All LoadRunner C-based scripts consist of three sections:
■
vuser_init
■
Actions
■
vuser_end
It is advised that the vuser_init section is used for initialization, and the body of the
test placed in the Actions section. The vuser_end section is typically left unused.
Script Implementation
This section walks through two examples which validate that LoadRunner and RTD
are working correctly together.
Script Section: vuser_init
The vuser_init section, which can be common to all RTD scripts, deals with the DLL
load. In order for it to load correctly, the directory containing the library should be in
your system PATH. The DLL load should work without the PATH setting, but results
can vary from machine to machine. Explicitly setting the PATH guarantees success.
#include lr_rtd.h
#define RTD_LIBRARY "c:\\path\\to\\rtd.dll"
vuser_init {
int rc = lr_load_dll(RTD_LIBRARY);
if (rc!=0) {
lr_error_message("rtd library did not load (rc=%d). Not in your %PATH%?", rc);
lr_abort();
}
}
This section references the lr_rtd.h interface file defined previously. If it is not in the
script directory, it should be prefaced by the full path.
B-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
LoadRunner Scripting
Script Section: Action (simple test)
The Actions section contains user actions; these will vary on a case-by-case basis. This
example uses a simple script to check that the RTD and LR integration is working
correctly.
Action {
rtd_logon("user", "pwd", "connect", "dom", "c:\\path\\to\\Foundation.fcf",
"english", "debug");
lr_think_time(60);
rtd_logoff();
}
This example causes the virtual user to log on, sleep 60 seconds, and then log off. The
login details should be altered to suit the RPAS environment under test. If this
succeeds, then RTD is correctly installed.
The following is a more realistic example.
Script section: Action (real-world)
In this more complicated example, a workbook is created and the name retrieved. It is
then opened and closed. Additionally, rather than having multiple rtd_send() calls
in-line, the XML is placed within a LoadRunner parameter file. This is then iterated
over within the LoadRunner script.
The parameter file should consist of one complete XML entity per line, single column
called "command" with the following contents.
<Logon … />
<WizardInitialize templateName="perftest"/>
<GetNextWizardDialog templateName="perftest" forward="true"/>
<SelectPositions templateName="perftest" currentDialog="wiz_PerfTestphsd"
hierarchy="PHSH" dimension="PHSD"><position dimension="PHSD"
name="PHSDP001"/></SelectPositions>
<GetNextWizardDialog templateName="perftest" forward="true"/>
<SelectPositions templateName="perftest" currentDialog="wiz_PerfTestweek"
hierarchy="CLND" dimension="WEEK"><position dimension="WEEK"
name="WEEK200801"/><position dimension="WEEK"
name="WEEK200802"/></SelectPositions>
<GetNextWizardDialog templateName="perftest" forward="true"/>
<SelectPositions templateName="perftest" currentDialog="wiz_PerfTestitem"
hierarchy="PROD" dimension="ITEM"><position dimension="ITEM"
name="ITM000"/><position dimension="ITEM" name="ITM001"/></SelectPositions>
<WizardFinish templateName="perftest"/>
get_wb_name
<OpenWorkbook workbookName="{_wb}" access="write"/>
<CloseWorkbook method="backwards"/>
<Logoff/>
The vuser_init section should be identical to the prior example.
Appendix: RPAS Test Driver B-13
LoadRunner Scripting
The Actions section should contain the following:
Action {
char *wb_name, *xml, *response;
int success;
while(…) {
if (0==stricmp("get_wb_name", script.param)) {
wb_name=rtd_getResponseProperty("workbookName");
lr_save_string(wb_name, "_wb");
rtd_freeCharPtr(wb_name);
} else {
rc=rtd_send(lr_eval_string(xml));
if (!rc) {
response=rtd_getResponse();
lr_error_message("error - response was: %s", response);
rtd_freeCharPtr(response);
lr_abort();
}
}
}
The above section accomplishes a number of things:
■
Uses parameters instead of hard-coded calls
■
Builds a workbook through the wizard
■
Obtains the workbook name
■
Saves the workbook name to the _wb parameter name
■
Replaces subsequent instances of the _wb parameter with the workbook name,
through lr_eval_string()
Considerations for Scenario Use
■
■
■
When RTD is used in a scenario orchestrated by the LoadRunner controller, it is
necessary to have RTD on each of the load generators (injectors). RTD should be in
the same path, referenced in the LoadRunner script, on each generator.
Check the script runtime settings for the scenario. Match those used within the
virtual user generator (vugen) environment.
Ensure that if RTD is upgraded, it is upgraded on each generator.
B-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
C
Appendix: RPAS Test Automation
C
This appendix describes an RPAS utility called rpac (RPAS Pluggable Automation
Component). It can be used to perform various tests on an existing domain, based on a
set of test cases contained in XML files.
Introduction
The rpac utility enables the creation of highly customizable automated test suites for
the RPAS server. The XML-based framework allows rapid development of tests and
ensures that test cases can be quickly copied across locations. The flexible XML schema
allows the user to test a large number of RPAS features from as simple as writing data
to a domain, or as complicated as building a workbook, running custom menu
options, and verifying the results.
The XML framework also introduces consistency, accuracy, and reproducibility in the
test results. To reproduce a test case, all that is needed is the XML file and a copy of the
domain.
Note that rpac operates directly against the domain itself and therefore does not test
any Client/Server interaction.
Usage
To run an rpac test, simply run the following from the command line:
rpac -d <path to domain> -title <title> -input <path to xml input>
[options]
[commands]
The output of this command is written to unittest.xml in the local directory. The results
of this file contain only the failing tests. To display both passing and failing tests, use
the -coverage option. This generates a coverage.xml in the local directory that contains
both passing and failing results.
Required Parameters
Table C–1
Required Parameters
Option
Parameter
Description
-d
Path to domain
Specifies the path to the domain that the test will run against.
-title
Title
Specifies the name that this test run is given in the output files. This
is used when combining the results of multiple test runs.
Appendix: RPAS Test Automation C-1
Writing Test Cases
Commands
Table C–2
Commands
Command
Description
<none>
If you do not specify a command, then rpac will simply run the test script provided.
-listTests
When this is specified, rpac will just write the tests to be executed to the console. The
tests will not be run.
-traceTests
When this is specified, rpac will just write the commands to be executed to the
console. The tests will not be run.
-printTagDoc
Print the rpac schema to the console. This option does not require -input.
-writeTagDoc
Write the rpac schema to a file. This option does not require -input.
Options
Table C–3
Options
Option
Parameter
Description
-input
path to XML script
Specifies the path to the XML script containing the test suite.
-suite
pattern
A regular expression pattern to specify which test suites should be
run. Any test suite whose name does not match the pattern is skipped.
Example: If you have the following test suites (test1, test2, test3, test4,
test5) and you just want to run suites 1,2, and 4, specify:
-suite test[124]
-coverage
<none>
When specified, rpac writes all passing and failing results to
coverage.xml.
Writing Test Cases
The structure of an rpac test script is defined by the following tags. For more
information, see the "Schema" on page C-7.
Table C–4
Test Case Tags
Tag
Description
<testscript>
The outermost tag for the test script. This tag contains the one or more <testsuite>
tags.
<testsuite>
This tag defines a suite of tests that are designed to run together. Each suite contains
its own <setup>, <teardown>, <testcase>, and <workbook-operations> tags. This tag
has a name attribute that can be used with the -suite command line attribute to
specify which suites are executed in this run.
<setup>
This tag sets the preconditions that are common to all test cases. Operations inside
this tag are run before every test case is executed.
Example operations:
■
Set RpasToday so the test date is consistent for every test run.
■
Pre-set measure values so tests operate in a known state.
■
Check any preconditions to make sure this test run is valid.
C-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Example
Table C–4 (Cont.) Test Case Tags
Tag
Description
<teardown>
This tag contains cleanup code that is run after all test cases. This is used to restore a
domain or workbook to its default state to remove dependencies between
independent test cases.
Example operations:
<workbook-operations>
■
Set domain measure values back to their initial state.
■
Run batch scripts to remove any test-specific files that were generated.
This tag allows for the test script to build, refresh, commit, and close workbooks.
Workbook operations may exist outside of test cases, but we recommend you
encapsulate them wherever possible inside a testsuite tag for logging purposes.
<testcase>
This tag is where the code to perform each test goes. It should perform operations,
then use the assert tags to verify the results. The name of this tag is used in the output
to log timing results and success/failure. Note: Code in the <setup> tag will be
executed prior to each test case, and code in the <teardown> tag will be executed after
each test case.
It is highly recommended that the teardown section restore the domain to its previous
state. This removes dependencies between test cases and ensures consistency from one
run to the next.
Example
Below is a sample XML file that contains some rpac tests that run against an MFP
domain. This test illustrates how the setup/teardown methods work, as well as how to
do the various workbook operations.
The first test case builds the workbook. The first step in this operation is to shell out to
the wbmgr utility to clear out all existing workbooks. This step prevents the domain
from growing after repeated operations, but you should only use this step in cases
where you know that existing workbooks are not needed.
After that, the test verifies the preconditions of the test case. In this example, the test
verifies the pre-conditions performed in the setup code by checking that the domain
measure value is "true". After that, the test makes the wizard selections and builds the
workbook. Once the workbook is built, an assertion verifies that the load rules
correctly set the workbook value.
Once this test case is complete, the teardown code is executed, along with the setup
code for the next test case. The test verifies that the teardown code correctly set the
workbook's measure value to "false", then issues a commit. Once the workbook is
committed, the domain value is checked to see if it was properly updated. Once again,
the teardown code is executed, and the setup code is run at the beginning of the next
test case.
For the third test case, the setup code should have initialized the domain value back to
"true", and the workbook value back to "false". The test case verifies these operations,
then performs a workbook refresh, and verifies that the workbook value was correctly
set to "true".
After that, the workbook is closed, and the test suite is complete.
Appendix: RPAS Test Automation C-3
Example
Because our teardown code modifies workbook data, the
workbook close step cannot be encapsulated inside of a test case. If it
was, the teardown code would try to modify a workbook that was no
longer there and produce a failing result.
Note:
<?xml version="1.0" encoding="UTF-8"?>
<!--Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
File: wbtest.xml
TestCase Description:
- Setup:
Set the RPAS Today value
Set the domain's measure value to "true"
- Teardown:
Set the workbook's measure value to "false"
- Build: Build a workbook and validate the load rule
- Commit: Validate the commit rule
- Refresh: Validate the refresh rule
- Close the workbook
-->
<testscript>
<testsuite name="MFP RPAC Test 11">
<!--Setup executed at the beginning of every testcase-->
<setup>
<rpas-today>20070101</rpas-today>
<edit-domain-measure-value name="ipopappenbb" namedkeys="h1_2007:100:1"
value="true"/>
</setup>
<testcase name="Enable OP Approval Workbook: Build">
<!--Clear all existing workbooks-->
<shell>wbmgr -d [DOMAIN] -remove -all</shell>
<!--Verify pre-conditions are true-->
<assert-domain-measure-value-eq name="ipopappenbb" namedkeys="h1_2007:100:1"
value="true"/>
<workbook-operations>
<build template-name="EnableOp" label="Enable OP Approval" user="adm">
<!--Make positions selection for the wizard page-->
<wizard-page-settings id="wiz_EnableOpssn">
<set-tree-selections control-name="tree1" dim-name="ssn"
rollup-name="ssn">
h1_2007
</set-tree-selections>
</wizard-page-settings>
<wizard-page-settings id="wiz_EnableOpdept">
<set-tree-selections control-name="tree1" dim-name="dept"
rollup-name="dept">
100
</set-tree-selections>
</wizard-page-settings>
<wizard-page-settings id="wiz_EnableOpchnl">
<set-tree-selections control-name="tree1" dim-name="chnl"
rollup-name="chnl" >
1
</set-tree-selections>
</wizard-page-settings>
C-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Output
</build>
</workbook-operations>
<!--Validate the load rule worked correctly->
<assert-workbook-measure-value-eq name="ipopappenbb" keys="0:0:0"
value="true"/>
</testcase>
<!--Commit the workbook and assert the measure values in domain-->
<testcase name="Enable OP Approval Workbook: Commit">
<assert-domain-measure-value-eq name="ipopappenbb" namedkeys="h1_2007:100:1"
value="true"/>
<assert-workbook-measure-value-eq name="ipopappenbb" namedkeys="h1_
2007:100:1 value="false"/>
<workbook-operations>
<commit type ="now" template-name="EnableOp" label="Enable OP Approval"
user="adm"/>
</workbook-operations>
<!--Validate the commit rule worked correctly->
<assert-domain-measure-value-eq name="ipopappenbb" namedkeys="h1_2007:100:1"
value="false"/>
</testcase>
<!--Refresh the workbook and assert measure values in workbook and domain-->
<testcase name="Enable OP Approval Workbook: Refresh">
<assert-domain-measure-value-eq name="ipopappenbb" namedkeys="h1_2007:100:1"
value="true"/>
<assert-workbook-measure-value-eq name="ipopappenbb" namedkeys="h1_
2007:100:1" value="false"/>
<workbook-operations>
<refresh template-name="EnableOp" label="Enable OP Approval" user="adm"/>
</workbook-operations>
<!--Validate the refresh rule worked correctly->
<assert-workbook-measure-value-eq name="ipopappenbb" namedkeys="h1_
2007:100:1" value="true"/>
</testcase>
<!--Close the workbook-->
<workbook-operations>
<close template-name="EnableOp" label="Enable OP Approval" user="adm"/>
</workbook-operations>
<!--Teardown executed at the end of every testcase-->
<teardown>
<edit-workbook-measure name="ipopappenbb" keys="0:0:0" value="false"/>
</teardown>
</testsuite>
</testscript>
Output
When rpac executes, it prints the status of current execution to the console. On
completion of all the test cases, the summary of test cases is stored in unitest.xml
under the current directory. These results contain the failing test case, as well as the
error message that was captured. If -coverage was specified, then a coverage.xml file is
generated containing the passing and failing results.
Appendix: RPAS Test Automation C-5
Output
Example:
[rpasHome] rpac -d testDomain -input wbTest.xml -title "'MFP OpApproval RPAC Test"
Running rpac tests for RPAC : MFP Tests...
Now executing wbmgr in domain.
Deleting all workbooks in the domain...
Destroying workbook 't0000000000' in domain.
wbmgr completed successfully
5.292541
0.308167
0.244300
Ran 3
tests: 0
errors, 0
failures in 5.85 seconds
If something had gone wrong, the output would look like this:
Example:
[rpasHome] rpac -d testDomain -input wbTest.xml -title "'MFP OpApproval RPAC
Test"
Now executing wbmgr in domain
Deleting all workbooks in the domain...
Destroying workbook 't0000000000' in domain
wbmgr completed successfully
Failure
0.192497
Failure
Ran 3
tests: 0
errors, 2
failures in 6.42 seconds
Contents of unittest.xml
After execution, rpac creates a unittest.xml file containing the test results.
Here is an example from the successful execution above:
<unittest name='MFP OpApproval RPAC Test' runcount='3' timestamp='2012-10-17
10:06:49' elapsedTime='13.72 seconds'>
</unittest>
Here is the unittest.xml output from the failing run:
<unittest name='MFP OpApproval RPAC Test' runcount='3' timestamp='2012-10-17
10:07:38' elapsedTime='6.42 seconds'>
<failurelist>
<failure>
<testname> </testname>
<message>Got Error: Expected measure &apos;ipopappenbb&apos; at ArrayKey(0,
0, 0, 0) is false;
false == true</message>
<file>OpApproval.xml</file>
<line>52</line>
</failure>
<failure>
<testname> </testname>
<message>Got Error: Expected measure &apos;ipopappenbb&apos; at ArrayKey(0,
0, 0, 0) is false;
false == true</message>
<file>OpApproval.xml</file>
<line>60</line>
C-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
</failure>
</failurelist>
</unittest>
Schema
1. Top Level Parent Tag
1.1 testscript
Top level tag, which contains all the rpac tags.
1.2 testsuite
Contains setup, teardown, and testcase tag elements.
1.3 testcase
Contains a list of tag elements to be executed.
1.4 setup
The setup tag is used to set any preconditions that must be true prior to each test case.
These can include initializing measure values, setting the date, or running batch
scripts to prepare the domain.
1.5 teardown
The teardown tag contains tag elements used to restore the environment to a default
state after a test case is executed. This can include returning measures to their default
values or running batch scripts to clean up the domain.
The sample implementation of the above tags are given below:
Sample Usage:
<testscript>
<testsuite name="MFP RPAC Test">
<setup>
<!--- setup code ->
</setup>
<testcase name="Measure Analysis Workbook : build">
<!---testcase code ->
</testcase >
<teardown>
<!--- teardown code ->
</teardown>
</testsuite>
</testscript>
2. Generic Tags
2.1 Attribute
Specifies the attributes of a Tag.
Appendix: RPAS Test Automation C-7
Schema
2.2 Description
Describes the functionality of the Tags or Attributes.
2.3 Fail
Creates a failure message.
Attribute
Description
Category
Msg
Message to be used in the failure text Optional
2.4 key
Set the key specs value of the named key.
Attribute
Description
Category
Name
Key name
Required
keyspec
Key value spec
Required
2.5 rpas-today
Sets the RpasToday environmental variable to the value of this tag.
Sample usage:
<rpas-today>20070101</rpas-today>
Where: the date is given in yyyymmdd format.
2.6 shell
Start a shell process with the command provided as value of this tag.
Attribute
Description
Category
working-directory
Directory to use for shell, if not
provided then the current working
directory is used
Optional
check-status
Boolean to determine if a non-zero
return status throws an exception
Optional
is-shell
Boolean to indicate that the process is Optional
a shell
Sample usage:
<shell check-status="true" is-shell="false">wbmgr -d [DOMAIN] -remove -all</shell>
2.7 register-measure
Register a measure with the provided properties.
Attribute
Description
Category
Name
Measure name
Required
Intx
Base intersection
Required
C-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
Type
Type of measure
Required
Naval
NA value of the measure
Required
Defagg
Default aggregation
Required
Sample usage:
<register-measure name="MeasureX" intx="WEEK_STR_DAY_" type="int"
naval="0"/>
defagg="total"
2.8 unregister-measure
Unregister a measure registered by rpac.
Attribute
Description
Category
Name
Measure name
Required
Sample usage:
<unregister-measure name="MeasureX" />
3. Workbook Operation Tags
3.1 Workbook Wizard Operations
3.1.1 build Build workbook base on provided tag data.
Attribute
Description
Category
template-name
Template name
Required
label
Label for workbook
Required
user
User used to access workbook
Required
Sample usage:
<build template-name="MeasureAnalysis" label="MEAS AN" user="adm">
3.1.2 wizard-page-settings Contains the settings for a wizard page.
Appendix: RPAS Test Automation C-9
Schema
Attribute
Description
Category
id
ID use to match up settings with
wizard pages
Required
For configured templates, this
follows the pattern:
wiz_<wbt_name><base_dim>
Example:
For the EnableOp workbook, the
wizard page that sets CHNL is:
Fwiz_EnableOpchnl
Note: For custom templates, get the
name from the administrator.
Sample usage:
<wizard-page-settings id="wiz_EnableOpchnl">
3.1.3 set-hier-selection Set the selection of a SingleHier Select control of a custom wizard
page.
Attribute
Description
Category
control-name
Name of the control for a wizard
page. This can be obtained from the
template.cfg file
Required
dim-name
Name of the dimension containing
the selection
Required
selection
Name of the position selected
Required
Sample usage:
<set-hier-selection control-name="loc_select" dim-name="chnl"
selection="1" >
3.1.4 set-selected Set the value for a Boolean control on a custom wizard page.
Attribute
Description
Category
control-name
Name of the control for a wizard
page. This can be obtained from the
configuration
Required
Selected
Set this to "TRUE" or "FALSE"
Required
Sample usage:
<set-selected control-name="UseExtraMeasures" value="TRUE">
C-10 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
3.1.5 set-selection Set the selection of a drop-down list control on a custom wizard page.
Attribute
Description
Category
control-name
Name of the control for a wizard
page. This can be obtained from the
configuration
Required
Selection
Text for the selection operation
Required
Sample usage:
<set-selection control-name="ForecastLevel" value="2">
3.1.6 set-selections Set the selections of a list box or tree control on a custom wizard
page. This tag should contain a space-delimited list of the selections.
Attribute
Description
Category
control-name
Name of the control for a wizard
page. This can be obtained from the
configuration
Required
Sample usage:
<set-selections control-name="ExtraMeasures">
meas1 meas2 meas3 </set selections>
3.1.7 set-text Set the contents of an edit control on a custom wizard page.
Attribute
Description
Category
control-name
Name of the control for a wizard
page
Required
test
Text for the operation
Required
Sample usage:
<set-text control-name="MyText" value="abc">
3.1.8 set-tree-selections Set the selections for a two-tree control on either a standard or
custom wizard page.
Attribute
Description
Category
control-name
Name of the control. For two-tree
controls, this should always be set to
"tree1"
Required
rollup-name
The highest level of the wizard page
Required
dim-name
Name of the dimension on which the Required
selections are made
Sample usage:
<set-tree-selections control-name="tree1" rollup-name="chnl" dim-name="str">
str1 str2 str3
</set-tree-selections>
Appendix: RPAS Test Automation
C-11
Schema
3.2 Workbook Operations
3.2.1 Workbook-operations Contains the workbook operations to be executed.
3.2.2 Calc Does workbook calculations.
Attribute
Description
Category
template-name
Template name
Required
label
Label for workbook
Required
user
User used to access workbook
Required
Sample usage:
<calc template-name="RptAdmin" label="Reporting Administration" user="adm"/
3.2.3 custom-menu Checks for the existence of, or executes, a custom menu.
Attribute
Description
Category
template-name
Template name
Required
label
Label for workbook
Required
user
User used to access workbook
Required
menu-label
Menu label for this custom menu .
This can be obtained from the
configuration
Required
menu-exist
Set this to "true" to see if the menu
item exists, or leave it blank to
execute the custom menu
Optional
Sample usage:
<custom-menu template-name="BottomUp" label="Botup" user="adm"
menu-label="menuItem83" menu-exist="true"/>
3.2.4 refresh Does workbook refresh.
Attribute
Description
Category
template-name
Template name
Required
label
Label for workbook
Required
user
User used to access workbook
Required
rule-group
Set this to use a rule group other than Optional
the default refresh group
Sample usage:
<refresh template-name="BottomUp" label="Botup" user="adm" rule-group="refresh_
alt"/>
C-12 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
3.2.5 Close Does workbook close. Arguments may be provided for debug purposes.
Attribute
Description
Category
template-name
Template name
Optional
label
Label for workbook
Optional
user
User used to access workbook
Optional
Sample usage:
<close template-name="BottomUp" label="Botup" user="adm"/>
3.2.6 Does workbook commit Does workbook commit.
Attribute
Description
Category
type
Commit Type (now|later)
Required
template-name
Template name
Required
label
Label for workbook
Required
user
User used to access workbook
Required
Sample usage:
<commit type="now"
user="adm" />
template-name="BottomUp" label="Bottom Up MFP Refresh"
3.3 Workbook Assertions
3.3.1 assert-window-contain-measure Assert that the measures provided are visible (or not
visible) on the window.
Attribute
Description
Category
name
Name of the window in the
workbook configuration.
User-generated windows cannot be
used
Required
measure
Comma separated list of measures
names
Optional
containflag
If true, will check that measures
Optional
provided are visible. If false, will
check that the measures provided are
not visible.
Sample usage:
<assert-window-contain-measure
name=" chnldeptssn__W"
measures =" Ipopappenbb"/>
3.3.2 assert-window-exists Assert if a window exists in the current workbook.
Attribute
Description
Category
name
Window name of current workbook
Required
Appendix: RPAS Test Automation
C-13
Schema
Sample usage:
<assert-window-exists name="chnldeptssn__W" />
3.3.3 assert-window-intersection Assert window intersection matches provided
intersection.
Attribute
Description
Category
name
Window name of current workbook
Required
baseint
Intersection string to compare. Leave Optional
blank if checking for scalar.
Sample usage:
<assert-window-intersection name="chnldeptssn__W" baseint"chnldeptssn_" />
3.3.4 assert-window-not-exists Assert if a window does not exist in the current workbook.
Attribute
Description
Category
name
Window name of current workbook
Required
Sample usage:
<assert-window-not-exists name="chnldeptssn__W" />
3.3.5 assert-window-measure-exists Assert a measure exists.
Attribute
Description
Category
name
Measure name
Required
Sample usage:
<assert-measure-exists name=" Ipopappenbb" />
3.3.6 assert-workbook-measure-intx Assert a workbook measure base intersection
matches an expected value.
Attribute
Description
Category
name
Measure name
Required
intx
Intersection string to compare with
Required
Sample usage:
<assert-measure-intersection name=" Ipopappenbb" baseint"chnldeptssn_" />
3.3.7 assert-workbook-measure-value-eq Asserts that a workbook measure at the specified
positions is equal to the provided value.
Parent tag(s): testcase
Child tag(s): None
C-14 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
keys
Required
The keys to be used to compare
measure values. Can be either indices
or position names . Each dimension
spec in the keys-spec is delimited by
a ":". Multiple position ranges for a
dimension can be specified by using
"," as separators.
When using indices, a range of
positions can also be used.
Ex - "0-2:4-7,11-13:4" implies indices
0,1,2 for the first dimension,
4,5,6,7,11,12,13 for the second, and 4
for the third dimension of the
measure.
Note: Because indices are based on
the workbook selections, they may
not be consistent across all test cases.
Care must be exercised to ensure that
you are using the correct indices for
your specific test case.
namedkeys
Optional
Position names used to get keys of
the measure array. Using indices
instead of position names or
positions that do not exist in the
MeasureStore (Workbook) will be
flagged as an error. Similar to "keys"
above, but using position names only.
path
Optional
Path of the flat file used for
comparison against the Measure
array. This looks like pointing to a
pre-set environment variable. "path"
cannot be used along with "keys" or
"namedkeys". "path" is used only to
compare the measure data against a
pre-existing flat file. If none of
"path","keys" and "namedkeys" are
specified, the comparison occurs for
ALL the keys in the measure array of
the Measure Store (Workbook).
start
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
width
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
value
The expected value of the measure.
Comparison on equality.
Optional
Sample usage: (indices)
<assert-workbook-measure-value-eq name="drwppthrsclsp" keys="0-2"
value="0.0" />
Sample usage (names):
<assert-workbook-measure-value-eq name="drwppthrsclsp" namedkeys="pos1,pos2,pos3"
value="0.0" />
Appendix: RPAS Test Automation
C-15
Schema
3.3.8 assert-workbook-measure-value-ge Assert a workbook measure value at the specified
positions is greater than or equal to provided value.
Attribute
Description
Category
keys
The keys to be used to compare
measure values. Can be either
indices, or position names. Each
dimension spec in the keys-spec is
delimited by a ":". Multiple position
ranges for a dimension can be
specified by using "," as separators.
Required
When using indices, a range of
positions can also be used.
Ex - "0-2:4-7,11-13:4" implies indices
0,1,2 for the first dimension,
4,5,6,7,11,12,13 for the second, and 4
for the third dimension of the
measure.
Note: Because indices are based on
the workbook selections, they may
not be consistent across all test cases.
Care must be exercised to ensure that
you are using the correct indices for
your specific test case.
namedkeys
Optional
Position names used to get keys of
the measure array. Using indices
instead of position names or
positions that do not exist in the
MeasureStore (Workbook) will be
flagged as an error. Similar to "keys"
above, but using position names only.
path
Optional
Path of the flat file used for
comparison against the Measure
array. This looks like pointing to a
pre-set environment variable. "path"
cannot be used along with "keys" or
"namedkeys". "path" is used only to
compare the measure data against a
pre-existing flat file. If none of
"path","keys" and "namedkeys" are
specified, the comparison occurs for
ALL the keys in the measure array of
the Measure Store (Workbook).
start
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
width
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
value
The expected value of the measure.
Comparison on equality.
Optional
Sample usage (indices):
<assert-workbook-measure-value-ge name="drwppthrsclsp" keys="0-2"
C-16 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
value="0.0" />
Schema
Sample usage (names):
<assert-workbook-measure-value-ge name="drwppthrsclsp" namedkeys="pos1,pos2,pos3"
value="0.0" />
3.3.9 assert-workbook-measure-value-gt Assert a workbook measure value is greater than
a provided value.
Attribute
Description
Category
keys
The keys to be used to compare
measure values. Can be either
indices, or position names. Each
dimension spec in the keys-spec is
de-limited by a ":". Multiple position
ranges for a dimension can be
specified by using "," as separators.
Required
When using indices, a range of
positions can also be used.
Ex - "0-2:4-7,11-13:4" implies indices
0,1,2 for the first dimension,
4,5,6,7,11,12,13 for the second and 4
for the third dimension of the
measure.
Note: Because indices are based on
the workbook selections, they may
not be consistent across all test cases.
Care must be exercised to ensure that
you are using the correct indices for
your specific test case.
namedkeys
Optional
Position names used to get keys of
the measure array. Using indices
instead of position names or
positions that do not exist in the
MeasureStore (Workbook) will be
flagged as an error. Similar to "keys"
above, but using position names only.
path
Optional
Path of the flat file used for
comparison against the Measure
array. This looks like pointing to a
pre-set environment variable. "path"
cannot be used along with "keys" or
"namedkeys". "path" is used only to
compare the measure data against a
pre-existing Flat file. If none of
"path","keys" and "namedkeys" are
specified, the comparison occurs for
ALL the keys in the measure array of
the Measure Store (Workbook).
start
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
width
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
value
The expected value of the measure.
Comparison on equality.
Optional
Appendix: RPAS Test Automation
C-17
Schema
Sample usage (indices):
<assert-workbook-measure-value-gt name="drwppthrsclsp" keys="0-2"
value="0.0" />
Sample usage (names):
<assert-workbook-measure-value-gt name="drwppthrsclsp" namedkeys="pos1,pos2,pos3"
value="0.0" />
3.3.10 assert-workbook-measure-value-le Assert a workbook measure value is greater than
or equal to a provided value.
Attribute
Description
Category
keys
The keys to be used to compare
measure values. Can be either
indices, or position names. Each
dimension spec in the keys-spec is
delimited by a ":". Multiple position
ranges for a dimension can be
specified by using "," as separators.
Required
When using indices, a range of
positions can also be used.
Ex - "0-2:4-7,11-13:4" implies indices
0,1,2 for the first dimension,
4,5,6,7,11,12,13 for the second, and 4
for the third dimension of the
measure.
Note: Because indices are based on
the workbook selections, they may
not be consistent across all test cases.
Care must be exercised to ensure that
you are using the correct indices for
your specific test case.
namedkeys
Optional
Position names used to get keys of
the measure array. Using indices
instead of position names, or
positions that do not exist in the
MeasureStore (Workbook) will be
flagged as an error. Similar to "keys"
above, but using position names only.
path
Path of the flat file used for
comparison against the Measure
array. This looks like pointing to a
pre-set environment variable. "path"
cannot be used along with "keys" or
"namedkeys". "path" is used only
when we want to compare the
measure data against a pre-existing
flat file. If none of "path","keys" and
"namedkeys" are specified, the
comparison occurs for ALL the keys
in the measure array of the Measure
Store (Workbook).
Optional
start
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
C-18 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
width
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
value
The expected value of the measure.
Comparison on equality.
Optional
Sample usage (indices):
<assert-workbook-measure-value-le name="drwppthrsclsp" keys="0-2"
value="0.0" />
Sample usage (names):
<assert-workbook-measure-value-le name="drwppthrsclsp" namedkeys="pos1,pos2,pos3"
value="0.0" />
3.3.11 assert-workbook-measure-value-lt Assert a workbook measure value is less than a
provided value.
Attribute
Description
Category
keys
The keys to be used to compare
measure values. Can be either
indices, or position names. Each
dimension spec in the keys-spec is
de-limited by a ":". Multiple position
ranges for a dimension can be
specified by using "," as separators.
Required
When using indices, a range of
positions can also be used.
Ex - "0-2:4-7,11-13:4" implies indices
0,1,2 for the first dimension,
4,5,6,7,11,12,13 for the second, and 4
for the third dimension of the
measure.
Note: Because indices are based on
the workbook selections, they may
not be consistent across all test cases.
Care must be exercised to ensure that
you are using the correct indices for
your specific test case.
namedkeys
Optional
Position names used to get keys of
the measure array. Using indices
instead of position names, or
positions that do not exist in the
MeasureStore (Workbook) will be
flagged as an error. Similar to "keys"
above, but using position names only.
Appendix: RPAS Test Automation
C-19
Schema
Attribute
Description
Category
path
Path of the flat file used for
comparison against the Measure
array. This looks like pointing to a
pre-set environment variable. "path"
cannot be used along with "keys" or
"namedkeys". "path" is used only
when we want to compare the
measure data against a pre-existing
flat file. If none of "path","keys" and
"namedkeys" are specified, the
comparison occurs for ALL the keys
in the measure array of the Measure
Store (Workbook).
Optional
start
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
width
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
value
The expected value of the measure.
Comparison on equality.
Optional
Sample usage (indices):
<assert-workbook-measure-value-lt name="drwppthrsclsp" keys="0-2"
value="0.0" />
Sample usage (names):
<assert-workbook-measure-value-lt name="drwppthrsclsp" namedkeys="pos1,pos2,pos3"
value="0.0" />
3.3.12 assert-workbook-measure-value-ne Assert a workbook measure value is not equal to
a provided value.
Attribute
Description
Category
keys
The keys to be used to compare
measure values. Can be either
indices, or position names. Each
dimension spec in the keys-spec is
de-limited by a ":". Multiple position
ranges for a dimension can be
specified by using "," as separators.
Required
When using indices, a range of
positions can also be used.
Ex - "0-2:4-7,11-13:4" implies indices
0,1,2 for the first dimension,
4,5,6,7,11,12,13 for the second, and 4
for the third dimension of the
measure.
Note: Because indices are based on
the workbook selections, they may
not be consistent across all test cases.
Care must be exercised to ensure that
you are using the correct indices for
your specific test case.
C-20 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
namedkeys
Optional
Position names used to get keys of
the measure array. Using indices
instead of position names, or
positions that do not exist in the
MeasureStore (Workbook) will be
flagged as an error. Similar to "keys"
above, but using position names only.
path
Optional
Path of the flat file used for
comparison against the Measure
array. This looks like pointing to a
pre-set environment variable. "path"
cannot be used along with "keys" or
"namedkeys". "path" is used only to
compare the measure data against a
pre-existing flat file. If none of
"path","keys" and "namedkeys" are
specified, the comparison occurs for
ALL the keys in the measure array of
the Measure Store (Workbook).
start
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
width
The field start value. If this does not
exist in the XML, the value is taken
from the Measure's Properties. Used
in flat-file comparison.
Optional
value
The expected value of the measure.
Comparison on equality.
Optional
Sample usage (indices):
<assert-workbook-measure-value-ne name="drwppthrsclsp" keys="0-2"
value="0.0" />
Sample usage (names):
<assert-workbook-measure-value-ne name="drwppthrsclsp" namedkeys="pos1,pos2,pos3"
value="0.0" />
3.3.13 assert-workbook-popcount-eq Assert a workbook measure popcount matches an
expected value.
Attribute
Description
Category
name
Measure name
Required
pop-count
Expected popcount
Required
Sample usage:
<assert-workbook-popcount-eq name=" Ipopappenbb" pop-count="100" />
3.3.14 assert-workbook-popcount-eq-zero Assert a workbook measure is not populated.
Attribute
Description
Category
name
Measure name
Required
Appendix: RPAS Test Automation
C-21
Schema
Sample usage:
<assert-workbook-popcount-eq-zero name=" Ipopappenbb"
/>
3.3.14 assert-measure-popcount-ne-zero Assert a workbook measure is populated.
Attribute
Description
Category
name
Measure name
Required
Sample usage:
<assert-workbook-popcount-ne-zero name=" Ipopappenbb"
/>
3.4 Workbook Data Edit Operations
3.4.1 clear-workbook-list Clear a list of workbook measures of all data.
Attribute
Description
Category
path
Path to a file containing a new-line
delimited list of measures
Required
Sample usage:
<clear-workbook-list path="my_list.txt"/>
3.4.2 clear-workbook-measure Clear a workbook measure of all data.
Attribute
Description
Category
name
Measure name
Required
Sample usage:
<clear-workbook-measure name=" Ipopappenbb/>
3.4.3 edit-workbook-measure Edits the value of a workbook measure based on provided
attributes. This tag closely models the action of editing a cell from the Client, as
opposed to set-workbook-measure, which does a direct update of the workbook
arrays.
This tag can be used in a variety of ways:
Set by loadmeasure file:
By specifying <path>, <start>, and <width>, you can set the measure values according
to a supplied loadmeasure file. This file must be in fixed-width format.
Set by positions:
You can set individual positions by providing a <keys> tag. If you want, you can
provide the list of positions at an aggregate level by specifying the intersection using
the <keyint> tag.
Set everything:
If you do not supply a <path> or <keys> tag, the entire measure will be set to the
supplied value.
C-22 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
name
Measure name
Required
keys
List of comma separated position
names
Optional
namedkeys
List of comma separated position
names
Optional
path
Path to load measure type file to
compare with
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
For Date type measures, RPAC supports setting the array cell
using either of the following two Date & Time formats "%m/%d/%Y" or "%m/%d/%Y-%H:%M:%S" where m = 2 digit
month, d = 2 digit date, Y = 4 digit year, H = 2 digit hour, M = 2 digit
min, and S = 2 digit sec.
Note:
Sample usage (using keys):
<edit-workbook-measure name="meas1" keys="0-2:5"
value="0.0" />
Sample usage (using keyint):
<assert-workbook-measure-value-ne name="meas2" namedkeys="chnl1:week1"
value="02/24/2012" />
Sample usage (load-measure file):
<edit-workbook-measure name="meas1" path="loadMeas1.dat" start="100" width="20"/>
Sample usage (set all):
<edit-workbook-measure name="meas1" value="2"
3.4.4 set-workbook-measure Sets the value of a workbook measure based on provided
attributes. Unlike edit-workbook-measure, this performs a direct change of the
workbook data and does not update the changearrays unless told to do so. This can
have an impact on the calculation cycle since bypassing the change arrays results in a
full evaluation rather than incremental.
This tag can be used in a variety of ways:
Set by loadmeasure file:
By specifying <path>, <start>, and <width>, you can set the measure values according
to a supplied loadmeasure file. This file must be in fixed-width format.
Set by positions:
You can set individual positions by providing a <keys> tag. If you want, you can
provide the list of positions at an aggregate level by specifying the intersection using
the <keyint> tag.
Appendix: RPAS Test Automation
C-23
Schema
Set everything:
If you do not supply a <path> or <keys> tag, the entire measure will be set to the
supplied value.
Attribute
Description
Category
name
Measure name
Required
keys
List of comma separated position
names
Optional
namedkeys
List of comma separated position
names
Optional
path
Path to load measure type file to
compare with
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
incremental
True if evaluation is to be incremental Optional
For Date type measures, RPAC supports setting the array cell
using either of the following two Date & Time formats "%m/%d/%Y" or "%m/%d/%Y-%H:%M:%S" where m = 2 digit
month, d = 2 digit date, Y = 4 digit year, H = 2 digit hour, M = 2 digit
min, and S = 2 digit sec.
Note:
Sample usage (using keys):
<set-workbook-measure name="meas1" keys="0-2:5"
value="0.0" incremental="true"/>
Sample usage (using keyint):
<set-workbook-measure-value-ne name="meas2" namedkeys="chnl1:week1"
value="02/24/2012" />
Sample usage (load-measure file):
<set-workbook-measure name="meas1" path="loadMeas1.dat" start="100" width="20"/>
Sample usage (set all):
<set-workbook-measure name="meas1" value="2"
4. Domain Operation Tags
4.1 Assertions
4.1.1 assert-dimension-contain Assert a dimension contains or does not contain a position
name.
C-24 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
name
Dimension name
Required
posname
List of comma separated position
names
Required
containflag
If flag is true then position names are Required
checked to see if they are contained
in the dimension
Sample usage:
<assert-dimension-contain name="DEPT" posname="dept1" containflag="true"
/>
4.1.2 assert-dimension-exists Assert a dimension name exists.
Attribute
Description
Category
name
Dimension name
Required
Sample usage:
<assert-dimension-exists name="DEPT" />
4.1.3 assert-dimension-size Assert a dimension size is between a minimum and a
maximum value.
Attribute
Description
Category
name
Dimension name
Required
min
Minimum value
Required
max
Maximum value
Required
Sample usage:
<assert-dimension-size name="DEPT" min="8" max="32"
/>
4.1.4 assert-domain-measure-exists Assert a domain measure exists.
Attribute
Description
Category
name
Dimension name
Required
Sample usage:
<assert-domain-measure-exists name="r_ex_test"
/>
4.1.5 assert-domain-measure-intx Assert a domain measure base intersection matches an
expected value.
Attribute
Description
Category
name
Dimension name
Required
intx
Intersection string to compare with
Required
Appendix: RPAS Test Automation
C-25
Schema
Sample usage:
<assert-domain-measure-intx name="r_ex_test" intx="str_sku_week"
4.1.6 assert-domain-measure-value-eq Assert a domain measure value is equal to an
expected value. This tag can be run in a number of ways:
Check against a loadmeasure file:
By specifying <path>, <start>, and <width>, you can validate that the contents of a
measure are equal to the contents of a fixed-with loadmeasure file.
Check against specified positions:
By providing <keys> or <namedkeys>, you can verify that all of the positions in your
specification are equal to the provided value. You can specify <keyint> to provide
positions at an alternate rollup.
Check entire measure:
If you do not supply a <keys>, <namedkeys>, or <path> tag, then rpac will assert that
every logical cell in the measure is equal to the value provided.
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
Sample usage (using keys):
<assert-domain-measure-value-eq name="bulylagtx" keyint="year" namedkeys=" 2007"
value="Test1"/>
Sample usage (using path):
<assert-domain-measure-value-eq name="bulylagtx" path="loadmeas.dat" start="100"
width="20" />
Sample usage (check all):
<assert-domain-measure-value-eq name="bulylagtx" value="Test1" />
4.1.7 assert-domain-measure-value-ge Assert a domain measure value is greater than or
equal to an expected value. This tag can be run in a number of ways:
Check against a loadmeasure file:
By specifying <path>, <start>, and <width>, you can validate that the contents of a
measure are equal to the contents of a fixed-with loadmeasure file.
C-26 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Check against specified positions:
By providing <keys> or <namedkeys>, you can verify that all of the positions in your
specification are equal to the provided value. You can specify <keyint> to provide
positions at an alternate rollup.
Check entire measure:
If you do not supply a <keys>, <namedkeys>, or <path> tag, then rpac will assert that
every logical cell in the measure is equal to the value provided.
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
Sample usage (using keys):
<assert-domain-measure-value-ge name="bulylagtx" keyint="year" namedkeys=" 2007"
value="Test1"/>
Sample usage (using path):
<assert-domain-measure-value-ge name="bulylagtx" path="loadmeas.dat" start="100"
width="20" />
Sample usage (check all):
<assert-domain-measure-value-ge name="bulylagtx" value="Test1" />
4.1.8 assert-domain-measure-value-gt Assert a domain measure value is greater than a an
expected value. This tag can be run in a number of ways:
Check against a loadmeasure file:
By specifying <path>, <start>, and <width>, you can validate that the contents of a
measure are equal to the contents of a fixed-with loadmeasure file.
Check against specified positions:
By providing <keys> or <namedkeys>, you can verify that all of the positions in your
specification are equal to the provided value. You can specify <keyint> to provide
positions at an alternate rollup.
Check entire measure:
If you do not supply a <keys>, <namedkeys>, or <path> tag, then rpac will assert that
every logical cell in the measure is equal to the value provided.
Appendix: RPAS Test Automation
C-27
Schema
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
Sample usage (using keys):
<assert-domain-measure-value-gt name="bulylagtx" keyint="year" namedkeys=" 2007"
value="Test1"/>
Sample usage (using path):
<assert-domain-measure-value-gt name="bulylagtx" path="loadmeas.dat" start="100"
width="20" />
Sample usage (check all):
<assert-domain-measure-value-gt name="bulylagtx" value="Test1" />
4.1.9 assert-domain-measure-value-le Assert a domain measure value is less than or equal
to an expected value. This tag can be run in a number of ways:
Check against a loadmeasure file:
By specifying <path>, <start>, and <width>, you can validate that the contents of a
measure are equal to the contents of a fixed-with loadmeasure file.
Check against specified positions:
By providing <keys> or <namedkeys>, you can verify that all of the positions in your
specification are equal to the provided value. You can specify <keyint> to provide
positions at an alternate rollup.
Check entire measure:
If you do not supply a <keys>, <namedkeys>, or <path> tag, then rpac will assert that
every logical cell in the measure is equal to the value provided.
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
C-28 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
Attribute
Description
Category
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
Sample usage (using keys):
<assert-domain-measure-value-le name="bulylagtx" keyint="year" namedkeys=" 2007"
value="Test1"/>
Sample usage (using path):
<assert-domain-measure-value-le name="bulylagtx" path="loadmeas.dat" start="100"
width="20" />
Sample usage (check all):
<assert-domain-measure-value-le name="bulylagtx" value="Test1" />
4.1.10 assert domain-measure-value-lt Assert a domain measure value is less than an
expected value. This tag can be run in a number of ways:
Check against a loadmeasure file:
By specifying <path>, <start>, and <width>, you can validate that the contents of a
measure are equal to the contents of a fixed-with loadmeasure file.
Check against specified positions:
By providing <keys> or <namedkeys>, you can verify that all of the positions in your
specification are equal to the provided value. You can specify <keyint> to provide
positions at an alternate rollup.
Check entire measure:
If you do not supply a <keys>, <namedkeys>, or <path> tag, then rpac will assert that
every logical cell in the measure is equal to the value provided.
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
Appendix: RPAS Test Automation
C-29
Schema
Sample usage (using keys):
<assert-domain-measure-value-lt name="bulylagtx" keyint="year" namedkeys=" 2007"
value="Test1"/>
Sample usage (using path):
<assert-domain-measure-value-lt name="bulylagtx" path="loadmeas.dat" start="100"
width="20" />
Sample usage (check all):
<assert-domain-measure-value-lt name="bulylagtx" value="Test1" />
4.1.11 assert-domain-measure-value-ne Assert a domain measure value is not equal to an
expected value. This tag can be run in a number of ways:
Check against a loadmeasure file:
By specifying <path>, <start>, and <width>, you can validate that the contents of a
measure are equal to the contents of a fixed-with loadmeasure file.
Check against specified positions:
By providing <keys> or <namedkeys>, you can verify that all of the positions in your
specification are equal to the provided value. You can specify <keyint> to provide
positions at an alternate rollup.
Check entire measure:
If you do not supply a <keys>, <namedkeys>, or <path> tag, then rpac will assert that
every logical cell in the measure is equal to the value provided.
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
Sample usage (using keys):
<assert-domain-measure-value-ne name="bulylagtx" keyint="year" namedkeys=" 2007"
value="Test1"/>
Sample usage (using path):
<assert-domain-measure-value-ne name="bulylagtx" path="loadmeas.dat" start="100"
width="20" />
Sample usage (check all):
<assert-domain-measure-value-ne name="bulylagtx" value="Test1" />
C-30 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
4.1.12 assert-domain-popcount-eq Assert a domain measure popcount matches an
expected value.
Attribute
Description
Category
name
Measure name
Required
pop-count
Expected popcount
Required
Sample usage:
<assert-domain-popcount-eq name=" Ipopappenbb" pop-count="100" />
4.1.13 assert-domain-popcount-eq-zero Assert a domain measure is not populated.
Attribute
Description
Category
name
Measure name
Required
Sample usage:
<assert-domain-popcount-eq-zero name=" Ipopappenbb" />
4.1.14 assert-domain-popcount-ne-zero Assert a domain measure is populated.
Attribute
Description
Category
name
Measure name
Required
Sample usage:
<assert-domian-popcount-ne-zero name=" Ipopappenbb" />
4.1.15 assert-bitsize-value-eq Assert the dimInfo bitsize or dimregistry bitsize value of a
dimension.
Attribute
Description
Category
name
List of comma separated dimension
names
Required
category
Bit Size Category (dimInfo or
dimRegistry)
Required
value
Comma separated Bit Size Values
Required
Sample usage:
<assert-bitsize-value-eq name="week,skup," category="dimInfo" value="12,14" />
4.1.16 assert-dim-registry-version Assert the value for dimension registry version.
Attribute
Description
Category
value
Registry version
Required
Sample usage:
<assert-dim-registry-version value="1"
/>
Appendix: RPAS Test Automation
C-31
Schema
4.1.17 assert-reindex-threshold Assert the Threshold value of the dimension.
Attribute
Description
Category
name
List of comma separated dimension
names
Required
value
List of Comma separated threshold
values
Required
Sample usage:
<assert-reindex-threshold name="scls,week" value="25,103" />
4.1.18 assert-reindex-required Assert whether Diminfo Bitsize is equal to DimRegistry
Bitsize.
Attribute
Description
Category
bitsize-flag
Returns true if Bitsize mismatch
occurs
Required
name
Dimension Name
Required
Sample usage:
<assert-reindex-required name="week" bitsize-flag="false" />
4.1.19 assert-reindex-in-progress Assert the status of reindex with the user input.
Attribute
Description
Category
flag
Flag to indicate whether Reindexing
Domain is in progress
Required
Sample usage:
<assert-reindex-in-progress flag="false"
/>
4.2 Domain Data Edit Operations
4.2.1 clear-all-measures Clears all measures used in the following tags:
<edit-workbook-measure>, <set-workbook-measure>, <set-domain-measure>.
This sets all the contents of these measures to the NA value.
4.2.2 clear-domain-measure Clear a domain measure of all data. This sets all the contents
of this measure to its NA value.
Attribute
Description
Category
name
Measure name
Required
Sample usage:
<clear-domain-measure name="r_ex_pick_real" />
C-32 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Schema
4.2.3 clear-domain-measure-list Clear a list of domain measures of all data.
Attribute
Description
Category
path
Path to a file containing a new-line
delimited list of measures
Required
Sample usage:
<clear-domain-measure-list path="measlist.txt" />
4.2.4 execute-expression Execute an expression.
Attribute
Description
Category
expression
The expression to execute/calculate.
This is a full expression string,
Optional
incremental
True if this is to be an incremental
evaluation
Optional
Sample usage:
<execute-expression expression="a = b+c" incremental="false" />
4.2.5 set-domain-measure Set the value of a domain measure based on provided
attributes.
Attribute
Description
Category
name
Measure name
Required
keys
The list of comma separated position
names
Optional
namedkeys
The list of comma separated position
names
Optional
path
Path to load measure type file to
compare to
Optional
keyint
Intersection string
Optional
value
Expected value
Optional
start
Starting column of measure field
Optional
width
Width of measure field
Optional
incremental
True if evaluation is to be incremental Optional
Sample usage:
<set-domain-measure name="r_ex_pick_real" keyint="dept" keys="1" value="150"
type="real" />
For Date type measures, RPAC supports setting the array cell
using either of the following two Date & Time formats "%m/%d/%Y" or "%m/%d/%Y-%H:%M:%S" where m = 2 digit
month, d = 2 digit date, Y = 4 digit year, H = 2 digit hour, M = 2 digit
min, and S = 2 digit sec.
Note:
Appendix: RPAS Test Automation
C-33
Schema
Sample usage (using keys):
<set-domain-measure name="meas1" keys="0-2:5"
value="0.0" />
Sample usage (using keyint):
<set-domain-measure-value-ne name="meas2" namedkeys="chnl1:week1"
value="02/24/2012" />
Sample usage (load-measure file):
<set-domain-measure name="meas1" path="loadMeas1.dat" start="100" width="20"/>
Sample usage (set all):
<set-domain-measure name="meas1" value="2"
C-34 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
D
Appendix: Environment Variables
D
RPAS includes a number of environment variables that are set at the system level in
UNIX. At the system level, the variables are applicable to all RPAS Servers
(DomainDaemons) that are run on the system.
The common syntax for setting these variables is as follows:
export ENVIRONMENT_VARIABLE=XXXXXX
ENVIRONMENT_VARIABLE is a defined variable that is recognized by RPAS. XXXXXX is
an appropriate value for the variable, which could be a string, Boolean value, numeric
value, or date/time. If the value represents time, this number normally represents time
in milliseconds.
The DomainDaemon must be restarted after setting any
environment variables. An example of how this process is completed
is as follows:
Note:
DomainDaemon -port 55123 -start -debug &
This appendix describes the following environment variables used for RPAS:
■
Required Settings
■
Database Settings
■
■
–
RPAS_CACHE
–
RPAS_PAGE_SIZE
–
RPAS_PAGE_SPLIT_PERCENTAGE
–
RPAS_LOCK_TIMEOUT
–
RPAS_USER_MODE
Log Settings
–
RPAS_LOG_BACKUPS
–
RPAS_LOG_LEVEL
–
RPAS_LOG_PATH
Profiling Logging
–
RPAS_PROFILING_ENABLE
–
RPAS_PROFILING_PATH
Appendix: Environment Variables
D-1
Required Settings
■
■
Date and Time Setting
–
RPAS_TODAY
–
RPAS_TODAY_STATIC
Numeric Precision
–
RPAS_INCAGGPRC
–
epsilon
■
RPAS_PROCESSES
■
LDR_CNTRL=NAMEDSHLIB=RPASZONE
Required Settings
The following environment variables are required.
■
RPAS_HOME
■
RIDE_HOME
■
RIDE_OPTIONS
■
JAVA_HOME
■
RPAS_JAVA_CLASSPATH
■
PATH
Since these environment variables are required at the time of installation, and since
they vary according to the operating system that RPAS is running on, these
environment variables are described in the "Installing on UNIX and Linux
Environments" chapter of the RPAS Installation Guide. See that chapter for detailed
instructions for those environment variables.
Database Settings
These variables are used for RPAS B-tree storage performance.
RPAS_CACHE
RPAS_CACHE determines the number of pages of a BTree array file that are contain in
memory. This variable can be set to have values between 16 and 512 (including 16 and
512). The larger you set the cache value, the more memory usage and less disk access
you have.
If you set the cache size from 4 to 64, the performance of the BTree arrays should level
out around 16 pages. In tests, more pages did not provide better performance.
Although, for other access patterns, more cache pages may improve performance.
Therefore, a larger cache and page size may increase performance due to less disk
access. However, having a larger cache and page size increases the memory image of
an open BTree file. It is likely that if the number of cache elements is 512 and the page
size is 256K, then each open BTree file could use up to 131,072K of memory.
export RPAS_CACHE=16
Values: 4, 8, 16, 32, 64, 128, 256, 512
D-2 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Database Settings
RPAS_PAGE_SIZE
RPAS_PAGE_SIZE determines the size of a single BTree array page if the logical size of
the BTree array is greater than 200,000 cells. A BTree array is compose of a number of
pages and page types. Each page of a BTree array file is the same size. In the trunk,
there are five pages types: header, branch, leaf, data, and free. A larger page size
implies more memory usage, less fragmentation, and less disk access.
The page size also affects the disk overhead that each BTree file requires. A large page
size may provide better disk usage if the array is densely pack. However, large page
size with a loosely pack array uses more disk space. For example, consider the effect of
having 1,000,000 cells with only one cell populated on a 256K page versus one cell
populated on a 16K page. The first case requires 256,000,000K of disk space while the
second requires 16,000,000K of disk space.
Therefore, RPAS_PAGE_SIZE and RPAS_CACHE both affect performance based on
the access pattern. RPAS_PAGE_SIZE affect disk space and memory usage, and RPAS_
CACHE affect the memory usage.
export RPAS_PAGE_SIZE=32K
Values: 4K, 8K, 16K, 32K, 64K, 128K, 256K
RPAS_PAGE_SPLIT_PERCENTAGE
This variable sets the page split percentage. The page split percentage determines the
percentage of low order keys to keep in the low order page of the B-Tree when a full
page is being split to accommodate data for a new key. It is expressed as a number
between 1 and 100. RPAS stores non-NA values only. If an operation (load or
calculation) causes a value to be non-NA, RPAS tries to store it on a page and, if the
page is full, it causes it to split. Page splitting is an expensive operation, that is, it takes
a significant amount of processing time and if it happens too often, it can significantly
slow down the load or calculation process causing the splits. For efficient storage and
to prevent pages from being split very often, it is recommended that the value be kept
between 50 and 90. If this environment variable is not set, RPAS uses a page split
percentage of 90.
RPAS_LOCK_TIMEOUT
This environmental variable sets the maximum number of milliseconds to wait for a
database lock. The default value, 60,000, forces a database lock to wait for a maximum
of one minute before throwing a database lock exception.
export RPAS_LOCK_TIMEOUT=60000
Values: 60000, 90000, 120000, and so on
When performing certain operations, it is possible for two or more users to be
contending for access to the same database, which happens most commonly when two
users attempt to simultaneously commit/save the same data back to the domain. This
can also apply when running RPAS utilities in parallel to prevent database locking
during batch operations. By default, RPAS is set up to wait one minute before
returning a lock contention error when this situation occurs.
Appendix: Environment Variables
D-3
Database Settings
If desired, an administrator can override this default value by setting the RPAS_
LOCK_TIMEOUT environment variable. This variable is set to the number of
milliseconds to wait for a file lock before returning a lock contention error. As with any
environmental variable, the variable must be set prior to starting the process that uses
that variable. The variable was introduced for use with the RPAS database server,
which means that the variable is set for the DomainDaemon.
For example, the line below indicates how an administrator would tell RPAS to wait
two minutes before returning a lock contention error with the RpasDbServer after
launching the client and logging in. Any client that connects to that domain daemon
would see lock contention after a two minute delay:
Export RPAS_LOCK_TIMEOUT=120000
On the client side, the exception sent from the server will appear as a warning dialog
box only after some new action is initiated. With the client, there will be additional
warning dialog boxes displayed to the user.
RPAS_REQUEST_TIMEOUT
The RPAS_REQUEST_TIMEOUT environment variable is also used to handle issues
with firewalls and the RpasDbServer. The RpasDbServer checks RPAS_REQUEST_
TIMEOUT to determine what should happen when it has been idle for a period of
time. Like any environmental variable that RpasDbServer uses, this environmental
variable must be set prior to starting the DomainDaemon.
The environmental variable RPAS_REQUEST_TIMEOUT should be set to a value that
is the number of seconds of idle time that should pass before the RpasDbServer sends
a “Server has timeout waiting for a request” exception to the client and exits. In this
case, idle time is the time waiting for a request. If this variable is not present or is set to
zero, then the RpasDbServer will never time out.
export RPAS_REQUEST_TIMEOUT=600
Values: 600, 900, 1200, and so on
RPAS_USER_MODE
This environment variable determines how the DbCloser class behaves. It controls
whether the DbCloser aggressively closes databases. The “single” value puts the
DbCloser is single user mode. This is useful for running batch processes when no
users are logged in, which means that there is no need to rapidly close databases.
export RPAS_USER_MODE="single"
Value: single
D-4 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
Log Settings
Log Settings
The following environment variables can be used for log settings.
RPAS_LOG_BACKUPS
The RPAS_LOG_BACKUPS environmental variable sets the maximum number of log
files to keep.
export RPAS_LOG_BACKUPS=20
Values: 2, 3, 4, 10, 20, 30, and so on
The RPAS_LOG_BACKUPS environment variables allow an administrator to define
the number of log file backups to retain for a given user. A log file is created each time
for each session that a user has with the RPAS Client.
The environment is set by executing the following command:
Export RPAS_LOG_BACKUPS=X
X is an integer value that represents the number of backup log files to keep for each
user.
RPAS_LOG_LEVEL
The RPAS_LOG_LEVEL environmental variable sets the default logging level to use
when an application starts.
export RPAS_LOG_LEVEL="debug"
Values: all, profile, debug, audit, information, warning, error, none
RPAS_LOG_PATH
The RPAS_LOG_PATH environmental variable contains the path of a directory where
RPAS daemon applications creates log files. The default is the current working
directory where the application was started from.
export RPAS_LOG_PATH=" C:/RPAS/Domains/Temp"
Value: The absolute path to the directory where RPAS daemon applications creates log
files
Appendix: Environment Variables
D-5
Profiling Logging
Profiling Logging
The following two environment variables may be setup to control profiling logging:
RPAS_PROFILING_ENABLE
The RPAS_PROFILING_ENABLE environment variable, when set to true, allows
profiling data to be written to the profiling log file. This flag does not affect writing to
general RPAS log file, which is controlled solely by loglevel.
RPAS_PROFILING_PATH
The RPAS_PROFILING_PATH environment variable defaults to rpasProfile.log if not
present. This variable specifies the profiling log file name. It can be overridden
programmatically in the constructor of the profiling timer.
Date and Time Setting
The following environment variables can be used to set the date and time.
RPAS_TODAY
RPAS_TODAY tells RPAS what day that it should think today is.
RPAS_TODAY=20090530
RPAS_TODAY_STATIC
The RPAS_TODAY_STATIC environment variable affects how date and time and the
RPAS_TODAY environment variable are handled. The setting of RPAS_TODAY_
STATIC affects the date and time that is returned by the DateTime::now() function.
■
If RPAS_TODAY_STATIC is set to true, all calls to DateTime::now() return the
same date and time as the first call made to the DateTime::now() function. The
same date and time is returned no matter how many times the DateTime::now()
function is called.
For example, RPAS_TODAY_STATIC is set to true and RPAS_TODAY=20090530. If
a call is made to DateTime::now() at 10:30 pm, it returns a date and time of
5/30/2009 10:30:00 pm. If another call is made 10 minutes later to
DateTime::now(), a date and time of 5/30/2009 10:30:00 pm is also returned.
■
If RPAS_TODAY_STATIC is set to false, a call to DateTime::now() returns the
current date and time.
For example, RPAS_TODAY_STATIC is set to false and RPAS_TODAY=20090530.
If a call is made to DateTime::now() at 10:30 pm, it returns a date and time of
5/30/2009 10:30:00 pm. If another call is made 10 minutes later to
DateTime::now(), a date and time of 5/30/2009 10:40:00 pm is returned.
■
User level environment variable TZ (time zone) needs to be set for the user who
starts the RPAS server processes (DomainDaemon, RPAS ODBC Server) or runs
RPAS utilities (like printMeasure). A missing TZ will cause the system to
misinterpret the date value stored in RPAS. For example, on a Linux system, the
default DATE type measure NA value of 0001/01/01 would be interpreted as
7295/12/31 23:00:00.000 if TZ were not set.
D-6 Oracle Retail Predictive Application Server Administration Guide for the Classic Client
RPAS_PROCESSES
If the user is in time zone EST5EDT, use the command export TZ=EST5EDT to
set TZ. It is suggested that the command be added to user's login script (for
example, .profile).
Numeric Precision
There are two variables that affect the level of numeric precision that is displayed in
the RPAS clients:
■
RPAS_INCAGGPRC: An environment variable.
■
epsilon: The smallest difference that is allowed between any two numbers.
RPAS_INCAGGPRC
Use the RPAS_INCAGGPRC environment variable to set how a number's precision is
displayed. Set this variable to the precision level you want displayed. The default
value of this variable is 1e-06. Unless this variable is altered, very small values, such as
0.00000001, are displayed as 0.
Below is an example of setting this variable to a value smaller than the default.
export RPAS_INCAGGPRC=0.0000000001
epsilon
The epsilon variable also affects the level of precision that is displayed. This variable is
returned as a value by a public static function in the MathUtilities.h file. It is
hardcoded to 0.0000000001 (1e-09).
RPAS uses the epsilon value to consider any two numbers as different if the difference
is greater than or equal to epsilon. If the difference between any two numbers is less
than epsilon, then those numbers are considered as equal. Indirectly, the epsilon value
affects the display as it sets a limit to the number precision.
Note:
Reducing the epsilon value may impact performance.
RPAS_PROCESSES
This variable is used when performing batch measure registration. It sets the
maximum number of processes used to stage data. The default is 1, which results in all
processes being run serially.
If a user specifies a value less than 1, it will override to 1. If a user specifies a value
greater than the number of subdomains, it will be override to the number of
subdomains in the global domain. If this variable is set to a number greater than 1
when doing a measure registration in a global domain, RPAS spawns that number of
parallel processes to register or unregister measures in each local domain.
export RPAS_PROCESSES=4
Values: 1, 2, 3, 4, and so on
Appendix: Environment Variables
D-7
LDR_CNTRL=NAMEDSHLIB=RPASZONE
LDR_CNTRL=NAMEDSHLIB=RPASZONE
This environment setting performs two functions:
■
It creates a special named zone in the memory to load shared libraries for RPAS
processes to avoid version conflict.
By default, AIX loads shared libraries in a single global zone. This could
potentially cause conflict between the libraries on the system and RPAS versions.
For example, RPAS has its own version of libz. If a non-RPAS program has loaded
a different version of libz from the system into the global zone, RPAS would use
that one instead of loading its own.
■
It may also reduce the memory footprint for shared libraries in the private
memory of RPAS processes.
The global zone can be filled up if the system is very busy. In that case, the shared
libraries are loaded into private space of RPAS processes, which would reduce the
amount of memory available for RPAS data. A named zone would be difficult to
fill up since it is used only by RPAS processes.
export LDR_CNTRL=NAMEDSHLIB=RPASZONE
D-8 Oracle Retail Predictive Application Server Administration Guide for the Classic Client