• Read on! This documentation covers Dashboards in detail.

• View the Dashboards Webinar (1 hour)

• Check out the introductory Dashboards Video (5 min) Coming soon!

Overview

DocuPhase Forms Dashboards is a reporting feature that allows you to collate, visualize and share metrics and operational insights from your forms and workflows. Use Dashboards to create beautiful, functional reports that give your stakeholders at-a-glance insight into your business and help you monitor the efficiency of your workflow processes. Designers will appreciate the familiar user interface, the broad selection of chart types, filtering and customization options, and the ability to deploy dashboards anywhere, just like a form or workflow.

Open

This Dashboards documentation assumes a general knowledge of DocuPhase Forms design features for forms and workflows, including controls, business rules and settings. Designers building dashboards likely already have forms and workflows in production with submissions. If you are new to DocuPhase Forms, we recommend starting with the Quick Start Video Guide or the Workflow Tutorial.

On this page

• 1 Overview
  • 1.1 Form and Workflow Design for Dashboards
• 2 Create a Dashboard
• 3 Dashboard Designer
  • 3.1 Dashboard Canvas
    • 3.1.1 Dashboard Header
  • 3.2 Dashboard Palette
  • 3.3 Chart and Data Table Settings
    • 3.3.1 Data
    • 3.3.2 Null or Missing Fields
    • 3.3.3 Data Table in Design Mode
    • 3.3.4 Max Data
  • 3.4 Style Properties
  • 3.5 Chart Styles
    • 3.5.1 Axes
    • 3.5.2 X Axis and Y Axis
    • 3.5.3 Data Labeling
    • 3.5.4 Background, Border and Grid
    • 3.5.5 Legend
    • 3.5.6 Color Palette
    • 3.5.7 Radial Axis
    • 3.5.8 Axis Zones
    • 3.5.9 Radar Axis
    • 3.5.10 KPI
    • 3.5.11 Color Picker
  • 3.6 Table Styles
    • 3.6.1 Table Settings
    • 3.6.2 Other Styles
• 4 Dashboards at Runtime
  • 4.1 Download to CSV
  • 4.2 Mobile View
  • 4.3 Filter Errors
• 5 Data Set Validation
  • 5.1 Form and Workflow Changes
    • 5.1.1 Changes that Cause Dashboard Errors
• 6 Dashboard Rules
• 7 Dashboard Settings
  • 7.1 Settings Tab
  • 7.2 Access Control Tab
  • 7.3 Style Tab
• 8 Sharing Dashboards

Form and Workflow Design for Dashboards

While this documentation is heavily focused on the technical side of creating and customizing dashboards, form/workflow design plays an important role in optimizing this feature.

Designing forms and workflows with dashboards in mind will ensure your process is complete, efficient, productive, and manageable. Form/Workflow design should take into account the key stakeholders in the process and the reporting, monitoring, analysis, and strategic needs of the stakeholders and participants. The designer must quantify and specify those insights in terms of measurements, key performance indicators (KPIs), analytics, and data that is to be derived. This information can be roughly categorized into:

• Strategic data used to measure the process against set goals

• Analytical information that is more tactical and discovery in nature

• Operational and real-time process information

For example, a strategic goal in a Procure-to-Pay process might be on-time procurement. The designer would want to ensure the workflow captures data that can measure this, such as a deadline date and a calculation to determine if the procurement is early, on time, or late.

An example of a tactical insight in the same Procure-to-Pay process is discovering volume buying and discount opportunities. The form/workflow should capture relevant information on the product/service, including category, vendor, rate, and discount information (if any) that allows a stakeholder to assess this metric.

Operational statistics help determine efficiency and look for improvements by examining both data and metadata; for example, in the same Procure-to-Pay process it might be helpful to know which department the current workload is coming from, if the productivity is in line with given resources, and if there are inefficiencies that can be visualized and corrected. Much of this type of information is available in DocuPhase Forms dashboards by default, including submitter information, process duration, relevant process date/times (start, completion, etc.), and error information.

Create a Dashboard

Dashboards are created as part of a project. When you open a Project, you will see a Dashboards tab on the left side menu.

Open

Click the Add icon to create a new dashboard, upload a dashboard, or install a pre-built dashboard template.

• Install a prebuilt template allows you to create a dashboard from a template that has been published in your tenant. See the templates documentation for more details.

