10 Customizing Retail Applications

This chapter discusses supported steps for customizing Retail applications.

Using Custom Shared Library for Adding Custom Content

When you want to add new content such as new pages, business components or even Java code into a Retail application, you need to create a custom shared library, deploy it into the same managed server as the Retail application, and register that library into the Retail application.

Refer to the WebLogic documentation, Developing Applications with WebLogic Server, to learn more about developing and deploying shared libraries in WebLogic.

A Retail application that allows for customization has as part of its installation an intermediary shared library that serves as a registry to reference the actual customer-built shared libraries. The diagram below shows the deployment of a Retail application with the Custom Shared Library Registry.

When you need to add your own content into the shell, metadata to register their content into the shell including the binaries for the content itself (e.g. task flows and pages) are expected to be packaged into a Web Archive (WAR) file and deployed as a shared library in the same managed server as the application itself.

Then, the names of these shared libraries have to be referenced in the Custom Shared Library Registry.

Creating and Deploying a Custom Shared Library

This section contains instructions on creating your own shared library that contains custom content you want to include in the Retail application UI Shell.

The steps in this section are required before you can customize a Retail application.

Download JDeveloper

To create the custom shared library, it is recommended that you download and install JDeveloper version 11.1.1.7.0 by using the following link:

http://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.html

Create the Custom Shared Library Workspace through JDeveloper

The JDeveloper contains the code for any custom content you want to add to the Retail application. Through JDeveloper, a shared library Web Archive file (.WAR) can be generated which can be deployed on the same managed server as the Retail application.

To create and configure the Custom Shared Library Workspace, take the following steps:

Open JDeveloper and choose Developer Role when prompted.
Create a new Fusion Web Application JDeveloper workspace.
1. Go to File à New to invoke the New Gallery window. Choose Fusion Web Application (ADF) as the type of application to create and click OK.
2. Provide a meaningful application name, a directory path to the workspace, and an application (Java) package prefix. Click Finish.
3. The JDeveloper generates a new workspace with two projects: Model and View-Controller.
Add a Manifest file containing the name of the shared library.
1. Right-click on the View-Controller project and choose New from the Context menu.
2. The New Gallery window appears. Choose the option, File (General), in the All Technologies section of the window. Click OK.
3. The Create File window opens. For the File Name, specify MANIFEST.MF. For the Directory, the new file must be added under the src/META-INF sub-directory under the View-Controller project's directory.
4. Edit the new MANIFEST.MF file and add the following entries:
```
Manifest-Version: 1.0
Implementation-Vendor: companyName
Implementation-Title: Custom Shared Library for companyName
Implementation-Version: 1.0
Extension-Name: companyname.custom.shared.lib
Specification-Version: 1.0
Created-By: companyName
```
  Modify the contents such meaningful and unique values are used for Implementation-Vendor, Implementation-Title, Extension-Name and Created-By. Example:
```
Manifest-Version: 1.0
Implementation-Vendor: Acme Retail
Implementation-Title: Custom Shared Library for Acme Retail
Implementation-Version: 1.0
Extension-Name: acmeretail.custom.shared.lib.procurement
Specification-Version: 1.0
Created-By: AcmeRetail
```
Create a deployment profile for the shared library.
1. Right-click on the View-Controller project and choose New from the Context menu.
2. The New Gallery window appears. Choose the option, WARFile (Deployment Profiles), in the All Technologies section of the window. Click OK.
3. Provide a unique and meaningful name for the Deployment Profile and click OK.
4. The Edit WAR Deployment Profile Properties window appears.
5. Under the General section, make sure that the Specify Java EE Web Context Root is selected without any value. Click OK.
  
  You are prompted to confirm that you really want a blank context root. Click Yes to confirm.
6. Under the WAR Options section, enable the Include Manifest File option and Add the MANIFEST.MF file you created under …/View-Controller/src/META-INF.
7. Click OK.

Generate and Deploy the Custom Shared Library WAR

To generate and deploy the Custom Shared Library WAR file, take the following steps:

