| Oracle® Retail Home Oracle Retail Home Administration Guide Release 19.1 F35058-02 |
|
 Previous |
| Oracle® Retail Home Oracle Retail Home Administration Guide Release 19.1 F35058-02 |
|
Previous |
Retail Home provides three methods to seed configurations for applications. The first, discussed in Chapter 2, "Application Navigator Setup", is to press the seed data button on the application navigator configuration screen. Additionally, data may be loaded in bulk by using the standalone Retail Home Seed Utility or by making direct calls to the seed service.
The Retail Home Seed Utility is a standalone Java utility that populates the application list and dashboards of a Retail Home deployment. It takes a wallet containing admin credentials for Retail Home, a JSON template of application URL patterns, and a CSV of applications to load and populate. The JSON and a template of the CSV file are provided in an accompanying ZIP file.
The wallet for the seed utility is a standard Oracle Wallet containing the credential map oracle.retail.apps.platform.services.common.model.security with two keys:
idcsOAuthClient - IDCS application client ID and secret
idcsOAuthUser - Retail Home administrator username and password
The CSV file containing application information has two columns. The first column is the application code of the Retail application, which must correspond to an entry in the template JSON. The second column is the application host (the domain and port) of the external URL for the application.
There should be no need to modify the provided template JSON, which maps application codes to the format for the full application URL and the platform service URL (the application host value is substituted in for <app.host>).
The seed utility is invoked as follows:
java -jar RetailHomeSeedUtil.jar <Retail Home Host> <IDCS URL> <Wallet> <Application File> <Template File>
The Retail Home host is the protocol, domain, and port of the URL to Retail Home. The IDCS URL is the same to the IDCS tenant. The remaining fields are the paths (relative or absolute) to the files needed to run the utility.
When running, the utility may report that it was unable to retrieve seed data for one or more applications. This is normal behavior and means that the installed version of the application in question does not provide seed data.
In most cases it should be sufficient to let the application navigator page or seed utility call the seed service to upload seed data. However, in some cases, such as migrating configurations, a direct call may be more convenient. The seed service exposes a single endpoint/seed that can be called with either GET or PUT methods.
Calling the endpoint with GET will return the entire configuration of the Retail Home instance. Calling the endpoint with PUT allows uploading the configuration in the same format.
The general behavior of the seed utility is to merge configurations where possible. Most aspects of the configuration can be merged into existing settings. Some items cannot be matched to corresponding entries in the existing configuration however; in these cases the entire set of items will be replaced with the incoming configuration.
The following configurations will be replaced when loading seed data:
Application role mappings
Dashboard tile states for existing tiles
Application filters
All other configurations will be merged with incoming data.
The format for the seed data JSON is as follows:
| Property (*=required) | Type | Description |
|---|---|---|
| applications | Array | Array of Application objects to be configured |
| tiles | Array | Array of Tile objects to be configured |
| dashboards | Array | Array of Dashboard objects to be configured |
| properties | Array | Array of Property objects to be configured |
| reports | Array | Array of Report objects to be configured |
| filters | Array | Array of Filter objects to be configured |
Application entries represent applications registered with Retail Home.
| Property (*=required) | Type | Description |
|---|---|---|
| *name | String | Name of the application to display in Retail Home. Must be unique. |
| applicationCode | String | Unique identifier for Retail applications. Required for applications in a domain |
| *colorSetId | String | Color set to use for the application in Retail Home. See below for supported values |
| *active | Boolean | Whether the application is active. Inactive applications are not displayed in Retail Home. |
| applicationLink | String | The base URL to the application |
| platformService | String | The base platform REST service endpoint for the application.
Warning: Domains populate this value based on the domainUrl. Setting this will override the default value. |
| roles | Array | Array of Role objects the application is available to. Each role object has a single property containing the role name: validRole. When roles are enabled in Retail Home, this application will not be visible to other roles in application navigators after a publish. |
Tiles define available tiles to be displayed on dashboards.
| Property (*=required) | Type | Description |
|---|---|---|
| *tileName | String | The name of the tile to display in Retail Home. Must be unique. |
| *tileColor | String | The color to use for the tile. See below for supported colors. |
| url | String | The URL to launch when the tile header is clicked. Supports the <app.url> token when associated with an application, which indicates the tile will open relative to the application's applicationLink value. |
| applicationName | String | The name of the application this tile is associated with. Must be one of the applications defined in the seed data. |
Dashboard objects define the unique dashboard associated with a given role in Retail Home.
| Property (*=required) | Type | Description |
|---|---|---|
| *jobRoleName | String | The job role the dashboard is for. Only one dashboard can be created per role. |
| *active | Boolean | Whether the dashboard is active. Inactive dashboards are not displayed in Retail Home. |
| defaultDashboard | Boolean | Whether the dashboard is the default. Default dashboards will be preferentially displayed when opening Retail Home. |
| *tiles | Array | Array of Dashboard Tile objects on the dashboard. May be empty. |
| *regions | Array | Array of Region objects on the dashboard. May be empty. |
Dashboard tiles define an instance of a tile object shown on a given dashboard.
| Property (*=required) | Type | Description |
|---|---|---|
| tileSize | String | How much space to allocate to the tile. Supported values are "1x1" and "2x2". |
| *active | Boolean | Whether the tile is active. Inactive tiles will not be displayed in Retail Home |
| *tileName | String | The name of the tile being displayed. The name must be from the array of Tile objects in the seed data. |
| *tileStates | Array | Array of Tile States to display on the tile |
Tile states are the individual data views on dashboard tiles. Each tile state refers to reports configured for the application and can show both a tile state and expanded report. Reports are drawn from those already configured for the Retail Home deployment.
| Property (*=required) | Type | Description |
|---|---|---|
| *tileStateConfigId | String | ID of the tile state report to display |
| reportName | String | Name of custom report to display. Mutually exclusive with tileStateConfigId. |
| expandedReportConfigId | String | ID of the expanded report to display |
| *active | Boolean | Whether the tile state is active. Inactive tile states will not be displayed in Retail Home |
| *urlConfigurations | Array | Array of URL configurations configured as data sources for the tile state. No more than one active configuration per report type is allowed. |
Regions are the additional banner and contextual data view located above and beside the tiles in the dashboard. Reports are drawn from those already configured for the Retail Home deployment.
| Property (*=required) | Type | Description |
|---|---|---|
| *active | Boolean | Whether the region is active. Inactive regions will not be displayed in Retail Home |
| *reportConfigId | String | ID of the report to display in this region |
| *regionId | String | Which region this configures. Valid options are "Primary", "Secondary", and "Banner". No more than one configuration per region is allowed on a dashboard |
| *urlConfig | UrlConfig | The URL configuration set as the data source for the region |
URL configurations register the data sources for regions and tile states.
| Property (*=required) | Type | Description |
|---|---|---|
| *contentType | String | Type of report this is configuring. Valid options are "region", "tilestate", "expanded", and "filter". Tilestate and expanded are only valid for tilestates. Region is only valid for regions. Filter is only valid for filters (see below) |
| *resourceId | String | ID of the service this URL configures. |
| *resourceType | String | What type of URL this is. Valid options are "REST", "FILE", and "LINK" |
| *url | String | The URL. FILE type URLs may use relative paths. REST and LINK URLs are strictly validated and must contain a protocol if they do not use replacement tokens (details below). Replacement tokens are only supported for tile states. |
| *active | Boolean | Whether this configuration is active. Inactive URL configurations are ignored by Retail Home. |
Properties are used to turn on/off specific functionality on Retail Home.
| Property (*=required) | Type | Description |
|---|---|---|
| *propertyKey | String | Key defining the Retail Home functionality. Currently "oracle.retail.apps.retailhome." is used to Enable/Disable Roles flag on 'Application Navigator Setup'. |
| *currentValue | Boolean | Whether this configuration is enabled. |
Reports are custom reports configured using templates in Retail Home.
| Property (*=required) | Type | Description |
|---|---|---|
| *reportTemplateId | String | ID of the template for this report. |
| *reportName | String | Name of the report. |
| useLightBackground | Boolean | Whether to use a light background when displaying this report in a tile state. If false, the background will be drawn from the color set of the application. |
| *parameters | Array | Array of report parameters configuring this report. May be empty. |
Report parameters are used to configure the template of a custom report. The available and required parameters depend on the template being configured.
| Property (*=required) | Type | Description |
|---|---|---|
| *paramPath | String | ID of the parameter in the template |
| *paramType | String | Type of parameter. Valid options are "text" and "boolean". |
| *textValue | String | Value of the parameter as a string. |
Filter objects define filters associated with applications.
| Property (*=required) | Type | Description |
|---|---|---|
| *applicationName | String | The name of the application this filter is associated with. Must be one of the applications defined in the seed data. |
| *paramName | String | Name of parameter. This is appended to the REST call along with the value. |
| *filterName | String | Display name of the filter. |
| *filterType | String | Type of the Filter. Value options are 'MULTISLCT', 'TOGGLECTRL', 'NUMINPUT', 'CHECKBOX' & 'RADIOBTN'. |
| *active | Boolean | Determines whether this filter is active. |
| *urlConfig | Object | The URL configuration set for this filter. |
| options | Array | An array of filter options |
| translations | Array | An array of translations for the filter |
Translation objects provide localized strings for filters for a given application
| Property (*=required) | Type | Description |
|---|---|---|
| *applicationName | String | Name of the application this translation is associated with. Must be one of the applications defined in the seed data. |
| *paramName | String | Parameter name this translation is associated with. The paramName must be defined in the filters block. |
| *filterName | String | Filter name this translation is associated with. The filterName must be defined in the filters block. |
| options | Array | An array of translated options |
| *language | String | Language to which the translation needs to be applied. |
| *sourceLanguage | String | Original language of the base filter |
Filter options store selectable options for filters that rely on a preset list rather than pulling options from elsewhere
| Property (*=required) | Type | Description |
|---|---|---|
| *optionName | String | Name of the option to display in the UI |
| *optionValue | String | Value of the option to use when sending data |
| *displayOrder | Number | Order to display the option in the UI |
| *language | String | Language to which the translation needs to be applied. Not required for options on the parent Filter object. |
| *sourceLanguage | String | Original language of the base option. Not required for options on the parent Filter object. |
