Record Design

Overview

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

See the record tutorials on the Tutorials page to walk through an example of creating your first record.

Record purpose

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

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. Appian Records allow you to bring all of your data together in the form of configurable record lists and record views and allow users to take action in the context of that information. This includes both integrated business data, such as customer information or payroll information, and process data, like support tickets created through an record action.

See Using the Records Tab to see examples of how others implement Appian Records and find your own 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 as rule inputs

The rv! domain is not available outside of the record type. This means that if you try to pull in record data into an interface using rv!, the interface will not evaluate. It is better to pass all of the record data into the interface as a rule input.

For instance, a summary view should have a record type as a rule input and use record type field references with the rule input as the Value of each interface component.

In an interface that is using the Employee record type, it should look like this:

1
2
3
4
5
a!textField(
    label: "First Name",
    labelPosition: "ADJACENT",
    value: ri!Employee[recordType!Employee.fields.firstName],
    readOnly: true

Reference a record type from an expression

Record types are referenced using the recordType! domain and <record name>, as shown below.

record type employee lozenge

Use the recordType! domain to reference a specific record type in the a!gridField() function's data parameter, and the recordType parameter for the a!recordData(), a!queryRecordType(), and urlforrecord() functions. See Appian Functions for more information on functions that reference a record type.

You can then use dot notation to append .fields to the record type object reference and reference a record field or a record action in your expression. There's no need to remember your record fields, pull up your CDT, or open the record type to determine which fields you want to reference. The expression editor uses a type ahead to suggest existing fields associated with your record type. This also applies to other record features, such as field, action or filter.

Although you can still use a constant to reference your record type in record-related functions, in most cases, the recordType! domain eliminates the need to create this additional object.

See [a!queryRecordType()][fnc_system_queryRecordType.md], urlforrecord(), and a!recordData() for more information.

Record performance

Records are one of the most important pillars of your applications. With guided configuration, built-in component support, the ability to sync your record data in Appian, and quickly pull your record data into a read-only grid, record type objects are easier than ever to design and optimize for performance.

All considerations for optimizing interface performance also apply to optimizing record performance. However, a record type has additional configurations that can affect how a record UI will perform.

Attributes that affect record list performance:

  • Grid or feed list interface definition
  • Generating user filters and their options
  • Evaluating the default filter
  • Querying for your records

Attributes that affect record view performance:

  • The view's interface definition
  • Calculating visibility of the other available record views
  • Calculating visibility of related action shortcuts
  • Querying for the record data
  • Evaluating the record's title

You can visualize the performance breakdown of your record type UIs by navigating to the Performance page while configuring your record type.

/record performance page

Record list view design

Providing an easy way to users to browse the record data is important. The record list allows you to configure the columns you want to display, the user filters, how you want the data sorted, and much more. Not only can you add the record list to a site page, but your record list configurations are used as the default configurations when displaying your data in the read-only grid.

See Read-Only Grid Component for more information.

Define the number of rows per page

You can easily set the number of rows of data you want to display on each page of the grid by defining an integer value in Rows to Display Per Page.

/Create Record Type/create a record data grid paging

In the image shown above, the value is set to 10, meaning only 10 rows of record data will display on each page of the grid.

Define how the record data sorts

The grid-style record list allows you to define two sort parameters: initial sorts and secondary sorts. One determines how the data is ordered when the record list initially loads in the grid and the other determines how the data is ordered after the user interactions with the grid. Note that you can define multiple initial sorts and secondary sorts to apply to your grid.

The initial sorts parameter defines how the grid data is sorted when it first loads.

/Create Record Type/create a record data grid configure initial sorts

You'll select a record field to sort on and a sort order.

/Create Record Type/create a record data grid configure initial sorts field

The secondary sorts parameter defines how the grid data is ordered after the user clicks a column in a grid. Similar to the initial sorts, you will also define the sort field and order for this parameter.

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 data source for your records has existing rows 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 a different record sets

When you use the read-only grid to pull the record list into your interface, the grid will display the record set returned by the record list configuration in your record type. If you want the grid to return a different set of records, you can use the filter editor to create a filter that returns the records you want the grid to display.

See Configuring the Read-Only Grid for more information.

User filters for service-backed record types created using Appian 20.3 are not configured in the same way. You can configure and handle filters for these record types using the record data source expression

Record usability

When users visit the Records tab, they'll be primarily focused on finding a particular record type and viewing specific information that pertains to it. Follow the best practices below to ensure users can easily 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 will help users quickly 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 record 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 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 type.

  • 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.

Open in Github Built: Fri, Nov 12, 2021 (02:44:06 PM)

On This Page

FEEDBACK