Skip to main content

Charting and Dashboarding Developer Guide

Jenny Drummey
  • Updated

Charting and Dashboarding Overview

BackOffice Associates® Solutions allows users to create charts and dashboards to graphically display data. Individual charts of data are created by using the Chart page type. Dashboards are created using the Dashboard page type to create a collection of charts. For example, a dashboard can be configured to display tables as a bar chart and the package types used for downloads as a pie chart.

BackOffice Solutions is delivered with a series of charts and dashboards. This manual outlines the process to create custom charts and dashboards in the Platform.

Audience of Developer’s Manual

The audience of this manual is developers who are creating charts and dashboards. This manual assumes advanced knowledge of DSP® navigation and functionality.

Support

Custom development of charts and dashboards is permitted; however, it is not covered by standard Product Support. Refer to a technical lead for customization troubleshooting. If you believe there is a bug in the feature as implemented in the delivered product, report the bug to Product Support using the standard Support notification process.

Charting Basics

Custom charts are maintained during upgrades to a new version of BackOffice Solutions. Modifications made to delivered charts are not supported; any changes made to delivered charts will be lost once BackOffice Solutions is upgraded.

Chart Types

The following chart types are available:

Area

area_chart.png

Bar

Bar.png

Column

column.png

Doughnut

doughnut.png

Line

line.png

Pie

pie.png

Tabular

tabular.png

NOTE: A tabular chart is not a standard chart; it is similar to a dynamic page with limited functionality. It can be used as a stand-alone chart page within a layout.

Create a Chart

To create a chart, create a view in SQL then create a chart page in the DSP®.

Create a Chart View

A chart view contains the data to be displayed via the chart page and can reference multiple views and tables.

At least one column in the view must contain a Value field (for X-axis data) and a Category (for Y-axis data) field. There can be more than one Value column and 1-2 Category columns. If there are 2 Category columns, there can only be one Value column.

chart_view.png

In this example, EmployeeID is the Category, while Orders is the Value column.

Name the chart view using the naming convention web*Chart.

NOTE: web*Chart is the default naming convention and can be changed per WebApp (Admin > WebApps > Vertical View > Naming Conventions > Chart Filter) or globally for every WebApp on the site (Admin > Configuration > Parameters > Naming Conventions > Chart Filter). A chart filter set globally at the Parameters level takes precedence of the chart filter set at the WebApp level.

The Platform automatically creates two records on the Page Columns page:

  • Control = Value: must always be the first column listed in the chart view
  • Control = Category: must always be the second column in the chart view

Page_Column_Category_Value.png

NOTE: The records automatically created by the Platform are not a requirement. They can be modified and deleted if they do not infer the correct data.

An extra column can be included in the view, which must be manually added to the Page Columns page where the Control = Category. The Platform only supports two column properties where Control = Category. Mark each category control as Primary and Secondary via the Grouping Category field on the Vertical View. Refer to Configure_Column_Properties for more information on Primary and Secondary Categories.

Create a Chart Page

To create a chart page:

  1. Create a page for a WebApp where:
    1. DESCRIPTION = Name of chart which displays as the chart title
    2. PAGE TYPE = Chart
    3. TABLE = Blank
    4. Report View = View created in Create a Chart View
    5. Horizontal Menu ID = Menu where chart page is accessed
    6. Chart Type = Type of chart: Area, Bar, Column, Doughnut, Line Pie and Tabular. Refer to Chart Types for an illustration of each type.
  2. Configure column properties.
  3. Configure chart properties. Options available depend on the chart type.
  4. Return to the WebApp and refresh to view the chart. Modify the chart properties as needed.

Configure Column Properties

Category and Value column properties are required for the chart to render. By default, two columns from the web*Chart view are selected as a Category and a Value column; review these column properties for accuracy.

Page_Column_Category_Value.png

For Tabular chart type, the user has the ability to add a Text Box control to any column as a means to support page links. No other controls are supported.

Category Column Property

The Category column property allows the user to define which column in the web*Chart view corresponds to the X-axis. This column property can be for most data types; the exception is binary data types. As with list boxes, a non-string key column can be used as the underlying value and a display value can replace what is shown.

There are two types of categories: Primary and Secondary. Each combination of Primary and Secondary Category values must be unique to ensure a proper rendering of the dataset.

A Primary Category column corresponds to the field whose data is rendered on the X-axis. If there is only one Category column defined (by definition, it must be Primary), each value row’s primary column field is rendered on the X-axis. There must be one Primary Category column per non-tabular chart.

