Chart Configuration Using Records

This page explains how to configure a chart that uses a record type as its source.

Overview

Charts in Appian can be configured in one of two different methods:

  1. Define a record type as the source and select fields to display on the chart
  2. Provide a list of data directly to categories and series parameters

If the source of data for the chart is an entity-backed or synced record type, we recommend directly using the record type in the configuration. Once you select the record type, it's easy to reference each field that should display in the labels or calculations in the chart.

In some cases, you may want to display a chart that doesn't use record data. In this case, use the categories and series to construct the chart using an expression. Also, if you need to configure a link on the cart or apply multiple measurements, these configurations are not supported on charts with a record as the source, so use the configuration using categories and series.

Chart Configuration with Records

Configuring a chart with records involves two key parameters: the data and the field configuration. The combination of these parameters determine what data to query from the source and how to display the results on the chart. Keep in mind that when using records as a source, you don't need to build any query or expression to return the data displayed on the chart. Instead, just provide the fields to display and Appian will do the rest.

At a high level, here's the basic steps to configure a chart using records data:

  1. To get started, drag one of the four chart types (Bar, Column, Line, or Pie) from the palette.
  2. Select the record type as the source for the chart and provide any filters if necessary.
  3. Select fields for grouping and measure to define which data to display on the chart.
  4. Define any additional display properties on the chart

/chart design view

We'll dive into each of these areas in more detail below to describe the key terminology and guidance for creating advanced charts.

Data

When creating a chart using records data, start by selecting the appropriate record type as the source data.

Charts Record Source Data

The record type defined in the data determines which fields are available to display on the chart. Once you select a source record type, you can also define a filter to narrow down the results displayed on the chart.

If you use expression mode, the data parameter can accept either a record type reference or the function a!recordData. If you want to provide filters, use a!recordData to provide both the record type and filters.

Key Concepts

Once you select a source record type, fields will auto-populate in design view for the primary grouping and the measure. Each of these parameters define a key aspect of the design for your chart.

Groupings

The groupings are used to define configurations for how the data should be grouped into unique distributions. The grouping itself contains a reference to a field to group by and some additional information that determines how to display the results. The grouping fields most often represent the labels to compare against. For example, in the chart below, the primary grouping is the Technician.

Chart with one grouping

In each chart type, the grouping represents slightly different concepts. Also, some charts can support multiple groupings for more complex visualizations. See the image below for an example of using multiple groupings on a column chart.

  • Pie charts contain only one grouping. This grouping determines the labels for each slice of the pie chart.
  • Bar and column charts allow adding multiple groupings. If only the primary grouping is used, the chart displays a single series of data and the axis shows the labels of the grouping results. When a secondary grouping is added, the secondary grouping shows as stacked or grouped bars.
  • Line charts also support multiple groupings. Like bar and column charts, the primary grouping displays on the x-axis. We recommend using time series data for this grouping. A secondary grouping will show as multiple lines in a line chart.

Chart with one grouping

Measures

A measure determines the numerical results that are used to compare across the grouped values in the chart. The measure is important because it determines the relative size of each result on the chart. For example, in the chart below the measure is the count of requests, and the grouping is the status.

Chart measure

To configure a measure, you must provide both a field and a function to calculate the results for the measure. The field can be any field in the record type, but it should usually be a numeric field (except when using the COUNT function). The five functions available are COUNT, SUM, AVG, MIN, and MAX.

Data Limit and Sorting

In addition to the groupings and measures, charts that use a record type as a source contain options for setting a batch size and sorting. The data limit determines how many unique groupings are on the chart. The data limit is most useful when using a single grouping. For example, suppose you would like a chart to display the top 10 products by their sales. In this case, the limit of 10 will return the correct results. Keep in mind that the data limit determines the combination of groupings. So, both a primary and secondary grouping are used, a data limit of 100 would return a total of 100 values (10 primary grouping values x 10 secondary grouping values). For this reason, we recommend using the maximum limit of 5000 when using multiple groupings.

Sort is used to determine which values display first on the chart. Use a!sortInfo to define the field to sort by and whether to sort ascending or descending. To sort the chart, always select a field used in the groupings or measure. When multiple groupings are used, it usually makes the most sense to sort by the primary grouping field. The sort can reference either the record field reference for a field used elsewhere or an alias (see below for more information on aliases).

Detailed Field Configurations

There are also some configurations that apply directly to the measure or grouping fields defined. These configurations aren't available at the main level in design view; instead, drill down to the measure or grouping to view these additional configurations.

