Record Design

Overview

This article provides some recommended practices when designing Appian Records. For other topics related to Appian Records, see:

To walk through an example of creating your first record, see the record tutorials on the Tutorials page.

Record Purpose

The first thing you should ask yourself as a designer is, "Am I taking advantage of the full potential of Appian Records?"

Appian records can bring together all data used within Appian into a collection of information through the form of lists and record views. This includes both integrated business data, such as customer information or payroll information, and process data, like support tickets created through an Action. Unlike traditional records, or the records in your database, Appian Records are a new type of record that allow you to see your business information from a number of different perspectives, and take action in the context of that information.

It might be helpful to review Using the Records Tab; seeing how others implement Appian Records can be a great way to find inspiration.

Record Definition

Records don't need to be defined entirely in the record type; keeping definitions in external objects can improve maintainability.

Save Record Configuration Expressions as Rules

Appian recommends saving any expressions created for a record type as a rule for version control and testing purposes. This also allows you to re-use the rules for a different record type.

Pass Record Data for Rules as Rule Inputs

The rf! and rp! domains are not available from within the rules management interface. This means that if you try to test a rule that references rf!, the rule will not evaluate. It is better to pass all of the record data the rule needs into the rule as inputs.

For instance, a rule for a Summary View should look like the following, where the getMyView rule defines one rule input each for the customerName, industry, and contactInfo field:

1
getMyView(rf!customerName, rf!industry, rf!contactInfo)

Create Constants for your Record Types

If you save your record type as a constant, you can use it as a parameter value for functions related to records, such as queryrecord() and urlforrecord().

See also: queryrecord(), urlforrecord(), and Constants

Record Performance

Like reports, records perform better when they're designed better.

Avoid Using Slow Expressions

When a user accesses the record list view, the record list view item template expression must evaluate for every record in the record list view before the list view can render.

Accessing the data you wish to display in the list view using rf! helps the expression execute faster than it would if the data were accessed by executing a query rule or otherwise looking up data. Appian recommends adding fields to your record for the data you wish to display in the list view rather than performing a look-up.

Record List View Design

The record list view is an equally important part of record design, as it's how users find the information they're looking for; a well-designed record list view can increase the value of your records.

Provide High-Resolution Images for Record Icons

Appian will automatically optimize the image for display on web and mobile clients that support a variety of screen resolutions and pixel densities. Manually reducing the source document size may result in certain users seeing low-quality icons with improper layout.

Use Distinct Images for Records

When selecting the document source for the records images, make sure it results in images that help users identify each record easily. For example, using a company's logo as the image for each record in a Companies record type helps the user find a company by glancing at the record list view. Using the same generic icon for all listed companies would not. Similarly, you should not use a user object for the record list view image unless that record represents the person or is very strongly tied to that person.

Create a Default Filter for Deleted Records

If the source has existing instances that are flagged as deleted (such as rows of the data store entity or processes of the process model), consider creating a default filter to hide them from the record list view.

Create User Filters to Show Additional Records

Up to 100 records display in a list view. If the number of records for a record type exceeds 100, create simple alphabetical user filters so that each option displays up to 100 records. If using the grid-style list, users will be able to page to see more data.

Record Usability

When users visit the Records tab, they'll be primarily focused on finding a particular record and specific information that pertains to it. Follow the best practices below to make it easiest for users to scan through your records.

Use Appropriate Column Layouts for Record View Content

To create visually-balanced record views, it is recommended to use the same layout (one-column or two-column) for all sections. Two-column layouts provide greater density for short text values, smaller charts, and grids. One-column layouts provide additional space to show longer paragraphs of text, as well as charts and grids that contain more data points. A one-column layout is recommended for grids that include more than 5 columns and/or lengthy text content. Charts that show more than 7 data points are generally best-shown in one-column layouts.

When including multiple sections on a record view, make sure that the height of content in each column of two-column sections is similar in order to minimize white space.

When mixing different layouts on the same record view, it is preferable to place a one-column section above a two-column section; this reduces the likelihood of a shorter column creating empty space above the start of the next section. An example of an effective mixed-layout record view is a grid in a one-column section above a two-column section containing a variety of brief text and number data values.

Keep Label Text Short

Use concise labels to describe record view fields. Most of the space within the record view should be used to show data values; avoid having verbose labels distract from content. If detailed description of a value is needed for proper comprehension, provide instruction text instead of a lengthy label.

Use Sections to Organize Content

Group related fields into sections described by concise labels. This helps users to scan record views to find relevant information and also reduces the need for redundant text in field labels.

Record-List View Usability

The following suggestions apply only to the record list view.

Make Sure Record Titles are Unique

Adding repetitive prefixes, such as categories, to record titles only adds noise to the record title and doesn't help users locate the specific record they're looking for.

Keep Record Titles Concise

Long titles, especially those wrapping onto multiple lines for mobile applications, make it harder for users to quickly browse through the titles.

Avoid Using Complex Expressions For Record Titles

If record titles are defined by complex expressions that evaluate differently for one user over another or include metadata (such as a priority level or task count), it makes it difficult for users to discuss or search for the same record without confusion over the title. Specific functions to avoid include loggedinuser() and if().

Define Concise Record Descriptions to Make Record Lists Easy to Scan

Long, paragraph-style, descriptions will reduce the number of records that are visible on the screen at the same time. They are also harder to read when quickly scanning down the record list than either a shorter sentence-style description or a series of label/value pairs separated by line breaks.

Specify a Timestamp Only When it is Intuitive and Useful

The timestamp for records on a record list view is optional. Since the timestamp is not labeled, one should only be shown if users are likely to understand its meaning without further explanation (for example, when an event represented by the record occurred). If there is a requirement to show timestamps which require explanation, include them on the record views where they can be shown with explicit labels.

See Also

  • Using the Records Tab: Provides instructions on how to use Records as a user.

  • Create a Record Type: Provides instructions on how to create a record type for your application.

  • Record Types: Provides you detailed design information.

  • Records Tutorial: Walks you through an example of creating your first record.

  • Interface Tutorial: Walks you through an example of creating your first interface, which is the basis of a record view.

  • Interface Components: Lists the supported interface components and the data structure required for adding them to a record view.

FEEDBACK