A Appendix: Report Data Requirements
Retail Home can be configured to pull data for reports and custom reports from REST services or from a BI Analysis. This appendix describes the data structures required for the returned payloads.
Common Request Values
Username Headers
External calls from Retail Home Server to remote data services are routed through WTSS and IDCS, which append additional headers to the request object. The following headers can be used to fetch the username at the destination endpoint.
Property | Type | Description |
---|---|---|
idcs_remote_user |
String |
User name set in IDCS |
remote_user |
String |
User name set in IDCS |
Common Response Values
This section describes the valid values for certain properties that are commonly used in the response payloads described in the following sections.
The following table describes the supported values for the Value Format (valueFormat) property:
Table A-1 Value Format
Format Value | Meaning | Example |
---|---|---|
PC |
Percent |
Formats 0.045 as 4.5% |
S |
Short Number |
Formats 9950000 as 9.95M |
N |
Number |
Formats 1234567.89 as 1,234,567.89 |
(empty) |
No Formatting |
0.045 displays as 0.045 |
The following table describes the supported values for the Indicator property:
Table A-2 Indicator
Indicator Value | Meaning |
---|---|
up |
An upward pointing arrow |
down |
A downward pointing arrow |
normal |
A normal severity indicator. |
info |
An info severity indicator |
important |
An important severity indicator |
critical |
A critical severity indicator |
REST Service Response Payloads
All REST services should return data in a JSON format. The following sections describe the JSON structure of various objects included in a response payload and the specific response payload required for each report type.
JSON Response Objects
This section defines various response objects that will be referenced in the following section when describing required response payloads for each report.
Metric Item
Property | Type | Required | Description |
---|---|---|---|
name |
String |
Y |
Name of the metric. |
value |
Number |
Y |
Value of the metric. |
valueFormat |
String |
N |
Format for the value. The following formats are supported:
|
valueLabel |
String |
N |
An additional label to display below the value |
indicator |
String |
N |
An indicator to display next to the value. The supported options are "up", "down", "normal", "info", "important", and "critical". |
Metric Chart
Property | Type | Required | Description |
---|---|---|---|
type |
String |
Y |
Type of chart to display: "line", "bar", "area", or "total" |
title |
String |
N |
Title to display above chart |
items |
Array |
Y |
Data for the chart. Each object contains "value" and "name" fields. An optional “series” field can be included to support multiple series. |
renderTooltips |
Boolean |
N |
Hide or show tooltips on the chart. Default true. |
seriesName |
String |
N |
The name of the series the item belongs to. It is displayed as a tooltip label for the series. Applies to line, bar, and area charts. (Can be used when there is a single series.) |
valueFormat |
String |
N |
Formats the output of values in the chart. Takes the same values as for metrics items. |
valueLabel |
String |
N |
Prefix for values. Applies to total charts only. |
valueUnits |
String |
N |
Suffix for values. Applies to total charts only. |
xAxisTitle |
String |
N |
Label for the X-axis. Applies to line, bar, and area charts. |
renderXAxisLabels |
Boolean |
N |
Show or hide tick labels on the X-axis. Applies to line, bar, and area charts. |
yAxisTitle |
String |
N |
Label for the Y-axis. Applies to line, bar, and area charts. |
renderYAxisLabels |
Boolean |
N |
Show or hide tick labels on the Y-axis. Applies to line, bar, and area charts. |
initialScrollPosition |
String |
N |
Which end of the chart to start at if there are too many items to show at once. Options are "first" and "last", defaults to "first". Applies to line, bar, and area charts. |
renderLegend |
Boolean |
N |
Show or hide legend or label at the bottom of the chart. Applies to line, bar and area charts. |
y2AxisTitle |
String |
N |
Label for the Y2-axis (right side of the chart). Applies to line, bar and area charts. |
y2SeriesId |
String |
N |
Value of the series corresponding to the Y2 Axis Title that needs to be shown in the chart. Applies to line, bar and area charts. |
Table Metric Config
Property | Type | Required | Description |
---|---|---|---|
name |
String |
Y |
Name of the metric. |
threshold |
Object |
N |
Object with numeric properties "min" and "max" values (both optional). Metric values less than the "min" value will be displayed in Red. Metric values greater than the "max" value will be displayed in Green. |
valueFormat |
String |
N |
Format for the value. The following formats are supported:
|
Table Headers Config
Property | Type | Required | Description |
---|---|---|---|
image |
String |
N |
Column header label for image column. (Required for table reports that display an image) |
descriptors |
Array |
N |
Array containing one or two String values defining the column header labels for the descriptor column(s). |
metrics |
Array |
N |
Array containing one to three Table Metric Config objects used to configure column header labels, value formatting and value thresholds for each Metric column. |
Table Item
Property | Type | Required | Description |
---|---|---|---|
image |
String |
N |
URL of the image to display. Ignored if the table report does not display an image. |
descriptors |
Array |
Y |
Array containing one or two String values defining descriptor values to display for this item. (Should match the number of descriptors defined in the Table Headers Config) |
metrics |
Array |
Y |
Array containing one to three Numeric values for this item. (Should match the number of metrics defined in the Table Headers Config) |
JSON Report Payloads
This section describes the required response payload for each report and will reference JSON Response Objects above for details.
Metric Only Reports
This category includes the following reports:
-
Two Metric Summary
-
Eight Metric Summary
-
Twelve Metric Summary
And the following report templates:
-
Two Metric Summary
-
Twelve Metric Summary
-
Eight Metric Summary
-
RPAS Two Metric Summary
-
RPAS Twelve Metric Summary
The REST service should return a JSON object with the following properties:
Property | Type | Required | Description |
---|---|---|---|
items |
Array |
Y |
An array of Metric Item objects to display on the tile. Up to twelve metric items may be returned; some reports will display fewer. |
Example response payload for Two Metric Summary:
{ "items": [{ "name": "Metric 1", "value": 10000, "valueFormat": "S" }, { "name": "Metric 2", "value": 0.5, "valueFormat": "PC" }] }
Metric Chart Reports
This category includes the following reports:
-
Four Metric Summary
-
Five Metric Summary
-
Six Metric Summary
And the following report templates:
-
Four Metric Summary
-
Five Metric Summary
-
Six Metric Summary
-
RPAS Four Metric Summary
-
RPAS Six Metric Summary
The REST service should return a JSON object with the following properties:
Property | Type | Required | Description |
---|---|---|---|
items |
Array |
Y |
An array of Metric Item objects to display on the tile. Up to six metric items may be returned; some reports will display fewer. |
chart |
Object |
N |
A Metric Chart object defining a chart to be displayed below the metrics. |
Example response payload for Four Metric Summary:
{ "items": [{ "name": "Metric 1", "value": 10000, "valueFormat": "S" }, { "name": "Example", "value": 0.5, "valueFormat": "PC" }], "chart": { "type": "bar", "items": [{ "name": "JAN", "series": "2021", "value": 4300000 }, { "name": "FEB", "series": "2021", "value": 2230000 }, { "name": "JAN", "series": "2022", "value": 3500000 }, { "name": "FEB", "series": "2022", "value": 4500000 } ], "renderTooltips": true, "valueFormat": "S", "renderXAxisLabels": true, "renderYAxisLabels": true } }
Example response payload for Five Metric Summary:
{
"items": [
{
"name": "Metric 1",
"value": 1
},
{
"name": "Metric 2",
"value": 2
},
{
"name": "Metric 3",
"value": 3
},
{
"name": "Metric 4",
"value": 4
},
{
"name": "Metric 5",
"value": 5
}
],
"chart": {
"type": "bar",
"title": "Title",
"items": [
{
"id": 0,
"series": "Series-1",
"name": "Series 1 Name",
"value": 10
},
{
"id": 1,
"series": "Series-1",
"name": "Series 1 Name",
"value": 11
},
{
"id": 0,
"series": "Y2-Series ID",
"name": "Y2-Series-Name",
"value": 20
},
{
"id": 1,
"series": "Y2-Series ID",
"name": " Y2-Series-Name",
"value": 21
},
{
"id": 0,
"series": "Series-3",
"name": "Series 3 Name",
"value": 30
},
{
"id": 1,
"series": "Series-3",
"name": "Series 3 Name",
"value": 31
}
],
"renderTooltips": "true",
"valueFormat": "S",
"xAxisTitle": "X-Axis Title",
"renderXAxisLabels": "true",
"yAxisTitle": "Y-Axis Title",
"renderYAxisLabels": "true",
"initialScrollPosition": "first",
"y2AxisTitle": "Y2-Axis Title",
"y2SeriesId": "Y2-Series ID",
"renderLegend": true
}
}
Table Reports
This category includes the following reports:
-
Image Metric Table
-
Image Table
-
Metrics Table
And the following report templates:
-
Image Metrics Table
-
Image Table
-
Metrics Table
-
RPAS Image Metrics Table
-
RPAS Image Table
-
RPAS Metrics Table
The REST service should return a JSON object with the following properties:
Property | Type | Required | Description |
---|---|---|---|
name |
String |
Y |
The report name. |
headers |
Object |
Y |
A Table Headers Config object defining the structure of the report. |
items |
Array |
Y |
An array of Table Item objects representing the data to populate the report. |
Example response payload for Two Metric Summary:
{ "name": "Top Selling by Margin", "headers": { "image": "Image", "descriptors": ["Name", "ID"], "metrics": [{ "name": "Sales", "threshold": { "max": 700000000, "min": 10000000 }, "valueFormat": "S" }] }, "items": [ { "image": "http://my.image.url", "descriptors": ["Color Block Sundress", "10001003"], "metrics": ["854300234"] }, { "image": "", "descriptors": ["Color Item FULL ROW", "10001323"], "metrics": ["1235436234"] }, { "image": "", "descriptors": ["eqwtge", "10001323"], "metrics": ["1235436234"] } ] }
ORASE Reports
This category includes the following reports:
-
Demand Transference
-
Orase Offer Optimization
The REST service should return a JSON object with the following properties:
Property | Type | Required | Description |
---|---|---|---|
items |
Array |
Y |
An array of Metric Item objects to display on the tile. Up to twelve metric items may be returned; some reports will display fewer. |
Example response payload for Demand Transference:
{
"items": [
{
"name": "Version",
"value": "CS_DT"
},
{
"name": "Stage",
"value": "Calculation"
},
{
"name": "Status",
"value": "Completed"
},
{
"name": "Status Color",
"value": "Green"
},
{
"name": "Heading",
"value": "Transferable Demand"
},
{
"name": "Min",
"value": "0.1",
"valueFormat": "PC"
},
{
"name": "Avg",
"value": "0.7",
"valueFormat": "PC"
},
{
"name": "Max",
"value": "1",
"valueFormat": "PC"
}
]
}
Example response payload for ORASE Offer Optimization:
{
"items": [
{
"name": "Revenue",
"value": 11902000,
"valueFormat": "S"
},
{
"name": "vs2022",
"value": 0.1665,
"valueFormat": "PC",
"indicator": "up"
},
{
"name": "Sell Through",
"value": 0.8953,
"valueFormat": "PC"
},
{
"name": "vs2022",
"value": 0.0363,
"valueFormat": "PC",
"indicator": "up"
},
{
"name": "Gross Margin",
"value": 45960000,
"valueFormat": "S"
},
{
"name": "vs2022",
"value": -0.0621,
"valueFormat": "PC",
"indicator": "down"
}
]
}
BI Analysis Payloads
The following sections describe the row structure of various objects included in a BI response payload and the specific BI response payload(s) required for each report type.
BI Response Layout
This section defines various response layouts that will be referenced in the following section when describing required response analyses for each report.
Note:
If a column below hasN
in the Required column, this means the value can be empty, but the column still
needs to be present in the response.
BI Simple Metric
Column | Property | Type | Required | Description |
---|---|---|---|---|
0 |
Metric Name |
String |
Y |
Name of the metric. |
1 |
Metric Value |
Number |
Y |
Value of the metric. |
2 |
Value Format |
String |
N |
Format for the value. The following formats are supported:
|
3 |
Value Label |
String |
N |
An additional label to display below the value. |
BI Metric
Column | Property | Type | Required | Description |
---|---|---|---|---|
0 |
Metric Name |
String |
Y |
Name of the metric. |
1 |
Metric Value |
Number |
Y |
Value of the metric. |
2 |
Value Format |
String |
N |
Format for the value. The following formats are supported:
|
3 |
Value Label |
String |
N |
An additional label to display below the value |
4 |
Indicator |
String |
N |
An indicator to display next to the value. The supported options are "up", "down", "normal", "info", "important", and "critical". |
BI Metric Chart Config
Column | Property | Type | Required | Description |
---|---|---|---|---|
0 |
Chart Type |
String |
Y |
Type of chart to display: "line", "bar", "area", or "total" |
1 |
Chart Title |
String |
N |
Title to display above chart |
2 |
Render Tooltips |
Boolean |
N |
Hide or show tooltips on the chart. Default true. |
3 |
Series Name |
String |
N |
Label displayed in tooltip. Applies to line, bar, and area charts. |
4 |
Value Format |
String |
N |
Formats the output of values in the chart. Takes the same values as for metrics items. |
5 |
Value Label |
String |
N |
Prefix for values. Applies to total charts only. |
6 |
Value Units |
String |
N |
Suffix for values. Applies to total charts only. |
7 |
X-Axis Title |
String |
N |
Label for the X-axis. Applies to line, bar, and area charts. |
8 |
Render X-Axis Labels |
Boolean |
N |
Show or hide tick labels on the X-axis. Applies to line, bar, and area charts. |
9 |
Y-Axis Title |
String |
N |
Label for the Y-axis. Applies to line, bar, and area charts. |
10 |
Render Y-Axis Labels |
Boolean |
N |
Show or hide tick labels on the Y-axis. Applies to line, bar, and area charts. |
11 |
Initial Scrolling Position |
String |
N |
Which end of the chart to start at if there are too many items to show at once. Options are "first" and "last", defaults to "first". Applies to line, bar, and area charts. |
12 |
Render Legend |
Boolean |
N |
Show or hide legend or label at the bottom of the chart. Applies to line, bar and area charts. |
13 |
Y2 – Axis Title |
String |
N |
Label for the Y2-axis (right side of the chart). Applies to line, bar and area charts. |
14 |
Y2 – Series ID |
String |
N |
Value of the series corresponding to the Y2 Axis Title that needs to be shown in the chart. Applies to line, bar and area charts. |
BI Metric Chart Item
Each BI Metric Chart Item represents a value displayed in a chart (bar, line, area, total).
Column | Property | Type | Required | Description |
---|---|---|---|---|
0 |
Item Value |
Number |
Y |
Value of the item. |
1 |
Item Name |
String |
Y |
Name of the item. |
2 |
Item Series |
String |
Y |
Series Name of the item. |
BI Table Config
Column | Property | Type | Required | Description |
---|---|---|---|---|
0 |
Report Name |
String |
Y |
Name of the report. |
1 |
Image Column Header Label |
String |
N |
Column header label for images. |
2 |
Descriptor 1 Name |
String |
Y |
Column header label for first descriptor. |
3 |
Descriptor 2 Name |
String |
N |
Column header label for second descriptor. |
4 |
Metric 1 Name |
String |
Y |
Column header label for first metric. |
5 |
Metric 1 Value Format Code |
String |
Y |
Value format code for first metric. |
6 |
Metric 1 Max Threshold |
Number |
N |
Metric 1 values greater than the Metric 1 Max Threshold value will be displayed in Green. |
7 |
Metric 1 Min Threshold |
Number |
N |
Metric 1 values less than the Metric 1 Min Threshold value will be displayed in Red. |
8 |
Metric 2 Name |
String |
Y |
Column header label for second metric. |
9 |
Metric 2 Value Format Code |
String |
Y |
Value format code for second metric. |
10 |
Metric 2 Max Threshold |
Number |
N |
Metric 2 values greater than the Metric 2 Max Threshold value will be displayed in Green. |
11 |
Metric 2 Min Threshold |
Number |
N |
Metric 2 values less than the Metric 2 Min Threshold value will be displayed in Red. |
12 |
Metric 3 Name |
String |
Y |
Column header label for third metric. |
13 |
Metric 3 Value Format Code |
String |
Y |
Value format code for third metric. |
14 |
Metric 3 Max Threshold |
Number |
N |
Metric 3 values greater than the Metric 3 Max Threshold value will be displayed in Green. |
15 |
Metric 3 Min Threshold |
Number |
N |
Metric 3 values less than the Metric 3 Min Threshold value will be displayed in Red. |
BI Table Item
Column | Property | Type | Required | Description |
---|---|---|---|---|
0 |
Image URL |
String |
N |
URL of image to display |
1 |
Descriptor 1 Value |
String |
Y |
Value for first descriptor. |
2 |
Descriptor 2 Value |
String |
N |
Value for second descriptor. |
3 |
Metric 1 Value |
Number |
Y |
Value for first metric. |
4 |
Metric 2 Value |
Number |
N |
Value for second metric. |
5 |
Metric 3 Value |
Number |
N |
Value for third metric. |
BI Report Analyses
This section describes the required analyses for each report and will reference the BI Response Layout above for details.
BI Two Metric Report
This category includes the following report template:
-
BI Two Metric Summary
Table A-3 Required Analysis
Template Parameter | Response Layout | Repeat within row | Rows | Columns |
---|---|---|---|---|
BI Analysis Catalog Location |
BI Simple Metric |
up to 2 |
1 |
4 to 8 |
BI Twelve Metric Report
This category includes the following report template:
-
BI Two Metric Summary
Table A-4 Required Analysis
Template Parameter | Response Layout | Repeat within row | Rows | Columns |
---|---|---|---|---|
BI Analysis Catalog Location |
BI Metric |
Up to 12 |
1 |
5 to 6 |
BI Metric Chart Reports
This category includes the following report templates:
-
BI Four Metric with Chart Template
-
BI Six Metric with Chart Template
Table A-5 Required Analyses
Template Parameter | Response Layout | Repeat within row | Rows | Columns |
---|---|---|---|---|
BI Metrics Analysis Catalog Location |
BI Metric |
up to 4/6 |
1 |
5 to 20/30 |
BI Chart Configuration Analysis Catalog Location |
BI Metric Chart Config |
No |
1 |
13 |
BI Chart Items Analysis Catalog Location |
BI Metric Chart Item |
No |
Many |
2 |
BI Table Reports
This category includes the following report templates:
-
BI Metrics Table Template
-
BI Image Table Template
-
BI Image Metrics Template
Table A-6 Required Analyses
Template Parameter | Response Layout | Repeat within row | Rows | Columns |
---|---|---|---|---|
BI Table Headers Analysis Catalog Location |
BI Table Config |
No |
1 |
up to 16 |
BI Table Items Analysis Catalog Location |
BI Table Item |
No |
Many |
up to 6 |
Note:
All the report templates listed above require the same analyses using the same column layout, but some columns are not used in some reports. The BI Metrics Table Template will ignore the image related columns. The BI Image Table Template will ignore the values and configuration for the second and third metrics. If ignored columns are at the end of the row (such as metrics) they can be left out of the response.