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.

View this blog article for additional information and examples of optimal form/workflow design for dashboards.

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.

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 Visibility

Dashboard visibility is tied to the form/workflow access control of the user attempting to view/edit it.

• A designer who can edit a dashboard, and has access to submissions, can see a dashboard in design mode

• A designer who can edit a dashboard, but does not have access to submissions, can not see dashboards in design mode

• Any logged-in user can see dashboards in use mode if it has access to submissions(edit/view submissions)

• Anonymous users can not see Dashboards in use mode

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.

The status area is only visible if at least one of three properties is checked: Show Status, Show Viewer and/or Enable Filter. 

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.  

The ability for the end-user to save filter parameter selections is not supported at this time.

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.

Once you configure a Dashboard, certain changes made to the form/workflow used as the Data Source can cause the dashboard to "break". You will see validation errors in design mode and the Dashboard will not display data at run time. Some changes can prevent a dashboard from displaying any past submission data. Please see Form and Workflow Changes for examples of changes that cause this error state.

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.

Null or Missing Fields

If a field used in your dimension or metric has the potential to be null or missing in some submissions (e.g. if it is not required and may be left blank, might be nulled by a business rule, or was added after the form already had submissions), this may cause irregularities in your chart. It can appear that data is missing, especially when rolling up/aggregating by a field with some null values. Generally, it is advisable to ensure controls used as Dimensions and Metrics have some value; however, this is not a hard-and-fast rule.

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.

Please refer to the validations described above, which also apply to advanced view.

Click NEXT to continue configuring the chart.

Data Filter

The next screen allows the designer to filter the data. In the non-advanced view the user may only filter by submitted date using the simplified selections in the dropdown. For example, the filter below is for data with a submitted date within the last 6 months from now. All date/time filtering is done relative to the user/browser time zone.

Data Filter Advanced View

The advanced filter screen is used to construct a Boolean expression of filter clauses. Each clause is composed of a left side field from the data source, a match condition in the middle and a right value for the match condition. Note that a few condition types do not require a right side match value. The available match conditions for each field type always include a condition and its opposite (negated) condition. This fact along with the ability to combine clauses using AND and OR Boolean operators enable the designer to build any logical filter expression.

• Any choice made on the non-advanced screen is carried over to the advanced screen.

• As soon as additional filter clauses are added making the filter non-displayable on the non-advanced screen, the advanced view toggle switch is disabled and locked on the advanced setting.

Designers can build a logic expression consisting of AND and OR clauses as well as group sub-expressions. The choice of Boolean operator is made at the time the new clause is added as well as the choice of whether to explicitly “group” the newly added clause with the clause above it. The add menu illustrated below shows the AND/OR items as well as the grouping version of each.

As logic sub-expression groups are added, they are shown in a box to indicate the grouping. Since these can be nested, the nested boxes alternate with and without shading. A max nesting of 4 (explicit) levels is supported. Note that the system will implicitly group sub-expressions as necessary to accurately indicate the order of evaluation. For example, if starting with A AND B and you add an OR of C, the result will be (A AND B ) OR C. Nested grouping is illustrated below.

Much like the submission view filter, the conditions vary based on the type of the chosen field and are the same with only minor wording changes from what are used in the submissions filter. The right side value input area is rich in functionality and includes the following:

• A templatized string is allowed. Controls from the dashboard filter parameter area may be chosen as templates, and will be resolved as the value of that field at runtime. The right side field has a dropdown used for the selection of a control template. The user may also type “{“ followed by match text and the system will bring up a list of potential matching control templates.

• When the right side value is a template, a toggle appears that allows the display of a required test value field. The toggle will cycle between the value and the test value field. The designer must enter a value that will be used for the filter clause when in design mode. This is necessary because templates are not resolved at design time, but we still want to see data in the chart/table at design time. Templates are not allowed in the test value field. 

  • When the selected left side field is a Date, Time or DateTime, the right side field will also include a picker icon that brings up the appropriate picker overlay (calendar or time).
    
    

    Open

    

  • When the selected left side field is a DateTime and the selected condition is “is within last”, then the right side value must be a time duration and the user is prompted: “Enter as: PnYnMnDTnHnMnS”.
    
    

    
    
    

  • When the selected left side field is a DateTime and the selected condition is “is within the current” or “is within the previous”, the right side value must be one of the standard time periods (year, quarter, month, week or day). The drop down includes these options. See the non-advanced filter options discussion above for more on this.
    

    
    
    

• When the selected left side field is the metadata field ‘state’, then the only operators available are equals and not equals. The right side dropdown contains selectable options for the 5 submission states: PENDING, SUBMITTED, SAVED, ABORTED, WAITING.
  

The following validations are done on the filter screen:

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

• An aggregated query may not contain a filter with OR clauses that reference fields from the form/workflow itself and a child repeat or table. This is a limitation of querying against SOLR.

The control type on the left and right sides of the expression must be compatible, and the filter expression must resolve to a valid value at run time. Please see Filter Errors for details.

Click NEXT to continue configuring the chart.

Sort Order

Next, the wizard shows the sorting screen. Simply order columns to sort by with the first being primary, etc. Each can be ordered ascending or descending.

The fields available for sorting depends on the chart type and the dimension type chosen, as shown in this table.