Business Central 2019 Wave 2 – How to extend the Business Charts with your own charts

Peter Zentner

390

Like ( 0 )

Report

We all have seen the business charts on the role centers that Microsoft added. It always would have been nice, if you would have been able to add your own charts. Unfortunately, there were no events available so that you had to basically rewrite the page part and replace the existing one. I requested the addition of events in that area and it seems that those requests were heard: This changed now with Business Central 2019 Wave 2 – we can add our own charts.

I am going to explain how to do this and also bring up some issues that should be changed, in my eyes.

What do we want to do?

We have the chart part shown below in the role center. We would like to add our own chart in there to enhance the experience for our users and provide additional KPIs.

Standard Chart in Business Central — Business Central – Business Charts

Implementation of our own charts

I have the full source code of the project below, so you can download it and customize it to add your own charts. The main process is that you need to create a new codeunit and subscribe to some events that allow you interacting with the chart part. Then you also need to provide the values for your chart.

To get started

Microsoft provides an event to add your own chart into the Chart Definition table, unfortunately, this event is only raised when the table is still empty. This only happens typically on initialization of a new company.

What is really needed here is that the entire “Chart Definition” table and the entire functionality around adding charts is refactored using the Discovery Event Pattern. Let’s hope that this will be done in the future. For now, you have to create your chart during the install or setup of your app – but this also means that the chart stays there, even if you remove your extension. When someone selects your chart after your extension is removed, the standard behavior kicks in and – based on the implementation in standard – the “Top Ten Customers” chart will be displayed.

