Appendix: Report Data Requirements

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: PC - Percent (.01 = 1%) S - Short (1000 = 1K) N - Number (1000 = 1,000)
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.

Table Metric Config

Property

Type

Required

Description

name

String

Name of the metric.

threshold

Object

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

Format for the value. The following formats are supported:

PC - Percent (.01 = 1%)
S - Short (1000 = 1K)
N - Number (1000 = 1,000)

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
Twelve Metric Summary

And the following report templates:

Two Metric Summary
Twelve 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
Six Metric Summary

And the following report templates:

Four 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
  }
}

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"]
    }
  ]
}

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 has N 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: PC - Percent (.01 = 1%) S - Short (1000 = 1K) N - Number (1000 = 1,000)
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: PC - Percent (.01 = 1%) S - Short (1000 = 1K) N - Number (1000 = 1,000)
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.

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.