Prepare Data for Building Reports

This page applies to developers. It describes how to prepare record types for reporting in Process HQ.

Overview

Process HQ allows business users to securely explore record types as datasets. Using those datasets, users can build custom reports and dashboards that leverage the record data and other elements of the record type.

To provide users with the best experience, review the following elements of your record type since they will be visible to business users:

• Record type display names.
• Record type descriptions.
• Field names.
• Relationship names.
• Data source logos.
• Summary view.
• Record actions.
• Custom record fields for business process metrics.

Record type display names

Each dataset is labeled with the Display Name (Plural) value from the record type.

Review the record type's display name to ensure that it does not include an application prefix and that it can be easily understood by business users.

To edit the record type’s display name:

1. In your record type, go to Settings > Properties.
2. Update the Display Name (Properties) as needed.
3. Click SAVE CHANGES.

Record type descriptions

When a user hovers over a dataset, they will see the record type's description.

Review the record type's description to ensure it does not include any developer terminology (like "record type" or "sync enabled"), and that it is useful to a business user. The description should help users understand whether or not this is the information they're looking for.

To edit the record type’s description:

1. In your record type, go to Settings > Properties.
2. Update the Description as needed.
3. Click SAVE CHANGES to close the dialog.
4. Click SAVE to save the record type.

Field names

When a user selects a dataset, they will see a list of fields from the base record type and any one-to-one and many-to-one related record types. They can use these fields to build a grid, chart, or KPI.

To ensure users can easily find the fields they need:

• Use camel case formatting for record field names. A dataset will automatically convert any camel case field names to title case field names so they're easier to read. For example, if you have a record field called lastName, it would convert to Last Name in the dataset.
  
  

• Add field display names. If your record field names contain acronyms or they are not easily understood by business users, you can configure display names on your record fields. Display names allow you to provide users with friendly field names in Process HQ. For example, if you have a record field called YTDSales, you can configure a display name of Year-to-Date Sales so business users can see an easily understand the field name and purpose.
  
  

• Logically group record fields together. The fields in a dataset will appear in the same order as the fields in the record type. Ensure that fields like firstName and lastName, or address and zipCode are grouped together in the record type's data structure. This will ensure that the fields appear next to each other when a user selects fields for their report.

The image below illustrates how the fields in the Customer record type appear to business users in a dataset:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

To modify fields and the order they appear to business users:

1. In your record type, go to Data Model.
2. Click MAP RECORD FIELDS.
3. Edit the Record Field Name to rename a field.
4. Enter a Display Name to provide a user-friendly field name to business users in Process HQ. When this field is blank, the Record Field Name is displayed in the dataset using title case format.
5. Click Drag to reorder and place the field in the proper order.
6. Click FINISH.
7. Click next to a custom record field to add a display name and description. You cannot reorder custom record fields.
8. Click SAVE.

Relationship names

When a user selects a dataset, the data from any one-to-one or many-to-one relationships will appear under the relationship name. For example, the image below displays the Customers dataset, where the related data appears under the relationship names.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Review your relationship names to ensure that they are easily understandable and do not include an application prefix. For example, if you have a relationship name like ARregion, you should update the name to region so it displays as Region in a dataset.

To edit a relationship name:

1. In your record type, go to Data Model.
2. Under RELATIONSHIPS, click the relationship name you want to edit.
3. Update the Relationship Name as needed.
4. Click OK.
5. Click SAVE.

Data source logos

Each dataset will display the data source of the base record type and its related record types using vendor logos. The vendor logos that appear on a dataset are the same as the logos that appear in the record type relationship diagram.

A dataset will automatically display the logos for any Appian supported databases and certain connected systems.

The following connected systems will not automatically display a vendor logo, but you can manually configure a logo to display:

• HTTP Connected System.
• OpenAPI Connected System.
• Custom JDBC Connected System.

To display a vendor logo for these connected systems, select an image for the System Logo in the connected system's properties.

Summary view

When users configure a grid in a report, they can add links to each record’s summary view. By default, the link will open in the Default Start Page configured in the Admin Console, and display the summary view configured on the base record type.

Ensure a summary view is configured on the record types. If no summary view is configured, only the record title will display when users open the link.

Record actions

In addition to links to the summary view, users can also display record actions on a grid in a report.

Users can only display record actions from the base record type, and they must have permission to the record action. Review the record actions are available on your record types, and ensure that users have the necessary permissions to access those actions.

Custom record fields for business process metrics

You can use custom record fields to transform and aggregate data to display in your reports. For example, you can calculate common success metrics for your business processes.

When you configure record events for a record type, Appian will automatically include custom record fields that calculate the total duration for each instance of your business process.

If you already have record events configured, Appian will prompt you to use the Calculate Duration custom record field template to quickly add these fields to your record type, so they'll be available in datasets when users build reports.

Troubleshoot datasets

As a developer, you may be asked to troubleshoot or explain certain aspects of data fabric insights to your users. This section describes issues that can commonly occur.

Missing or stale data

In the dataset, you can see the number of rows in the base record type since the last full sync.

If that number is lower than expected, the data will be updated during the next scheduled full sync.

Unavailable datasets

Business users may be unable to access a dataset in the Data Catalog or in an existing report or dashboard.

There are a few reasons why a dataset may be unavailable:

Reason	Business User Impact	Troubleshooting
The record type failed to sync.	Users cannot select the corresponding dataset, use the data in a report or dashboard, or view the data in a report or dashboard.	Review the status and history of syncs associated with your record type to ensure your data is syncing successfully. See troubleshooting data sync for information on how to resolve sync issues.
The user does not have access to view the record type.	Users cannot see the record type as a dataset in the Data Catalog, or view or edit a report that uses the record data.	Review security on the record type to ensure users have the correct record type security, record-level security, and field-level security.
The record type or a related record type is not configured to show as a dataset.	Users cannot see the record type as a dataset in the Data Catalog or in any other datasets where the record type is configured as a related record type.	Show the record type and any related record types as datasets in the Data Catalog of Process HQ.

Feedback