Let’s create a new codeunit, I called it “Demo Chart Management”, since it will contain the full implementation for the Demo Chart. I then added a global procedure as follows (also am showing the needed global Label for this:

```
var
```
```
    ChartNameLbl: Label 'DEMO';
```
```
 
```
```
procedure InstallChart()
```
```
var
```

    ChartDefinition: Record "Chart Definition";

```
begin
```

    if not ChartDefinition.Get(Codeunit::"Demo Chart Management", ChartNameLbl) then begin

        ChartDefinition."Code Unit ID" := Codeunit::"Demo Chart Management";

        ChartDefinition."Chart Name" := ChartNameLbl;

        ChartDefinition.Enabled := true;

```
        ChartDefinition.Insert(true);
```
```
    end;
```
```
end;
```

I am calling this from outside of the codeunit, so it needed to be a global function. This function is called – in my demo code – from the Installation codeunit as shown here:

```
trigger OnInstallAppPerCompany()
```
```
var
```

    ChartMgt: Codeunit "Demo Chart Management";

```
begin
```
```
    ChartMgt.InstallChart();
```
```
end;
```

Now that we have the initial issue covered and get our chart into the list of chart definitions, you can actually now see it in the list of charts. However, when you select the chart, nothing happens – well, it shows another chart:

The events needed

Microsoft added events to codeunit Chart Management and we will need to subscribe to those and implement our own logic. There is also an event to subscribe to in the page Help and Chart Wrapper to subscribe to.

Codeunit Chart Management – OnBeforeChartDescription

This event will show the description of the chart when you click on “Chart Information”. The implementation looks as follows:

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Chart Management", 'OnBeforeChartDescription', '', true, true)]

local procedure ChartManagementOnChartDescriptionSubscriber(ChartDefinition: Record "Chart Definition"; var ChartDescription: Text; var IsHandled: Boolean)

```
begin
```

    case ChartDefinition."Code Unit ID" of

        Codeunit::"Demo Chart Management":

```
            begin
```

                ChartDescription := ChartDescriptionMsg;

                IsHandled := true;

```
            end;
```
```
    end;
```
```
end;
```

Codeunit Chart Management – OnAfterPopulateChartDefinitionTable

If the Chart Definition table is empty, this event will be raised when filling in the standard charts. The implementation should call the function from above InstallChart.

Codeunit Chart Management – OnBeforeSetPeriodLength

When the period length is changed in the chart part, this event is called. The implementation should look like this:

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Chart Management", 'OnBeforeSetPeriodLength', '', true, true)]

local procedure ChartManagementOnSetPeriodLengthSubscriber(ChartDefinition: Record "Chart Definition"; PeriodLength: Option; var IsHandled: Boolean)

```
var
```

    BusChartBuf: Record "Business Chart Buffer";

```
begin
```

    case ChartDefinition."Code Unit ID" of

        Codeunit::"Demo Chart Management":

```
            begin
```

                BusChartBuf."Period Length" := PeriodLength;

                SaveSettings(BusChartBuf);

                IsHandled := true;

```
            end;
```
```
    end;
```
```
end;
```

Codeunit Chart Management – OnBeforeUpdateChart

This is the main event – it is called when the chart should be updated with data. It is also important that you update the Last Used Chart table to save the current settings and allow the chart to be shown again when the user goes back to the role center. This is also something that should be done in base code, but unfortunately, it does not get executed, if “IsHandled” is set in the event. So, an alternative would be to leave IsHandled = false, but this doesn’t follow the Handled pattern, so I am rather considering that an incomplete implementation of base functionality and hope that it will be fixed.

I will go into some details of the UpdateChart function later.

[EventSubscriber(ObjectType::Codeunit, Codeunit::"Chart Management", 'OnBeforeUpdateChart', '', true, true)]

local procedure ChartManagementOnUpdateChartSubscriber(var ChartDefinition: Record "Chart Definition"; var BusinessChartBuffer: Record "Business Chart Buffer"; Period: Option; var IsHandled: Boolean)

```
begin
```

    case ChartDefinition."Code Unit ID" of

        Codeunit::"Demo Chart Management":

```
            begin
```

                UpdateChart(BusinessChartBuffer, 0);

                UpdateLastUsedChart(ChartDefinition);

                IsHandled := true;

```
            end;
```
```
    end;
```
```
end;
```

Codeunit Chart Management – OnBeforeUpdateNextPrevious

This event does not necessarily need to be subscribed to. It is called when a user clicks on “Next” or “Previous” period and you can perform any actions that are necessary to be done before that.

Codeunit Chart Management – OnBeforeUpdateStatusText

The status text is the heading above the chart that defines the name of the chart and the current period length.

Page Help and Chart Wrapper – OnBeforeInitializeSelectedChart

When a user selects a chart, this event is raised and you should subscribe to it to get the settings for your chart.

Functions called in event handlers

The UpdateLastUsedChart function is called to store the last used chart per user so that it can be displayed again when the user goes back to the role center.

local procedure UpdateLastUsedChart(ChartDefinition: Record "Chart Definition")

```
var
```

    LastUsedChart: Record "Last Used Chart";

```
begin
```
```
    with LastUsedChart do
```

        if Get(UserId()) then begin

            Validate("Code Unit ID", ChartDefinition."Code Unit ID");

            Validate("Chart Name", ChartDefinition."Chart Name");

```
            Modify();
```
```
        end else begin
```

            Validate(UID, UserId());

            Validate("Code Unit ID", ChartDefinition."Code Unit ID");

            Validate("Chart Name", ChartDefinition."Chart Name");

```
            Insert();
```
```
        end;
```
```
end;
```

Now we are getting to the main function: UpdateChart. The function will add the proper columns and measurements and values to the chart and then make sure that they are displayed. You might have to adjust this based on the chart type that you are displaying.

It is also important that you should try to use a Query to calculate your values for the chart and do one read to the server instead of manually calculating the values and then performing multiple server roundtrips to get the information. This just improves the performance of the chart and it is important to not slow down the display of the role center.

You can see some documentation in the code. Some of the functions that are called are local functions and can be found in the source code at the bottom.

local procedure UpdateChart(var BusChartBuf: Record "Business Chart Buffer"; Period: Option " ",Next,Previous)

```
var
```

    BusChartMapColumn: Record "Business Chart Map";

```
    PeriodLength: Text[1];
```
```
    NoOfPeriods: Integer;
```
```
    PeriodCounter: Integer;
```
```
    FromDate: Date;
```
```
    ToDate: Date;
```
```
    i: Integer;
```
```
begin
```

    // any settings stored for this chart - we are only storing the periods that are used.

    GetSettings(BusChartBuf."Period Length");

```
 
```
```
     with BusChartBuf do begin
```

        if Period = Period::" " then begin

            FromDate := 0D;

```
            ToDate := 0D;
```
```
        end else
```

            if FindMidColumn(BusChartMapColumn) then

                GetPeriodFromMapColumn(BusChartMapColumn.Index, FromDate, ToDate);

```
 
```

        // now we are initializing the chart and defining the X axis for it - here it is a period of time

```
        Initialize();
```
```
        SetPeriodXAxis();
```

        InitParameters(BusChartBuf, PeriodLength, NoOfPeriods);

        CalcAndInsertPeriodAxis(BusChartBuf, Period, NoOfPeriods, FromDate, ToDate);

```
 
```

        // since we are using a stacked column, we are adding 5 measures for each period. Those are just demo values

        for i := 1 to 5 do

            AddMeasure(StrSubstNo(MeasureNameTxt, Format(i)), '', "Data Type"::Decimal, "Chart Type"::StackedColumn);

```
 
```

        // we are now defining the Y axis values for each of the measures for each of the periods. Since it's just a demo,

        // we are randmizing some values.

        FindFirstColumn(BusChartMapColumn);

        for PeriodCounter := 1 to NoOfPeriods do

            for i := 1 to 5 do begin

                GetPeriodFromMapColumn(PeriodCounter - 1, FromDate, ToDate);

                Randomize(CurrentDateTime() - CreateDateTime(Today(), 0T));

                SetValue(StrSubstNo(MeasureNameTxt, Format(i)), PeriodCounter - 1, Random(10000) / 100);

```
            end;
```
```
    end;
```
```
end;
```

We are done

The full chart looks like this:

You can find the source code here for download.

I hope this helps a bit to make your life easier and not have to spend the same amount of time that I took to figure this out.

If you have any questions, feel free to hit me up in the comments.

Comments

*This post is locked for comments