Dashboards

Owned by Maroš Grman
Last updated: Oct 27, 2023 by Pricefx Learning Hub

This article describes how to create a simple Dashboard with filters and charts. It’s an introduction to the Dashboards configuration, not a deep-dive.

This handbook expects, that you can already use Dashboards as an end user and you can create PA charts.

Business Use Case

Let’s start with a couple of business use cases to have a better understanding of the business problems that are solved:

Revenue and Margin Analysis

As a Pricing Analyst,I want to Analyze revenue and margin % achieved during a given period, with the possibility to change the time dimension for aggregation,so I can Understand the revenue and margin trends for the business and decide on corrective actions.

Contribution to Revenue analysis

As a Pricing Analyst,I want to See the Pareto analysis for Customers/Products contribution to revenue, split into 10 buckets showing the number of Customers/Products in each bucket and cumulative contribution to the total revenue,so I can Understand which product line contributes the most/least toward the revenue and derive corrective actions.

Concept

The presented user stories are usually leading to a solution with some kind of a Dashboard, where the user can review the data and make a decision.

What Is a Dashboard

Dashboard is a page, which consists of:

  • Filters for data - allowing users to modify the scope of the report.

  • Portlets (rectangular areas) - visualizing the data in the form of:

    • Charts (either built-in PA charts, or Highcharts).

    • Tabular data.

    • Action buttons and Text.

Figure 1. Dashboard with filters on the left and 4 portlets containing charts.

Flow of Work with a Dashboard

Figure 2. Flow of execution of the Dashboard when the Dynamic inputs are used

Implementation & Configuration

To create a new Dashboard, you will set up three things:

  • Dashboard Logic - which:

    • Creates definitions of the filter input fields.

    • Prepares definitions of the charts (design + data).

  • Dashboard configuration - Which defines some Dashboard’s properties.

  • Layout (Preferences) - How the portlets are positioned on the screen.

Dashboard Logic

Let’s describe in more detail what the Dashboard logic actually does:

  • When executed in Input Generation mode, it creates definitions of the Filter input fields:

    • Definitions of input fields.

    • Data for the values of inputs (e.g., values of dropdowns).

  • When executed in regular execution mode, it prepares:

    • Charts

      • Analytics charts - It builds the definition of the chart, including the query to Datamart, which will later prepare the data feeding the chart.

      • HighCharts - The logic does both: prepares definition of the chart and also queries the data and transforms them into correct shape for usage in the HighChart.

    • Tabular data (aka Result Matrix) - It queries and prepares data into the correct shape, and prepares meta-definition of the ResultMatrix (like formatting, interactive behavior, etc.).

    • Text and action buttons (see the Handbook about Dashboard Controller).

    • Embeds other Dashboard, to provide interactive behavior (see the Handbook about Embedded/Interactive Dashboards).

To create a new Dashboard logic, create a logic

  • of the type "Pricing Logic",

  • with the "Default" nature.

Recommended structure for the logic:

  1. Elements which build the filters - the input fields.

  2. Element "AbortOnSynaxCheck".

  3. Element which queries data and prepares the definition of chart/matrix #1.

  4. Element which queries data and prepares the definition of chart/matrix #2.

  5. Element which queries data and prepares the definition of chart/matrix #3.

Elements, whose results should be displayable as portlets, must have DisplayMode set to Everywhere and all other elements to Never.

For more details see the Dashboard Logic API.

Filters

Dashboard filters are technically input fields. Their definition is created in the same way like e.g., on Pricelist, Quote Line Item, or CFS. The filter inputs will show up to the user in the section "Data Filters" of the Dashboard page.

You can create all common filter input fields, e.g.:

  • Number input - api.userEntry()

  • Drop-down selection - api.option()

Besides simple input fields, you can also use those more advanced filter inputs, like:

  • Filter Builder for Datamart - A popup which lets the user build a filter for a given Datamart:

    • Either clickable generic filter,

    • Or a selection of specific dimensions only.

      def dimFilters = ["CustomerID": "CD-00155", "ProductID": "MB-0005"] def filter = api.datamartFilterBuilderUserEntry( "DMFilterInput", "Transaction", dimFilters, Filter.equal("Country", "Germany") )

  • Configurator - A popup (or an in-line set of inputs) with many filters whose values can depend on the selection made in other inputs.