• Create a new dashboard generates a blank dashboard. You will customize each aspect of it, including adding charts and connecting a data source.

• Upload a dashboard installs a DocuPhase Forms dashboard from a previously downloaded _dashboard.zip file. You might use this when moving a dashboard from a development project to a production project. If you attempt to upload a _form.zip or _workflow.zip from this page, it will upload successfully and will redirect you to the Forms and Workflows homepage. The reverse is also true; upload a _dashboard.zip in the "Upload a form/workflow" dialogue, and you will be redirected to the Dashboards home page.

Once you click an option, you will be taken to the Dashboard Designer.

Your dashboards will appear in the list, which can be sorted by Update Date or Name.

Similar to the Forms and Workflows home page, dashboards with any error will display with a salmon background. See Data Set Validation for more details.

Each Dashboard in the list has a Test icon, which opens the dashboard in test mode, and 3-dot Action menu with the following options:

• Edit opens the Dashboard Designer. You can also open the designer by clicking the dashboard name in the list.

• Test opens the dashboard in test mode.

• Set Permissions opens the Access Control wizard.

• Duplicate creates a copy of the dashboard in the same project. You will immediately see the copied dashboard in the list.

• Share opens the share dialog that provides links for sharing a link or embedding your dashboards for end-users.

• Deploy/Undeploy changes the form from development to production or vice versa.

• Download dashboard zip file downloads a zipped file of the dashboard which can be uploaded into another DocuPhase Forms project.

• Publish as template makes the dashboard available as a template - the tenant admin must publish the template in order for other designers to use it. See the templates documentation for more details.

• Upload thumbnail allows you to upload an icon that will appear when the dashboard list is viewed in DocuPhase Forms Portal on a mobile device.

• Upload translation allows you to provide a translation file to internationalize the dashboard.

• Delete removes the dashboard. This is permanent and cannot be reversed.

Dashboard Designer

The Dashboard Designer is laid out similarly to the form and workflow designers.

Across the top, you will see:

• Dashboard Name, editable by hovering over it and then clicking the pencil icon.

• Guided Designer Navigation Bar allows you to switch between Dashboard, Rule and Settings editing modes.

• Action Menu with options to Save, Save and Test, Cancel and Close, Preview a read-only view, or show/hide mobile page breaks.

On the left side, you will see two palettes:

• Filter Palette provides controls that you can add to allow the end-user to filter the dashboard at run time.

• Dashboard Palette provides various chart types that you can add to your dashboard canvas.

The Properties panel will display chart properties when a chart is selected and control properties when a control is selected. This is where you will add data sources and customize your chart. See Chart Properties.

Dashboard Canvas

The center of the screen contains the dashboard canvas, which consists of three sections.

Dashboard Header

Every dashboard automatically includes a dashboard header. It is automatically added as the first control at the top when the dashboard is created. It cannot be moved or deleted. Other controls must be added below it. The dashboard header can optionally be hidden. Select the header to show its properties in the Properties panel.

The dashboard header consists of up to three distinct areas on the canvas. Two of these areas are shown in the image above.

Title

The top area is the Dashboard Title and is very similar to a message control. The Message property accepts HTML markup and displays it as the title, or toggle the Rich Text property to use the Rich Text Editor instead. The title may also contain templatized strings.

Status

The area below the Dashboard Title is the status area. It optionally shows the “as of” status and the “viewed by” status. The data shown on a dashboard is relative to a point in time and relative to the user that ran the dashboard. The status information is shown to give the user context; at a different time or for a different user, the data shown could be different. However, the designer could choose to not show either or both of these status fields by unchecking the “Show Status” and “Show Viewer” checkboxes in the Properties panel. They are both checked by default.

Filter Parameters

The dashboard header also supports an optional filter parameter area. The filter parameter area allows the end-user to customize the runtime dashboard by making selections that will alter the data shown on the dashboard. The filter parameter area includes a filter icon  that allows the designer or end-user to collapse or expand the filters. Set the filter to expanded in the designer to show it expanded by default in use mode or vice versa.

Select “Enable Filter” in the dashboard header Properties panel to display and edit the filter parameter area. This will display the filter icon button in the status area of the dashboard header.  

Most Filter Palette controls can be dropped inside the filter parameter area (but not outside of it). The only exception is that page break controls may only be dropped on the canvas outside of the filter parameter area. Charts and data tables may not be dropped inside the filter parameter “dropdown” area. Note that the signature, form viewer, and submit controls are not present on the Filter Palette in the dashboard designer.

