Configure Charts 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 using one of two methods:

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

If the source of your chart is a record type that uses a database as the source, or a record type that has sync enabled, use the record type in the configuration. Once you select the record type, it's easy to reference each field in the chart's labels or calculations.

If the source of your chart is not a record type, or you need to perform advanced calculations or manipulations on the data prior to displaying it on your chart (e.g. calculate a running sum after querying the results), use the categories and series parameters to construct the chart using an expression. See examples for configuring charts using categories and series directly in the component pages for Bar, Column, Line, and Pie charts.

To easily configure your charts, Appian recommends using a record type as the source. To configure a chart to use record data, you will:

Configure a chart to use record data

Appian makes it quick and easy to select a record type as the source of your chart. Simply choose Record Type as the source of your data and search for your record type. The selected record type determines which fields are available to display on the chart.

Once you select the source, there are two key configurations needed to display your record data: groupings and a measure. The combination of these configurations determine what data to query from the record type and how to display the results on the chart.

To configure a chart to use a record type as its source:

  1. On an interface, drag and drop one of the four chart types (Bar, Column, Line, or Pie) from the PALETTE.
  2. From Data Source, select RECORD TYPE and search for your record type.
  3. Click FILTER RECORDS to apply any filters if necessary.
  4. Use the Primary Grouping and Secondary Grouping fields to configure the chart's groupings.
  5. Use the Measure field to determines how to calculate the values of a field in a chart.
  6. Use the Sort and Data Limit fields to define how the chart sorts and displays the record data.

Depending on the chart you choose, you can configure additional chart properties like X-Axis and Y-Axis Titles, Reference Lines, Color Scheme, and more.

/chart design view

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.

Configure chart groupings

Groupings allow you to determine how the data is grouped together in the chart.

For example, say you have a record type of all open support cases and you want to see how many open cases are associated with each employee. You can use grouping to group open cases by employee.

Chart with one grouping

Depending on the type of chart you use, the way you group your data and the complexity of your groupings will vary:

  • Pie charts contain only one grouping: Primary 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

To configure a chart's groupings in Expression Mode, see the Grouping Component or the examples below.

Configure chart measures

A measure determines how to calculate the values of a field in a chart. A measure can calculate on any field in the record type, but it should usually be a numeric field.

For example, say you have a record type that lists all customer requests and you want to see how many requests have been marked as "Success", "Fail", or "Exception". You can use grouping to display requests by status and use measure to count the number of requests per status.

Chart measure

To configure a chart's measure:

  1. In Design Mode, select the chart component.
  2. Locate the Measure field on the chart's Component Configuration.
  3. Select a record field to perform a calculation on.
  4. Use the dropdown to choose the type of calculation to perform on the selected record field.
  5. Click the edit icon next to Measure to change the measure's label or create an alias for the results of the measure field. An alias can be used to reference a field used in sorting or a link.

Bar, column, and line charts can display multiple measures if no Secondary Grouping field is provided. When multiple measures display on a chart, each measure displays in chronological order on the chart and legend, and is assigned a different color based on the color scheme.

To configure a chart's measure in Expression Mode, see the Measure Component or the examples below.

A link in a chart can be used to drill down into a grid, or filter other components on an interface. Chart links consist of a dynamic link and the variable fv!selection that contains the current selected values.

The fv!selection variable returns a map with all information about the current selected item, which allows you to dynamically pass chart data. To save the current selected values, you'll create a local variable to store the values.

For example, suppose you have the following stacked column chart that displays a count of restaurants by region and type:

/drilling_link

In Expression Mode, you'll see that the chart's link parameter is pre-populated with the a!dynamicLink() function, and the value parameter contains fv!selection.

To dynamically save the current selected values, you'll add a local variable, like local!selectedItem, and use it in the saveInto parameter:

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
a!localVariables(
  local!selectedItem,
  {
    a!columnChartField(
      data: recordType!Restaurants,
      config: a!columnChartConfig(
        primaryGrouping: a!grouping(
          field: recordType!Restaurants.fields.region,
          alias: "region"
        ),
        secondaryGrouping: a!grouping(
          field: recordType!Restaurants.fields.type,
          alias: "type"
        ),
        measures: a!measure(
          field: recordType!Restaurants.fields.id,
          function: "COUNT",
          alias: "id_count"
        ),
        link: a!dynamicLink(
          value: fv!selection,
          saveInto: local!selectedItem
        )
      )
    )
  }
)

Now, when you select the bar chart shown above, the following data is saved to the local variable:

/drilling_link2

Notice that the data that is saved depends on the alias defined for each field. If you add a drilling link, the alias field is required. To add an alias, click the edit icon next to Measure and enter a value in the Alias field.

Additionally, the saved value is always the unformatted result. For instance, suppose the Primary Grouping field is a boolean type, but the chart displays as Yes or No using the formatValue parameter. When using a link, the data in fv!selection for that field will be a boolean instead of a text.

Once you store the currently selected chart data to a local variable, it's easy to use the selection for filtering, drilling, or other interactions on the page. See the recipe on how to configure a chart drilldown to a grid for an example on how to use the selection.

Configure the 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.

To limit the batch size, enter a value in the Data Limit field of the chart's Component Configuration. 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, if you want a chart to display the top 10 products by their sales, the limit of 10 will return the correct results. The data limit also determines the combination of groupings. So, if 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 5,000 when using multiple groupings.

To sort the record data in the chart, use the Sort field of the chart's Component Configuration. 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.

When configuring the sort, 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 or an alias.

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 type that contains a list of sales made for each product. A pie chart is a great way to view the contributions made by each product area.

Since the product area displays on each slice of the pie, this should be configured as the grouping field. The sales determine the size of each pie slice, so we should configure the measure as the sum of salesRevenue.

In Design Mode, 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.

Since employees in each region have the same type of roles, we will use the region field as the Primary Grouping value. This is the value that will display on the axis of the chart. We'll use the role field as the Secondary Grouping, so the field labels display as stacked columns in the chart.

To configure this chart in Design Mode:

  1. Set Primary Grouping to region.
  2. Set Secondary Grouping to role.
  3. Set Measure as Count of id.
  4. Click FILTER RECORDS to filter the record data to only display active employees.

stacked column 1

In Expression Mode, we can provide the key fields in the data and config parameters (along with some other basic visual properties). To display only the active employees, we'll use a!recordData() to create a filter.

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

Bar chart with formatted values

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. Using the status ID as the grouping field would display on the chart like this:

/chart with statusId

To display the status labels instead, we can add an expression to the formatValue parameter of a!grouping():

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

Open in Github Built: Thu, Feb 23, 2023 (02:59:22 PM)

On This Page

FEEDBACK