Analytics Charts

PA Chart is one of the subclass of class AbstractChartBuilder. It consists of:

  • Definition

  • Datamart query

You can either build it manually (use one of the Studio code template "pfxchart_…​", for example "pfxchart_scatter"), or you can create a chart in the UI and grab the code.

The Studio template code is good if you need to find some special setting, which is not available, when you set up the chart in UI.

But for daily usage and also a much quicker way, is to create the chart in Analytics › Data Analyzer and grab its code generated by the system:

  1. Create a chart and Refresh, so you can see it (alternatively you can open a Saved Chart).

  2. Open the chart context menu via button …​ and use the option View Expression.

  3. Ahe popup with the Groovy code appears.

  4. Copy the definition of the chart and paste it to a Dashboard logic element.

  5. If you later need to add code for filtering, go back to the chart in the UI, set up the filter, click View Expression again, and copy the additional piece of code.

Highchart, Matrix

For Highcharts and Result Matrix, please see the specialized Handbooks "Highcharts" and "Result Matrix".

Dashboard Configuration

In order for the user to find your Dashboard in the list of Dashboards, you must define/configure the Dashboard. You create the definition on the page Administration › Dashboards

(or also Administration › Configuration › Dashboards › Dashboards Admin).

The definition contains:

  • Name of the Dashboard.

  • Category - For easier navigation, in case you have many Dashboards, it’s good to sort the Dashbaords into more categories.

  • Selection of the Logic to use to prepare the dashboard inputs and results - see below.

  • Checkbox for Dynamic Inputs - When enabled, the Dashboard logic will be executed, before the Dashboard should be displayed, in the Input Generation mode, to retrieve the list of input (filters) definitions. Unless you have some specific other needs, use this approach - i.e., tick the checkbox.

  • Hide - This is only for "embedded" dashboards, which are not used as standalone, but only as par of another dashboard, and so you do not want them to be listed.

  • Target Date - If you set this date, then each time the Dashboard logic is executed, the TargetDate in the context will be set to this value. In most common scenarios, this is not wanted, so keep it empty.

  • etc.

To select a Logic for this Dashboard:

  1. Select the Dashboard and click on Configure.

  2. A popup will appear, where you select the Logic to be used for this Dashboard.

    1. Once you select the Logic, the system will immediately execute the Logic in Input Generation mode, and will display the filter inputs created by your logic - marked by "yellow" color on our screenshot.

Layout

The initial order of the portlets is given by the order of Elements in the logic.

Nevertheless, when the Dashboard is displayed on the screen, you can use your mouse to move & resize the portlets.

To persist the Layout, save the Preferences. Because you do it for all users, save it as Global.

Testing

Dashboard logic can be tested :

  • In Studio - This is the quickiest way, but with limitations:

    • It supports all common inputs (even Configurators) but does not support some type of complex filters (e.g., Datamart filter).

    • It can render Matrix but not charts.

  • In Pricefx UI:

    • Supports all input types and chart outputs.

    • Before testing, you must:

      • Deploy the logic to partition.

      • Create Dashboard definition.

      • When changing the filter input definitions, you need to reload the browser.

Considerations

Possible important considerations which must be borne in mind.

Performance

Always measure the time, how long it takes to:

  • Build the filters (i.e., create the inputs) - especially when the content of the filter is build from Datamart or Data Source, they’re usually quite big.

  • Build the content of the Dashboard (i.e., when the dashboard refreshes).

The measurements must be done on a dataset with a size close to the customer’s dataset, otherwise the real-world usage could be slow.

If the dataset used by the Dashboard is quite big or if you perform quite a lot of computations, always measure the performance and do optimizations.

Security

You can set up who can access & see the Dashboard by setting the User Group of the Dashboard in its configuration.

  • Dashboard Controller that allows creating:

    • Action buttons (which can trigger some processes or open some pages).

    • Paragraph text (kind of an HTML page) on the Dashboard.

  • Embedded Dashboard - User’s interactive selection of some data in a matrix or chart can influence what other parts of the Dashboards will be showing (e.g., show detailed info about selected data).

References

Logic API

Groovy API

Documentation

Knowledge Base

Found an issue in documentation? Write to us.