D3JS API definition

[metas-mk]

After created proof of concept of D3JS Integration into metasfresh WebUI, we can now start to define the API, needed for different chart elements. Please provide a concept suggestion. Samples of charts we could begin with
Bar Chart: http://bl.ocks.org/mbostock/3885705
Pie Chart: http://bl.ocks.org/dbuezas/9306799
Area Chart: http://bl.ocks.org/mbostock/3883195

Link to D3JS POC Task:
metasfresh/metasfresh-webui-api-legacy#64

[cadavre]

Do you need anything from us before you provide API for data?

[teosarca]

Yup :)
Basically we need a proposal about what endpoints will be needed and which is the JSON format we shall use in exchange.

Just a simple prototype would be enough for that start. We would be able to evolve it but for now we need to understand what's required.

[Dunkat]

For this three simple charts, we will need data (like label and value eg. label: "Anne", value: 8), and type of chart. I provide example of data:

{
"data": [
{name: "Alice", value: 2},
{name: "Bob", value: 3},
{name: "Carol", value: 1},
{name: "Dwayne", value: 5},
{name: "Anne", value: 8},
{name: "Robin", value: 28},
{name: "Eve", value: 12},
{name: "Karen", value: 6},
{name: "Lisa", value: 22},
{name: "Tom", value: 18}
],
"type": "barChart"
}

where name is a label of particular bar and value should be a number.

For start this should be enough, in the future we will try unify the data for more advanced charts, but let's start from this format of JSON.

[Dunkat]

Hey, let's a bit modify json to have more dynamic charts. I provide example below:

{
"layout": [
{type: "string", caption: "axis x"},
{type: "number", caption: "axis y"}
],
"data": [
[
  {value: "label1"},
  {value: "31"},
],[
  {value: "label2"},
  {value: "51"},
],[
  {value: "label3"},
  {value: "131"},
],[
  {value: "label4"},
  {value: "138"},
... more domains
],
... more data
],
"chartType": "barChart",
}

in layout you can define type of data, and describe axes

[teosarca]

Hi @Dunkat ,

I think we shall separate the metadata from actual data because the scenario, from frontend side, would be something like:

• fetch the metadata (once!)
• fetch the actual data (polling on a given rate)

wdyt?

[Dunkat]

You are right. It would be good to separate the metadata from actual data

[teosarca]

Hi @Dunkat ,

( Backend task: metasfresh/metasfresh-webui-api-legacy#184 )

NOTE: this is an working prototype which we can change it as we want ;)
Feel free to come with any suggestions.

The layout is provided by dashboard endpoints:

• KPIs: http://w101.metasfresh.com:8081/swagger-ui.html#!/dashboard-rest-controller/getKPIsDashboardUsingGET
• Target indicators: http://w101.metasfresh.com:8081/swagger-ui.html#!/dashboard-rest-controller/getTargetIndicatorsDashboardUsingGET

After you have the layouts, using the dashboard item's ID you can query for data:

• KPIs: http://w101.metasfresh.com:8081/swagger-ui.html#!/dashboard-rest-controller/getKPIDataUsingGET
• Target indicators: http://w101.metasfresh.com:8081/swagger-ui.html#!/dashboard-rest-controller/getTargetIndicatorDataUsingGET

---

Example:

1. Get dashboard KPIs: http://w101.metasfresh.com:8081/rest/api/dashboard/kpis
   You might get:

{
  "items": [
    {
      "id": 1000013,
      "caption": "Order lines / day",
      "seqNo": 10,
      "kpi": {
        "caption": "Order lines / day",
        "description": "",
        "chartType": "BarChart",
        "fields": [
          {
            "caption": "DateOrdered",
            "description": "",
            "type": "Date",
            "timeField": true
          },
          {
            "caption": "Count",
            "description": "",
            "type": "Number",
            "timeField": false
          }
        ]
      }
    }
  ]
}

So basically,

• your itemId is 1000013
• the KPI has 2 fields:
  ** DateOrdered, which is a date and it's also marked as the "timeField"
  ** Count, which is number

Now let's fetch the data for that KPI: http://w101.metasfresh.com:8081/rest/api/dashboard/kpis/1000013/data

You might get:

{
  "itemId": 1000013,
  "data": [
    {
      "key": "2016-09-08T00:00:00.000+02:00",
      "values": [
        "2016-09-08T00:00:00.000+02:00",
        3
      ]
    },
    {
      "key": "2016-10-25T00:00:00.000+02:00",
      "values": [
        "2016-10-25T00:00:00.000+02:00",
        1
      ]
    },
   .......
}

Remark the "data" node. There you will find the data items.
Each of data item has following properties:

• key - item's unique key (not sure if u will needed for start)
• values - an array of field values. The values are in SAME ORDER as they KPI's fields are.

wdyt?

[metas-mk]

This is a very a nice/ compact chart:
https://bl.ocks.org/mbostock/4061961

Is a very nice fit for target indicator sized KPI. Has everything we need for that
a) target
b) quantitive range
compared to
c) qualitative ranges

[metas-mk]

Another one that could be used as best/ worst performing comparison chart:
https://bl.ocks.org/mbostock/2368837

[bambeusz]

We need to think about the scale on bar charts. Will the API provide absolute scale, or we'll point min and max values dynamically from the dataset?

Another thing is data model. Current one is not really easy to get, and needs processing on frontend side. What I'm thinking of is every chart will display array of values.

In pie chart there's only one set of such values, and angle represents part of whole sum.
In bar chart we can have multiple datasets. And the height of bar represents value relative to applied scale.

my suggestion of model:
layout:

{
  "name": "Chart name",
  "id": 3123154123,
  "description": "if needed",
  "type": "bar"
}

data:

{
  "colors": ["#fafafa", "#132412", "#ff0000", "#00ff00", "#689721", "#302010"],
  "labels": [ "baby", "child", "tenager", "adult", "old", "super old" ],
  "datasets": [
    {
      "name": "age",
      "unit": "years",
      "values": [ 2, 6, 16, 20, 50, 88 ],
      "max": 100,
      "min": 0,
      "step": 2
    },
    {
      "name": "cash",
      "unit": "$",
      "values": [ 0, 0, 50, 1000, 600, 200 ],
      "max": "auto",
      "min": "auto",
      "step": 50
    },
    {
      "name": "time",
      "unit": "%",
      "values": [90, 90, 60, 10, 10, 90],
      "max": 100,
      "min": 0,
      "step": 10
    }
  ]
}

Such model should easily be rendered in both, pie and bar charts without too much data processing.

imho, if the chart is pie type, we should actually render 3 pie charts.

note: this model assumes, that the amount of values are equal to labels, and colors as it assigns corresponding label and color to value.

wdyt?

[teosarca]

Hi @chmieludaniel , thanks for taking care.

I have following observations...
I think the "colors" and "labels" shall go to "layout" because for the start, the frontend will poll for new data at a given rate.

imho, if the chart is pie type, we should actually render 3 pie charts.
Nop, imho the frontend shall always put everything in one chart.
If we want 2 or 3 charts, we shall create 3 KPIs.
In this case, the pie chart shall be rendered with 3 split slices... but that's for the future.

Question: can u give me an example about how the responses shall look like in case we have a time dependent chart.
Case: Revenue per Week. In this case we want the Revenue to be on Y-axis and the Week shall be on X-axis.
Do we also need to provide some scale like "the Week label is time in weeks" ?

Example of pie chart with split slices.

[bambeusz]

Hi @teosarca,

True - the labels, and colors can be a part of layout. In that case, the data, can be just an array (value of previous datasets).

I'm not sure if I got the point. What's new when the chart is time dependent? I think the labels would be something like:
"labels": ["week 14", "week 15", ...]
or:
"labels": ["16 Jan 2017 - 22 Jan 2017", "23 Jan 2017 - 29 Jan 2017", ...]

Frontend would not take care of date format, just display the text/date labels in given format

When it comes to pie chart in slices, then we would need to limit slices to radius/sliceWidth. Eg If the slice width is 20px and pie width is 400px (radius is 200), then we can only show 10 slices, and the last ones can be quite unreadable.

But it's not for now, is it? Until then, can we assume, for the pie chart to always have only one dataset in data array?

[bambeusz]

as @metas-mk commented on skype, the scale will be the same for each dataset. Saying scale I mean minimum and maximum value for y axis. But what about minimum step on y axis. Like here:

The step is equal to 20. Do you want to specify this value from API, or we sould calculate it dynamically?

[metas-mk]

quick examples for 6 KPI charts on dashboard:
pie - 1 dataset w/ revenue per Product Category in this week
pie - 1 dataset w/ revenue per Product Category in last week
bar - top 5 product revenue in this week compared w/ their revenues last week
bar - top 5 Product Category revenue in this week compared w/ their revenues last week
pie - 1 dataset w/ revenue per day in this week
pie - 1 dataset w/ revenue per day in last week

the 4 target KPI will be all metric things in the first step

[metas-mk]

Tested. Works very nicely and just in time for Chemnitzer Linux Days. Was an awesome experience for the visitors.