A Secondary Category, which is optional, allows for the definition of an implicit number of virtual “Value” columns for a dataset (refer to Value Column Property for more information). If a Secondary column is configured, there must be exactly one Value column. Secondary Category columns allow for multiple data points to be rendered per Primary Category value. For example, if the user can configure n number of statuses and wants to create a chart to visualize an Object/Status Count, they could define a view that returns data as outlined in the following table:

Object

Status

Count

A

Status1

1

A

Status2

2

B

Status1

3

B

Status2

4

NOTE: All combinations of Object and Status are unique.

The configuration outlined in the above table ensures that as new Statuses are added, they are automatically taken into account when the chart renders by treating them as a Value column. When this chart is rendered, the X-axis will have two tick marks: A and B. Within those tick marks will be two series: Status1 and Status2. If this was a Bar chart, there would be two bars for A and two bars for B. If a Status is not included, it is assumed to be NULL. If a user wants non-existence to equate to zero, this must be written into the view logic.

NOTE:  The DSP® does not support Secondary Columns with multiple Value columns.

Value Column Property

Value column properties are used to specify which field within the web*Chart view corresponds to a Y-axis value. This column is expected to be a numeric type because charts can only display numeric ranges. Multiple Value columns are supported when there is only one Category column defined. When the graph renders, there will be n number of series. For example, if a web*Chart view renders [“1/1/1990”, 1, 2, 3], the first column would be defined as the Category column and the last three columns would be defined as Value columns. Value columns are recommended over a Secondary column when the amount of supplemental data is static. See the following section for more information.

When to use Value Columns Instead of a Secondary Column

It may seem intuitive to always use a Secondary category when each record represents a separate value because Secondary categories give the best angle to manipulate data. However, Secondary categories do not allow for column properties that the Value columns support, such as coloring individual lines or bars.

An example of when to use multiple Value columns instead of a Secondary column would be for data within a finite number of possible states. For instance, if there is a record that denotes Pass or Fail, there are only ever going to be two individual series (the Pass series and the Fail series). If a view is created to return the following data, “Green” can be the color for Pass and “Red” for Fail. This kind of manipulation can only be performed at the Value column level.

This dataset can be displayed as follows:

Date

Pass

Fail

1/1/1990

15

30

 This same dataset can be displayed as follows:

Date

Status

Occurrences

1/1/1990

‘Pass’

15

1/1/1990

‘Fail’

30

However, the level of configuration is limited per Status if implemented in the second fashion. If statuses themselves are not derived from user or application data, the finite number of Statuses should be Status1 converted to Value columns.

Add Binding Criteria

If you link pages to charts, or charts to other charts then you can pass parameters to filter the chart using the Link to Page field at the column level and defining the binding field names value.

To add binding criteria:

  1. Access the Page Columns page in System Administration for the chart page. .
  2. Click the link in the LINK TO PAGE column for the for the column to be bound (as in, the bar that the user will click on chart to access the page or chart)..
  3. Click Edit.
  1. Enter the name of the key field(s) to bind the data from the current page or chart to the linked to page in the Binding Field Names
  2. Enter additional field name(s) for columns that are not key fields and are not normally passed in the Shared Field Names

NOTE: Enter multiple columns separated by a comma.

  1. Click Save.

Configure Chart Properties

NOTE: There are no Chart Properties for Tabular charts. The option to set a page Order By for sorting on the Pages page is not available.

Chart Type

Property

Description

Area

Bar

Column

Line

Stacked Type

Select an option to control how stacked data is displayed. Options:

·       Normal – Each section of the stack is represented by its value. The stack is a total of the values that make up each section.

·       Percent – Each section within the stack is represented by its percentage value of the whole. Stacks are of equal height and total up to 100% of the given series.

Zoom Type

Select an option to control the axis/axes on which users can zoom in and out. Options:

·       X – Users can zoom in and out on only the X axis

·       XY – Users can zoom in and out on both the X and Y axes

·       Y – Users can zoon in and out on only the Y axis

Legend Location

Select location of legend within the chart area. Options are Bottom, Left, Right and Top.

Show Value On Hover

If checked, the chart value displays as a tooltip when hovering over the chart selection.

X Show Major Gridline

If checked, major gridlines displays on the X axis.

Y Show Major Gridline

If checked, major gridlines displays on the Y axis.

Doughnut

Pie

Legend Location

 

Select location of legend within the chart area. Options are Bottom, Left, Right and Top.

Show Value On Hover

If checked, the chart value displays as a tooltip when hovering over the chart selection.

Pie Label Location

Select a location of the pie data labels. Options are inside or outside the pie area.

Pie Collected Threshold