Generate the share library WAR file through JDeveloper.
1. Open the Custom Shared Library workspace.
2. Right-click on the View-Controller project and choose the shared library WAR deployment profile created previously under the Deploy option.
3. The Deploy window appears. Select Deploy to WAR and click Finish.
4. The JDeveloper generates the WAR file into the View-Controller project folder sub-directory, deploy.
Deploy the generated WAR file to the same managed server as the Retail Application as a shared library. For more information, see the section Deploying Applications to Oracle WebLogic Server documentation (http://docs.oracle.com/cd/E23943_01/web.1111/e13702/deploy.htm). This task should be completed using the WebLogic Administration Console or Enterprise Manager Fusion Middleware Control with a user having WebLogic administrator permissions.

Reference the Custom Shared Library from the Retail Application

A Retail application, that can be customized, includes in its deployment an intermediary shared library that serves as a registry for any other shared libraries that you want to include during runtime of the Retail application.

Once you create and deploy your own custom shared library by following the steps in this section, you must modify the configuration of the Custom Shared Library Registry to add references to your shared library.

Take the following steps:

Log in to the WebLogic Administration Console as a user with administrative permissions.
If the Administration Console was configured with domain configuration locking, click Lock & Edit to ensure that other administrators can be prevented from making changes during your edit session.
Navigate to the Deployments section.
Look for the Retail application deployment and shut it down. Choose Force Stop Now when appropriate. Wait for the shutdown process to complete.
Get the deployment location of the Retail application's custom shared library registry. Under the deployments list, click on the link for the library named oracle.retail.apps.alc.portal.extensions. The Settings window for the library appears.

The Settings window displays the file location of the registry's WAR file under the Path entry.

Make a note of this file location.
Using the operating system's file manager application, go to the location of the WAR file. You need read and write permissions to the file system where the WAR file is located.
Make a copy of the WAR file as back-up.
Open the original WAR file using an archive file manager and update the /WEB-INF/weblogic.xml by adding a new <library-ref> entry pointing to your custom shared library.
```
<library-ref>
<library-name>companyname.custom.shared.lib</library-name>
</library-ref>
```
Note:
The library-name has to match the Extension-Name you provided in your custom shared library's MANIFEST.MF file.

Once this change is done, you have now linked your custom shared library to the Retail application.
Return to the WebLogic Administration Console. Under Environments' Servers > Control tab, select the managed server where the Retail application is deployed. Shut it down and restart it.

Adding Custom Content into the Custom Shared Library

The Custom ADF and Java based components that add new content or functionality into the Retail application can be coded or built into the Custom Shared Library workspace. Typically, you can include task flows that add new UI work flows into the Retail Application UI Shell.

The WAR for the Custom Shared Library needs to be regenerated when new content is added.

To re-deploy the Custom Shared Library WAR, the Retail application and its Custom Shared Library Registry must both be shutdown first.

Since Retail applications are secured Web applications, the addition of new ADF UI pages and task flows need to be secured using the application roles and policies that are recognized by the Retail application. The provisioning process is done using the Oracle Enterprise Manager Fusion Middleware Control Console.

For more information, see Managing the Policy Store section of the Oracle Fusion Middleware Application Security Guide. (http://docs.oracle.com/cd/E23943_01/core.1111/e10043.pdf).

Customizing the Retail Application User Interface

Retail applications can provide you the capability to add and display custom content such as ADF task flows and URL to BI reports in the deployed application. These custom contents can be accessed from the Retail Application's UI Shell.

Overview of a Retail Application User Interface Shell

Retail applications are built on top of the Retail Fusion Platform which provide common reusable features that Retail applications can share.

One such feature is the Retail Application UI Shell.

The UI Shell organizes the contents of the application into visual containers that fulfill common layout and navigational requirements in a structured, consistent manner.

The high level containers or areas in the shell are highlighted in the diagram below:

The Global Area presents branding, logged-in user information as well as menus that allow you to switch to other areas of the application. Notifications are also visually represented as an icon in this area.

The Sidebar Area is a collapsible area on the left of the window. A typical content of the sidebar area is the task navigation tree. Each node on the tree presents a business process or task that opens UI workflow windows in the Local Area.

The Local Area is the main content area for the application. The contents change as a result of actions selected in the Sidebar or Global Area. Typically, task flows are opened as tabs within the Local Area.

The Contextual Area is a collapsible area on the right of the window which provides space to present information that can assist users in completing their tasks. The Contextual Area is presented per Local Area tab. Each task flow in presented in the local area can have their own contextual area.

Adding a Dashboard

A dashboard is a window within a Retail application that displays the current status of metrics and key performance indicators relevant to the Retail application. They are typically tailored for specific roles and they allow you to easily monitor the status of the current data within the application.

For Retail applications, dashboards are typically built and maintained in a separate BI reporting tool. Oracle Retail recommends using Oracle Business Intelligence Enterprise Edition (OBIEE). Whatever the tool you use, the resulting dashboards must be accessible in a Web browser via a URL.

The following is an example dashboard built in OBIEE:

The dashboards can be added into a Retail application which you can launch from the application's UI Shell sidebar task tree.

The dashboard windows are added into a Retail application by adding and configuring the application's sidebar Navigation Model XML file into the Custom Shared Library.

The following example displays the dashboard window as rendered in the local area of a Retail application's UI Shell:

Preparing the Custom Shared Library for Adding Dashboards

To prepare the Custom Shared Library to add dashboard pages into the Retail application, take the following steps:

Perform the steps to create a Custom Shared Library workspace, generate a shared library WAR out of it, deploy the WAR, and associate the library to the Retail application.

Obtain a copy of the application's sidebar navigation model XML file.

EarAllocCore.ear\AlcPublicUIViewController.war\WEB-INF\classes\oracle\retail\apps\framework\uishell\config\custom\HomeSidebarNavigationModel.xml

Using the JDeveloper, open the Custom Shared Library workspace in the Developer Role.
Add the sidebar model XML file in the View-Controller project src directory, preferably under a sub-directory called Custom.

For example:

If the sidebar navigation model is named HomeSidebarNavigationModel.xml,then that file's path must be View-Controller/src/custom/HomeSidebarNavigationModel.xml.
Add a new file called PageTemplateOverrideModel.properties under the View-Controller/src directory. Modify this file and add the following entry:
```
Home.sidebarModel=<path to sidebar model xml within view-controller/src>
```
For example:
```
Home.sidebarModel=/custom/HomeSidebarNavigationModel.xml
```
Verify the location of the files in the workspace.
Regenerate the shared library WAR file from the workspace and redeploy the shared library. Make sure you shutdown and restart the Retail application and its shared library registry as a part of this step.
Test the Retail application. The original sidebar contents of the Retail applications should be accessible.

The succeeding sections describe the steps to modify the model in order to add dashboard pages into the Retail application.

Adding a Dashboard into a User Interface Shell Sidebar

Adding a dashboard window so that it is accessible from the sidebar area of the Retail application's UI Shell primary entails the modification of the Sidebar Navigation Model XML file. The sidebar area renders a collection of links organized or grouped into folders. Each link represents content that launches into a tab in the UI Shell's local content area. A content is typically a workflow that allows you to accomplish specific tasks in the application. The content can be a dashboard page.

Before adding a dashboard into the UI Shell Sidebar, you must have:

Built, prepared, deployed, and tested the Custom Shared Library as described in the section.
Created one or more dashboard pages in their BI reporting tool (e.g. OBIEE).
- The Web URL for the dashboard pages must be available in order to proceed with the steps in this section.
- Any parameters to modify the content of the dashboard must be known and should be accessible as parameters to the dashboard's URL.

Once the above pre-requisites have been satisfied, take the following steps:

Open the Custom Shared Library workspace in JDeveloper.
Open the application's Sidebar Navigation Model XML file (ex. View-Controller/src/custom/HomeSidebarNavigationModel.xml).
Go to the bottom of the file and add a new folder into the list. A folder is represented by an <Item>/<Items> pair of XML elements of type "folder". These have to be added within the top most <Items> tag.
```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NavigationDefinition … >
<Items>
... (existing contents)

<Item id="myCustomDashboardFolder" title="My Custom Dashboards" type="folder">
<Items>

</Items>
</Item>
</Items>
</NavigationDefinition>
```
Provide a unique identifier to the Item and meaningful values for the title attributes of the Item tag. For this example, we are assuming that the folder title is "My Custom Dashboards".
Add an <Item> element within the folder that references the dashboard page URL as well as the parameters to control the view of the dashboard if available.

The following example shows an <Item> element that links to a BI dashboard URL with six parameters:
```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NavigationDefinition … >
<Items>
... (existing contents)
<Item id="myCustomDashboardsFolder" title="My Custom Dashboards" type="folder">
<Items>
<Item id="myDashboard1"
type="link"
title="Profitability Dashboard">
<url> <![CDATA[http://mspdv171.us.oracle.com:9704/analytics/saw.dll?SyndicatePages&syndicate=portal&PortalPath=/shared/Customer Order/_portal/Customer Order&Page=Channel Profitability Comparisons&Action=Navigate]]>
</url>
<Parameters>
<Parameter id="col1">"Business Calendar"."Fiscal Year"</Parameter>
<Parameter id="val1">"2010"</Parameter>
<Parameter id="psa1">"Retail Merchandising Analytics As-Was"</Parameter>
<Parameter id="col2">"Business Calendar"."Fiscal Quarter"</Parameter>
<Parameter id="val2">"2010Quarter1" "2010Quarter2" "2010Quarter3"</Parameter>
<Parameter id="psa2">"Retail Merchandising Analytics As-Was"</Parameter>
</Parameters>
</Item>
</Items>
</Item>
</Items>
</NavigationDefinition>
```
To create this element, note the following attributes and sub-elements:
- The <Item> type must be set as "link".
- The <Item> title must be meaningful.
- The <Item> id attribute must be unique across all the other items in the XML file.
- The <url> sub-element within <Item> indicates the URL to the dashboard page built in the BI tool. The entire URL must be marked as character data (e.g. enclosed in CDATA).
- The <Parameters> sub-element within <Item> should list all the parameters to the dashboard page if there are any. Each parameter is represented as a <Parameter> element inside <Parameters>.
  - The <Parameter> id should be the actual parameter reference name recognized by the dashboard URL.
  - The value of each <Parameter> is a string value. This is the only supported data type.
Regenerate the Custom Shared Library WAR file from the Custom Shared Library workspace. Shutdown the Retail application and its Custom Shared Library Registry, redeploy the Custom Shared Library WAR file, and restart the Retail application components.
Test the Retail application. Log in and note that a link to the BI dashboard appears in the UI Shell's sidebar task tree under a folder "My Custom Dashboards".

Securing Dashboard Access to Specific Roles

To restrict access to the dashboard added on the sidebar to specific security roles, set the visible property on the <Item> element for the dashboard URL to an Expression Language (EL) expression that calls ADF's securityContext API's isUserInRole method. For example:

<Item id="myDashboard1"
type="link"
title="Profitability Dashboard"
visible="#{securityContext.isUserInRole['BUYER_JOB']}" >

The parameter to the securityContext.isUserInRole method is a logical security role that is configured for the Retail application. The API returns true if the user is included in the specified security role. If the user is not authenticated or is not found in the role, the API returns false.

Adding Contextual Reports

Contextual reports are reports that appear in a task flow's contextual area section. The Contextual Area is a collapsible section to the right of the local area that provides a space to present information that can assist you in completing your tasks.

Since information presented in a contextual area is presented depending on the task or workflow you are on, contextual areas are associated with task flows and there can be at most one contextual area per task flow.

Within a contextual area, multiple contextual reports can be configured.

Each contextual report can change its contents depending on the action being performed in your current workflow.

For example - Metrics pertaining to an item included in an allocation being maintained by you can be displayed in the Allocation Maintenance Flow. As you click through the list of items, the corresponding metrics on contextual area change.

Each task flow publishes the contextual business events on key activities taking place on the screen. Contextual reports can listen to those events and change its contents depending on the payload information associated with the event.

Contextual reports are typically built and maintained in a separate BI reporting tool. Oracle Retail recommends using Oracle Business Intelligence Enterprise Edition (OBIEE). Whatever the tool you use, the resulting reports must be accessible in a Web browser via a URL.

The contextual reports are added in a Retail application by adding and configuring the task flow's contextual area model XML file into the Custom Shared Library.

Retail applications can also provide you with the list of possible contextual business events each flow generates that you can configure the contextual reports to react to. Examples of this event include an item being selected, a recalculation being triggered, or a location being selected. Each event includes information about the event's payload information (example: the item ID of the item being selected in an Allocation Maintenance screen).

List of Contextual Business Events and Payloads

The following table lists the contextual business events and the payloads:

Event Name	Task Flow	Page	Contextual Area Model XML Location	Generated when…	Payload Values
AlcAllocMaintenanceItemReviewSelectedEvent	AllocationMaintenanceFlow	AllocMaintenancePage		Allocation Maintenance, Item Review row change	itemId allocId depatmentId classId subclassId diff1 diff2 diff3 wh doc docType
UpdateContextAwareReportEvent	AllocationMaintenanceFlow	AllocMaintenancePage		Allocation Maintenance, Item Review row change	itemId allocId depatmentId classId subclassId diff1 diff2 diff3 wh doc docType

Preparing the Custom Shared Library for Adding Contextual Reports

To prepare the Custom Shared Library to add contextual reports in Retail application task flows, take the following steps:

Perform the steps to create a Custom Shared Library workspace, generate a shared library WAR out of it, deploy the WAR, and associate the library to the Retail application.
Obtain a copy of the task flow contextual area model XML files where the contextual reports should be added.
Using JDeveloper, open the Custom Shared Library workspace in a Developer Role.
Add the contextual area model XML file in the View-Controller project src directory, preferably under a sub-directory called Custom.

For example:

If the contextual area model XML for the task flow AllocMaintFlow is called AllocMaintFlowContextualAreaModel.xml, then that file's path must be View-Controller/src/custom/AllocMaintFlowContextualAreModel.xml.

Add a new or open the existing file called PageTemplateOverrideModel.properties under the View-Controller/src directory. Modify this file and add the following entry:

Home.sidebarModel=<path to sidebar model xml within view-controller/src>
<FlowName>.contextualAreaModel=<path to the contextual area model for the flow>

For example:

AllocMaintFlow.sidebarModel=/custom/AllocMaintFlowContextualAreaModel.xml

Regenerate the shared library WAR file from the workspace and redeploy the shared library. Make sure you shutdown and restart the Retail application and its shared library registry as a part of this step.
Test the Retail application. Navigate to the flow and make sure the flow is functional.

Adding a Contextual Report To A Task Flow

Adding a contextual report to a task flow primary entails the modification of the task flow's Contextual Area Model XML file. Multiple reports can be added to the model. Each report is rendered in collapsible panel boxes.

Before adding a dashboard into the UI Shell Sidebar, the you must have:

Built, prepared, deployed, and tested the Custom Shared Library as described in the section.
Obtained information about the Retail Application's list of contextual business events that can be broadcast from various work flows.
Created one or more contextual BI reports in the BI reporting tool (e.g. OBIEE).
- The Web URL for each report must be available in order to proceed with the steps in this section.
- Any parameters to configure the content of the report must be known and should be accessible as parameters to the dashboard's URL.

Once the above pre-requisites have been satisfied, take the following steps:

Assume the following example scenario when following the steps:

A contextual report called "Item Metrics" showing information about an item should be added to the Allocation Maintenance Flow's main page. When you select an item on the page, the report displays information for the selected item.

The Retail application has provided the following information about the contextual business event:

Event Name	Task Flow	Page	Contextual Area Model XML Location	Generated when…	Payload Values
AlcAllocMaintenanceItemReviewSelectedEvent	AllocationMaintenanceFlow	AllocMaintenancePage		Allocation Maintenance, Item Review row change	itemId allocId depatmentId classId subclassId diff1 diff2 diff3 wh doc docType
UpdateContextAwareReportEvent	AllocationMaintenanceFlow	AllocMaintenancePage		Allocation Maintenance, Item Review row change	itemId allocId depatmentId classId subclassId diff1 diff2 diff3 wh doc docType

The Item Metrics report was built in the customer's BI reporting tool (e.g. OBIEE). It was built considering the payload values the contextual business event will generate.

Open the Custom Shared Library workspace in JDeveloper.
Open the task flow contextual area model XML file (ex. ViewController/src/custom/AllocMaintFlowContextualAreaModel.xml).
Add an <Item> element within the topmost <Items> element that reference the task flow called ViewContextAwareReportFlow. The ViewContextAwareReportFlow is a framework for rendering URL based reports that is aware of contextual business events emanating from the Retail aplication task flows.

For example:
```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NavigationDefinition … >
<Items>
...
...
<Item id="showItemMetric"
type="taskflow"
title="Item Metric">
<url>
/WEB-INF/oracle/retail/apps/framework/contextawarereport/publicui/flow/ViewContextAwareReportFlow.xml#ViewContextAwareReportFlow
</url>
</Item>
</Items>
</NavigationDefinition>
```
Note:
Note the following:

Make sure that the <Item> id is unique.

Make sure the <Item> type is "taskflow".

Provide a meaningful title.

Enter the parameters to the ViewContextAwareReportFlow by adding the following <Parameter>/<Parameters> elements:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NavigationDefinition … >
<Items>
<Item id="showCustomerMetric"
type="taskflow"
title="Customer Metric">
<url>
/WEB-INF/oracle/retail/apps/framework/contextawarereport/publicui/flow/ViewContextAwareReportFlow.xml#ViewContextAwareReportFlow
</url>
<Parameters>
<Parameter id="reportDescription">Item Metric</Parameter>
<Parameter id="actionType">AllocMaintItemSelectedEvent</Parameter>
<Parameter id="primaryUrl">
<![CDATA[http://companyobiee.com:9704/report/shared/itemMetric&paramItemId=<selectedItemId>&paramItemType=<selectedItemType:token01>&paramLanguage=<language>]]>
</Parameter>
<Parameter id="token01">regular</Parameter>
</Parameters>
</Item>
</Items>
</NavigationDefinition>

Note:

Note the following:

The <Parameter id="reportDescription"> element is the title of the contextual area report. Set this to a meaningful value.
The <Parameter id="actionType"> element indicates the contextual business event name the report listens to.
The <Parameter id="primaryUrl"> element indicates the URL for the contextual area report in the BI server. The entire URL must be marked as character data (e.g. enclosed in CDATA). Note how the parameters to the URL are tokenized.
- The "?paramItemId=<selectedItemId>" portion of the URL instructs the system to pass the contextual business event payload value called selectedItemId into the URL parameter paramItemId when rendering the contextual report.
- The "?paramItemType=<selectedItemType:token01>" portion of the URL instructs the system to pass the contextual business event payload value called selectedItemType into the URL parameter paramItemType when rendering the contextual report. If that payload value is empty or null at runtime, then a default value of regular is used as referenced in a <Parameter id="token01"> entry.
- The "?paramLanguage=<language>" portion of the URL instructs the system about your current locale. The "language" identifier is a reference to a value in the contextual event payload. This is a built-in value that exists in all Retail application contextual business event payloads.
The <Parameter id="token01"> element holds the default value for the URL parameter selectedItemType. Token parameters hold default values and you can define up to 20 default value tokens.

Re-generate the Custom Shared Library WAR file from the Custom Shared Library workspace. Shutdown the Retail application and its Custom Shared Library Registry, redeploy the Custom Shared Library WAR file, and restart the Retail application components.
Test the Retail application. Go to the flow where the report was added and verify that the report is rendered correctly.