The controls inside the filter parameter area can be used to filter the dashboard, altering the data that is displayed. To do this, the designer will use these controls as templatized strings in the data configurator wizard, but most importantly in the advanced data filter screen, for the various charts and data tables on the dashboard. As the end-user makes parameter changes, each chart and data table’s data filters are altered. This triggers the data to be retrieved again and the dashboard view to automatically refresh. Rules are available in dashboards and have full access to the controls inside the filter parameter area. The designer can also set default values in the filter controls. 

Header Properties

The Dashboard Header properties panel has a Settings tab and a Style tab.

Settings

Similar to message controls, there is a Message property that accepts HTML markup and a Rich Text toggle that makes the Rich Text Editor available. You can also give the header a name and CSS Class if desired. The Visible and Printable properties work as they do in other controls. You will also see three header-specific properties:

• Show Status displays "As of <current date/time>". 

• Show Viewer displays "Viewed by <current user>"

• Enable Filter enables the filter parameters area

If any of these three properties are checked, the status area is displayed. 

Styles

The styles tab for the dashboard header has been enhanced with new style properties to allow the designer a wide latitude in customizing the markup area of the header.

• BG Color sets the background color of the control.
  The following 4 properties apply only to the Title area.

• Surface Color is used to set the background color inside the Title area (as opposed to the background color of the area outside the box).

• Border Width property defaults to the width set by DocuPhase Forms for all control borders and has options for no border as well as overrides of thin, medium, wide, and extra-wide.

• Border Color defaults to the color inherited from the color scheme/style for borders and can be overridden with any valid CSS color name or its hexadecimal RGB equivalent.

• Border Style defaults to solid unless overridden with one of the CSS border style settings in the dropdown.

All color properties accept any valid CSS color name or its hexadecimal RGB equivalent.

Dashboard Palette

The Dashboard Palette contains all of the chart controls you can use in your dashboard. See the Chart Types page for a detailed description of each type and when you might use it.

• Pie and Donut

• Bar

• Column

• Area

• Line

• Scatter and Scatter Line

• Radar

• Data Table

• Radial Gauge

• KPI

Click any control and drag it to the canvas to add it to your dashboard. Just like when you add controls to a form canvas, you can change the width, and drag and drop additional controls to the right, left, above, or below any existing charts. Green arrows will appear to show you where you can drop the chart control. 

When you drop a chart control onto the canvas, it will display some sample data so that you can get an idea of what it will look like with your real data. You must configure the chart in order to show real data.

Chart and Data Table Settings

Chart and data table settings and style tab(s) will display in the Properties Panel when they are selected. Several settings are familiar from Palette Control Settings. Click the links on the following property names to learn more: Label, Name, CSS Class, Visible, Printable, Hide Label. The Label on a chart will display at the top of the chart.

The remainder of this section discusses chart settings specific to Dashboard Palette controls.

Data

Use the Data property to configure the data that will display in the chart. When you first drag and drop a chart to the canvas, you will see a warning "NOT Configured!" under the Edit Configuration button. If there is a data configuration error, you will see a "Configuration Error" warning here (see Data Set Validation for more info on resolving errors).

Click Edit Configuration to begin. This will display a "Configure <Chart Type> Data" wizard. The icon and title indicates the chart type you are working on.

Data Source

The first screen displays a required Data Source dropdown. Select a form/workflow as the data source for this chart/table. The selectable forms/workflows are those that the designer owns, those that have been shared for View/Edit Submissions, and those that have been shared for Editing by another designer in the tenant. See the Access Control and Shared Items page for details about these permissions.

Click NEXT to continue configuring the chart.

Field Selection

The next screen in the wizard is the field selection screen. This screen will vary in behavior depending on the chart type or data table being configured. The fields available are those you have set up as Searchable Fields in the form/workflow settings, and metadata fields (Age/Duration, Error, Error Description, Lock Date, Lock User ID, Lock User Name, Started Date, State, Submitted Date, Submitter ID, Submitter Name).

The screen below is the field selection screen for a column or bar chart. To use a column/bar chart the user selects a searchable field from the source form/workflow as the dimension. The dimension represents the category used for each column/bar. The value of the metric field chosen will determine the height/length of the column/bar (also known as the 'measure').