Enter threshold, in percentage of the total pie size, under which all points are collected into a grouped pie slice.

Pie Collected Label

Enter label that applies to the collected grouping. When there are pie pieces below the Pie Collected Threshold, they are aggregated into a single piece of the pie chart. The Pie Collected Label is the text that describes the aggregated pie slice.

Pie Collected Exploded

If checked, the aggregated pie slice is slightly separated from the rest of the pie chart.

Supplemental Pie Chart Size

 

Select the size of the aggregated pie chart in relation to the size of the original pie chart. The aggregated pie slice displays when the Pie Collected Threshold is set. Options:

·       Smaller – Supplemental pie chart displays smaller than the original pie chart

·       Same – Supplemental pie chart displays the same size as the original pie chart

Bar, Column, and Line Charts

Bar_Column_Line_Diagram.png

Pie and Doughnut Charts

Pie_Doughnut_diagram.png

Drill Down from Chart to Additional Data

Charts can be linked together so that users can drill down to see data at a more granular level. Charts can also be linked to any page type (dynamic, static, dashboard, header detail, etc.) so that when a chart section is clicked (a pie slice in a pie chart, a bar in a bar chart, etc.), a data page or another chart displays to show additional details.

Example

For example, this pie chart illustrates the number of orders placed by an individual.

Pie_Chart_example_Employee_Order.png

To view details about the individual who placed an order, click any pie slice to be navigated to a data page:

DSP_page__example_Employee_Order.png

To use the drill down feature on a chart:

  1. Create a chart. Refer to Create a Chart for detailed information.
  2. Create a page to display the drill-down data.
  3. Modify the chart page’s column properties for the Category control so that the LINK TO PAGE is the page created in Step #2. In the above example, the LINK TO PAGE is set to the Employees page.

Page_Column_Category_Value.png

Dashboard Basics

A Dashboard is a page type where chart pages are registered. Developers can put any charts assigned to any WebApps into a dashboard, so be mindful of security and the dashboard audience when assigning charts to a dashboard.

This section contains the following subsections:

Create a Dashboard Page

A dashboard is created via a Dashboard page type.

To create a dashboard page:

  1. Create charts to assign to the dashboard. Refer to Create a Chart for more information.
  2. Create a page for a WebApp where:
    1. PAGE TYPE = Dashboard
    2. TABLE = Blank
    3. Layout ID = Collection of chart pages. Select a layout or click + icon to add a new layout. Refer to Create a Layout for detailed information.
    4. Horizontal Menu ID = Menu where dashboard is accessed
  3. Return to the WebApp and refresh to view the chart. Modify chart properties as needed.

Create a Layout

A layout controls how and which chart pages display within a dashboard. Several layouts are delivered with BackOffice Solutions; however, they cannot be modified. Users may copy delivered layouts and modify as needed or create custom layouts.

NOTE: A layout that is currently assigned to a page cannot be modified. If it were modified, the change would cascade to all dashboards with potential undesired effects. The layout can be copied and modified or unassigned from a dashboard and modified.

There are four methods to create a layout:

  1. Create a Layout while Creating a Dashboard Page
  2. Create a Layout while Customizing a Dashboard Page
  3. Create a Layout via the Configuration Menu
  4. Copy a Layout

Create a Layout while Creating a Dashboard Page

When creating a Dashboard page, users are able to create a layout directly from the Pages page, without leaving the page to navigate to the Layout page in order to create a new layout.

To create a layout while creating a Dashboard page:

  1. On the Vertical View of the Pages page for the Dashboard page type, click Edit.
  2. Click the + icon for the Layout ID; a new browser tab opens to display the Layouts page in add mode.
  3. Enter the name of the layout in the DESCRIPTION
  4. Click the binoculars icon for LAYOUT TEMPLATE ID to see a visual example of each layout template ID on the LayoutTemplateID
  5. Click Choose Record next to the LAYOUT TEMPLATE to select the layout.
  6. Click Save.
  7. Click the Layout Frames
  8. Edit records to assign chart pages to each frame of the layout. Only chart pages to which the user has access display. Refer to Dashboard Security for more information on user security.

NOTE: The charts are list unique. The same chart cannot be assigned to the same dashboard multiple times.

Create a Layout while Customizing a Dashboard Page

BackOffice Solutions is delivered with several dashboards. Some of these dashboards may not be suitable for a client’s business needs. A Developer can create a custom dashboard.

When customizing a Dashboard page, users are able to create a layout directly from the Pages page, without having to leave the page to navigate to the Layout page in order to create a new layout.