Grouping

  • The field refers to the record field to use in this grouping. It must be a field available on the source record type.
  • The alias is used to define a field name that can be used elsewhere in the chart. It's most useful when using a field name for sorting, since the alias can be used as the field name. In addition, an alias is necessary if the same field is used in multiple places.
  • Interval can be used with a date field to define a different date aggregation to group by. The two options available include "MONTH" and "YEAR". If the interval is "MONTH", the number for the month is returned.
  • Format Value is a parameter that enables you to manipulate the resulting value from the grouping before displaying it on the chart. This can be useful to define formatting for values like dates or numbers, or it can even pull in labels from reference data to display on the chart.

The format value works by using a variable called fv!value. This variable represents the raw response from the grouping; use the variable in any expression to further manipulate the result.

As an example with formatting, suppose the grouping field displayed on the chart is the status ID. The status labels exist in a constant, so the labels aren't available directly from the data source. Without using the formatValue, the chart might look like this:

/chart with statusId

To display the status labels instead, add the following expression to the formatValue parameter:

1
2
3
4
5
6
7
8
9
a!grouping(
  field: recordType!Cases.field.statusId,
  alias: "status",
  formatValue: index(
    cons!MY_APP_STATUS_LABELS /* Status labels available in a constant*/
    fv!value,
    "Unknown Status"
  )
)

Using the expression above, the chart will instead display like this:

/chart with status labels

Keep in mind that using the format value does not affect the grouping or measure values, it only updates the label displayed in the chart. Also, the format value needs the results of the field configured inside the chart to perform the calculation correctly, so you can't use the grouping function outside of a chart.

Measures

  • The field for a measure is similar to field in grouping; it refers to the field from the record type to use in the calculation. Like the grouping, the field here also must be from the source record type.
  • Measures also have an alias, which can also be used to reference a field used in sorting.
  • The function is used to determine what type of calculation to use for the measure result. This parameter can be selected either at the top level configuration for the chart or in the child configuration for a!measure(). The options available for function are "COUNT", "SUM", "MIN", "MAX", and "AVG".
  • The label can determine the label displayed in the legend or tooltip for the measure. If no label is provided, the default label displays with the internationalized function and field name, such as Count of id. The label does not apply when used with a secondary grouping, as the label is then determined by the secondary grouping field value. Also, the label does not apply when using a measure in a pie chart.

Examples

Let's look at a few examples to understand how to configure the chart to display in a variety of scenarios.

Pie Chart with Sales by Product Area

Suppose you have a record that contains a list of sales made for each product. A pie chart is a great way to view the contribution of each product area to the whole.

Since the product area displays on each slice of the pie, this should be configured as the grouping field. The sales determines the size of each pie slice, so we should configure the measure as the sum of salesRevenue. In design view, simply select the source record type and appropriate fields for grouping and measure.

/pie chart design view1

In expression mode, we can provide the key fields in the data and config parameters (along with some other basic visual properties).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
a!pieChartField(
  label: "Sales by Product Area",
  data: recordType!Sales,
  config: a!pieChartConfig(
    primaryGrouping: a!grouping(
      field: recordType!Sales.fields.productArea,
      alias: "productArea"
    ),
    measures: a!measure(
      function: "SUM",
      field: recordType!Sales.fields.salesRevenue,
      alias: "sum_salesRevenue"
    ),
    dataLimit: 100,
    sort: a!sortInfo(
      field: "sum_salesRevenue",
      ascending: false
    )
  ),
  labelPosition: "ABOVE",
  height: "SHORT",
  showDataLabels: true,
  showAsPercentage: true,
  seriesLabelStyle: "LEGEND",
  colorScheme: "RAINFOREST",
  style: "DONUT"
)

Here's the final pie chart:

/pie chart design view2

Stacked Column Chart of Employees

In this example, we'd like to count the number of employees in the company grouped by their region and role. Since this can best be displayed as a stacked chart, we'll need to use multiple groupings.

We should also only display active employees using a filter within a!recordData().

Here's the expression that defines this chart:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
a!columnChartField(
  data: a!recordData(
    recordType: recordType!Employee,
    filters: a!queryFilter(
      field: recordType!Employee.fields.status,
      operator: "=",
      value: true
    )
  ),
  config: a!columnChartConfig(
    primaryGrouping: a!grouping(
      field: recordType!Employee.fields.region,
      alias: "region"
    ),
    secondaryGrouping: a!grouping(
      field: recordType!Employee.fields.role,
      alias: "role"
    ),
    measures: a!measure(
      function: "COUNT",
      field: recordType!Employee.fields.id,
      alias: "id_count"
    ),
    dataLimit: 5000
  ),
  label: "Column Chart",
  stacking: "NORMAL",
  showLegend: true,
  showTooltips: true,
  colorScheme: "MIDNIGHT"
)

Here's what the chart looks like: /stacked column chart2

Open in Github

On This Page

FEEDBACK