Dimension and Metric

Typically, the dimension is a text field or a date/time field that is aggregated or not, but there is no restriction on type for most chart types. The exception to this is for scatter and scatter line charts which require the dimension to be date/time or numeric. If the dimension is a Date, DateTime, or Time field, the dimension will be treated as a “time” axis. This applies to bar, column, line, area, scatter and scatter line charts. A “time” axis can be thought of as a timeline and metric items are plotted/positioned based on the relative time/date. Any other type of dimension is treated as a “category” axis where metric items are plotted/positioned evenly along the axis (not applicable to scatter/scatter line). Radar charts are conceptually the same except that everything is plotted radially.

The metric must always be a numeric “value” and this includes the special “age” metadata field. Therefore it must be either a number, quantity, or money field, or any field type with a count/count distinct aggregation. The dropdowns for dimensions and metrics are not restricted by type and will show all Searchable Fields, so the designer must choose fields that meet these criteria.

Aggregation

Any selected dimension aggregation provides a sub-range to apply any selected metric aggregation over. Dimension and metric aggregation can be applied independently. The aggregations available are dependent upon the field type selected. For example, Day, Week, Month, Year and Quarter are only available on Date and DateTime fields. The optional alias is used in column headings (data table), axis labels, tool tips and data labels.

The following additional validations are done on this screen:

• If any fields are from a repeat, then only one repeating item's fields can be included. You cannot mix repeating fields from more than one repeat/table in a single query.

• If aggregating (including dimension), then all metrics must be aggregated.

• If there is more than one metric, then metrics must be either all aggregated or all not aggregated.

• All aggregated non-date/time fields must at the same level/parentage. If one is from the main form/workflow they all must be or if one is from a repeat/table, they all must be.

• The special calculated "age/duration" field cannot be part of a functional expression.

• If aggregating any field, then the special calculated "age/duration" field cannot be part of the data set.

• In advanced mode, every dimension and metric field expression must have at least one data field in it - literal only expressions are not allowed.

The “age/duration” field is a special calculated field and cannot be part of an aggregated query, nor part of a filter, nor be a sorted field.

The field select screen for other chart types will vary as follows:

The following additional validations are done on this screen and are relevant to advanced view and expressions:

• If aggregating (including dimension), then no dimension may contain an aggregated sub-expression. This means that any aggregation function must be at the first level.

• Aggregation functions may not be nested within another aggregation function.

• If any metric contains an aggregation nested in another non-aggregation function(s), the containing function(s) must not reference any fields as parameters. Doing so would alter the grouping in a way the user would not intend, so it is not supported.

Field Selection for Data Table

The field select screen shown when configuring data for a data table is shown below. 

The following validations are done on this screen:

• When configuring a table with a non-date/time aggregated field, there must either be at least one other field that is not aggregated or there must be an aggregated date/time field. This is because non-date/time aggregations require some range to aggregate over for a valid query.

• If any fields are from a repeat, then only one repeating item's fields can be included. You cannot mix repeating fields from more than one repeat/table in a single query.

• If aggregating, then there must be at least one non-date/time field aggregation.

• All aggregated non-date/time fields must at the same level/parentage. If one is from the main form/flow they all must be or if one is from a repeat/table, they all must be.

• If aggregating any field, then the special calculated "age/duration" field cannot be part of the data set.

Field Selection Advanced View

In advanced mode, the designer is allowed to enter functional expressions involving one or more fields and can select a display format.

The field and aggregation dropdowns on the non-advanced version of the screen are replaced by an expression input control (similar to the Visual Rule Builder). The designer may enter functional expressions involving multiple fields and nested functions. The expression input offers similar completion prompts, help, and validations as those seen in the Visual Rule Builder expression input. The field and aggregation selects found on the non-advanced version of the screen provide a simple and limited ability to build an aggregating expression and anything entered there is carried over to the advanced version of the screen when changing modes.

The advanced version of the screen additionally allows the selection of a display format for the selected dimension and the metrics. Any chosen display format is used in data labeling and tooltips on the chart. In a data table, the formatting is applied in the table. Also, multiple metrics are supported by the bar/column chart, so advanced mode makes that possible with the appearance of the blue plus icon. At least one metric is required.

Configuring fields for a Data Table in advanced view allows the designer to specify the following on the selected table columns:

• Aggregation function

• An alias

• A display format.