To customize a layout while creating a Dashboard page:

  1. Verify the logged in user is a member of the Customizer WebApp group for System Administration.
  2. Navigate to the Dashboard page.
  3. Click the Gear icon on the Site Toolbar.
  4. Select Customize; the Page Extension icon displays in edit mode.
  5. Select a layout from Layout ID list box.

Or

Click the + icon to create a new layout. Refer to Create a Layout while Creating a Dashboard Page for detailed information on how to populate the layout fields.

  1. Click Save.

Create a Custom Layout via the Configuration Menu

Create a layout page via the Configuration menu to add a layout independent from a Dashboard page. This method is helpful if creating multiple layouts that are not necessarily associated with a defined Dashboard page.

To create a layout via the Configuration menu:

  1. Click Admin > Configuration > Layouts in Navigation
  2. Add a layout record. Refer to Create a Layout while Creating a Dashboard Page for details on each field.

Copy a Layout

Several layouts are delivered with BackOffice Solutions; however, they cannot be modified. Users may copy delivered layouts and modify as needed.

Copying a layout can be done while creating a layout for a Dashboard page, customizing a layout for a Dashboard page or creating a layout via the Configuration menu.

To copy a layout:

  1. Navigate to the Layouts
  2. Select a layout.
  3. Click the Copy icon on the Page toolbar.
  4. Locate the copied layout and configure as needed. Refer to Create a Layout while Creating a Dashboard Page for details on each field.

Copy Existing Dashboard

As with any WebApp page, dashboards can be copied between applications. When a dashboard is copied, a new layout is created and populated for the copied page.

This process should only be used when adding a new page to a custom WebApp.

To copy an existing dashboard:

  1. Navigate to the Vertical View of the dashboard.
  2. Click the Advanced Properties
  3. Click the Copy
  4. Modify page properties as needed.
  5. Click the Copy

Dashboard Security

Onsite developers can create a new layout and override the default WebApp registration at three levels:

  1. For all users
  2. By role security
  3. For an individual user

NOTE: Refer to online documentation for details about assigning a dashboard at each level (Admin > Customization > WebApp Customization > Pages > Click Help icon).

All three levels exist concurrently and are applied in the following order (per WebApp):

  1. User – The user-defined layout displays, if one exists
  2. Group – If a user defined layout does not exist, but a role defined layout does, the role defined layout displays
  3. All – If the user does not have a user defined or role defined layout, the default layout displays
  4. None – If there are no customizations, the dashboard delivered with BackOffice Solutions display for all users

NOTE: Users can review the precedence that security is applied via the Review icon on the Page Customization page (Admin > Customization > WebApp Customization > Pages > Review).                 

Users who have been granted Customize Security can control their own view by creating a layout and assigning it to a WebApp dashboard. This process overrides the default group and any other assigned user layout.

Users can select any layout in which they have permissions to each page registered on the layout. When users customize from the Customize menu, they only see layouts where they have permissions to each individual page within the layout (as defined under WebApp Group permissions/roles).

Dashboard pages are one of the few features in the DSP® that are customizable and are not affected by upgrade.

Grant Customize Security

The layout of a dashboard can be changed based on a user’s preference. The ability to change the layout is controlled by the Customizer WebApp group for System Administration. By default, all users who have access to System Administration have security to this group.

To grant customize security:

  1. Add a user to a security role where the Customize WebApp group for System Administration has been added.

Or

  1. Add a user to the Customize WebApp group for System Administration.

Assign Layout to a Group of Users

A user, most likely a project lead, can create a layout that is then available to the team. Create the layout and assign it to a group of users.

To assign a layout to a group of users:

  1. Create a Security Role. Refer to online documentation for details.
  2. Assign users to the Security Role. Refer to online documentation for details.
  3. Assign a key to the security role where the Key is the Layout ID. Refer to online documentation for details.

Make Dashboard Default Upon Login

BackOffice Solutions can be configured to display a dashboard when users log in. This default dashboard can be different for an individual user or a security role.

To change dashboard default:

  1. Select Admin > Customization > WebApp Customization from the Navigation
  2. Click Pages for WebApp.
  3. Click Default.
  4. Update the Layout ID list box.

Use Delivered Dashboard

If the delivered dashboard has been replaced with a custom dashboard, users can set the delivered dashboard to display on login.

To use the delivered dashboard for the current user after it has been replaced with a custom dashboard:

  1. Navigate to the Dashboard page.
  2. Click the Tools icon on the Site toolbar.
  3. Select Customize; the Page Extensions page displays in edit mode.
  4. Select [None] from the Layout ID list box.
  5. Click Save.

NOTE: The Default and Role level customizations still take effect.

Related articles