Record Knowledge Graph Component

Displays a record and its related records as an interactive knowledge graph.

The record knowledge graph component renders a visual diagram starting from a single record (such as a Customer named "Amelia Richardson") and shows configured related data, like the customer's orders, their status, and the order priority. End users can search across the graph, zoom in and out of relationship levels, and click records to explore their connections.

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

Where to use the record knowledge graph component

Use a!recordKnowledgeGraph() in the following components:

• Top-level layouts:
  • a!formLayout(): contents parameter.
  • a!headerContentLayout(): contents parameter, or in the header parameter (inside a!cardLayout()).
  • a!pane(): contents parameter (inside a!paneLayout()).
  • a!wizardStep(): contents parameter (inside a!wizardLayout()).
• Layout:
  • a!boxLayout(): contents parameter.
  • a!cardLayout(): contents parameter.
  • a!columnLayout(): contents parameter (inside a!columnsLayout()).
  • a!sectionLayout(): contents parameter.
  • a!tabItem(): contents parameter (inside a!tabLayout()).
  • a!sideBySideItem(): item parameter (inside a!sideBySideLayout()).
• Subcomponents:
  • a!sidebarTemplate(): additionalContents parameter (inside a!formLayout() or a!wizardLayout()).
  • a!barOverlay(): contents parameter (inside a!billboardLayout()).
  • a!columnOverlay(): contents parameter (inside a!billboardLayout()).
  • a!fullOverlay(): contents parameter (inside a!billboardLayout()).

You can't use a!recordKnowledgeGraph() in the following components:

• Read-only grid (a!gridField())
• Editable grid (a!gridLayout())
• Chat message (a!chatMessage()).
• Billboard Layout (a!billboardLayout())

Parameters

a!recordKnowledgeGraph( recordType, recordIdentifier, enableLevelSlider, label, labelPosition, helpTooltip, accessibilityText, marginAbove, marginBelow, relationshipLevel, excludedRelatedRecords, includedRelatedRecords, showWhen, height, showMiniMap, selectionSaveInto )

Using the record knowledge graph component

The following sections cover important details about configuring and using the record knowledge graph component.

Record type requirements

The recordType parameter must reference a record type using the recordType! domain (for example, recordType!Customer).

The record knowledge graph component supports both synced and unsynced record types. Legacy record types are not supported because they do not support record type relationships.

Record names in the graph

The base record and any related records display two elements:

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

• Record type display name: Shown as secondary text. The display name based on the configuration in the record type's Properties.
• Record title: Shown in bold and populated based on the record title configuration.

Configure a meaningful record title and display name on each record type so records are easy to identify in the graph.

Related record display limit

The record knowledge graph component can display a maximum of 500 related records. If a record has many relationships across multiple levels, the record knowledge graph may reach this limit.

To avoid exceeding the 500-record limit, you can:

• Reduce the relationshipLevel parameter to a lower value.
• Use the excludedRelatedRecords parameter to omit certain related records from the diagram.

Control which records appear in the graph

By default, the record knowledge graph component displays all related records up to three relationship levels deep.

You can control which records appear using different parameters:

• Change the relationship depth: Set the relationshipLevel parameter to control how many levels of relationships the component traverses from the base record type. By default, the value is 3. The relationshipLevel value also sets the maximum depth for the relationship level slider.
• Hide specific relationships: Use the excludedRelatedRecords parameter to remove relationships you don't want to show.
• Highlight specific relationships: Use the includedRelatedRecords parameter to show only certain related records. When configured, the graph displays the specified related records and any intermediate records needed to connect the base record to each specified record. The relationshipLevel parameter determines how far the graph extends. If you specify a record type that is not related to the base record type within the configured relationship level, only the base record displays.

Using the relationshipLevels parameter

Each relationship level represents one "hop" from the base record type through its configured relationships. A relationshipLevel value of 1 shows only the record types directly related to the base record type. A value of 2 adds the relationships configured on those related record types, and so on, up to a maximum of 10.

The relationshipLevel parameter also sets the maximum depth for the relationship level slider. The relationshipLevel value defines how deep the graph can go, and the enableLevelSlider parameter determines if end users can adjust the relationship levels displayed in the graph.

The following example illustrates how relationship levels map to a data model in the record knowledge graph, starting from the RE Order record type:

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

Include or exclude related records

The excludedRelatedRecords and includedRelatedRecords parameters accept either a record type reference (recordType!RE Order) or a relationship reference (recordType!RE Customer.relationships.order).

Use a relationship reference to exclude related records directly related to the base record type. Use a record type reference to omit related records from a nested relationship.

Using the enableLevelSlider parameter

The enableLevelSlider parameter controls whether end users can interactively explore different relationship depths in the record knowledge graph.

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

• When enableLevelSlider is true: The graph renders at depth 1 on initial load, hiding deeper relationships. Users adjust the slider to expand up to the configured relationshipLevel value.
• When enableLevelSlider is false (default): The graph renders all levels up to the configured relationshipLevel on initial load.

Using the selectionSaveInto parameter

The selectionSaveInto parameter lets you capture information about a record when a user clicks one in the graph. You can use the record information to pass the data to another component or process, such as displaying record details in a side panel. See Save a selection to display record details for an example.

To use this parameter, create a local variable in your interface to store the selected record's information. Then, configure the value of the selectionSaveInto parameter to use your local variable.

You can index into the following properties of the local variable to access individual record details:

Using the showMiniMap parameter

By default, the showMiniMap parameter is true, so a small satellite view of the record knowledge graph appears at the bottom of the component. The mini map helps users orient themselves as they pan and zoom through the graph.

Consider the complexity of your graph when deciding whether to show the mini map:

• Show the mini map (default) when the graph displays multiple relationship levels, many related records, or is placed in a tall container where users are likely to pan and zoom.
• Hide the mini map when the graph is small or simple enough that all records fit in view without panning, or when screen space is limited and you want to maximize the area dedicated to the graph itself.

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

End-user interactions

The record knowledge graph provides several interactive features that let end users explore the graph without additional developer configuration.

Grouped one-to-many records

When a one-to-many relationship produces more than one related record, the record knowledge graph automatically groups them into a single visual element.

Each group displays up to 10 records by default. End users can view additional records, search within a group, and select individual records to explore their relationships on the graph or see their summary view.

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

The excludedRelatedRecords and includedRelatedRecords parameters affect which records appear in groups. If a related record type is excluded, records of that type do not appear. If includedRelatedRecords is configured, only records of the included types appear.

Search records in the graph

The record knowledge graph provides two levels of search:

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

View a record summary

End users can click the icon on a record in the graph to view its summary view. The summary view option is only available if the record type has a summary view configured.

For records in a one-to-many group, the user must first select a record from the group so it displays as its own record in the graph. The icon is then available on the selected record.

Appian Mobile considerations

The record knowledge graph component is not supported in Appian Mobile. If you include a!recordKnowledgeGraph() in an interface displayed on Appian Mobile, the component does not render.

Examples

The following examples demonstrate the record knowledge graph component.

These examples illustrate how data displays in the record knowledge graph using the following data model:

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

In each example, the recordIdentifier is provided by a rule input (ri!customer), which points to a specific record in the AT Customer record type.

These examples reference record types from a different environment and will error if you try to use them in yours. Use them as a reference only.

Show one level of related records

This example displays all the related records from the relationships configured on the base record type (AT Customer).

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

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  a!recordKnowledgeGraph(
    label: "Customer Relationships",
    recordType: recordType!AT Customer,
    recordIdentifier: ri!customer[recordType!AT Customer.fields.id],
    /* Only displays related data from the */
    /* relationships configured on AT Customer */
    relationshipLevel: 1,
    showMiniMap: false,
    enableLevelSlider: false,
    height: "MEDIUM"
  )
}

Exclude specific related records

This example displays all the related records from the relationships configured on the base record type (AT Customer), but excludes the AT Customer Event History record type so it doesn't appear in the record knowledge graph.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  a!recordKnowledgeGraph(
    label: "Customer Relationships",
    recordType: recordType!AT Customer,
    recordIdentifier: ri!customer[recordType!AT Customer.fields.id],
    /* Only displays related data from the */
    /* relationships configured on AT Customer */
    relationshipLevel: 1,
    /* Removes record type from the graph */
    excludedRelatedRecords: {
      recordType!AT Customer.relationships.eventHistory,
    },
    showMiniMap: false,
    enableLevelSlider: false,
    height: "MEDIUM"
  )
}

Include only specific related records

This example displays only the orders related to the customer. Any other related records, like industry and event history, are not displayed on the graph because they are not explicitly referenced in the includedRelatedRecords parameter.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  a!recordKnowledgeGraph(
    label: "Related Customer Data",
    labelPosition: "COLLAPSED",
    recordType: recordType!AT Customer,
    recordIdentifier: ri!customer[recordType!AT Customer.fields.id],
    relationshipLevel: 1,
    /* Only displays related orders from the */
    /* relationship configured on AT Customer */
    includedRelatedRecords: {
      recordType!AT Customer.relationships.orders,
    },
    showMiniMap: false,
    enableLevelSlider: false,
    height: "MEDIUM"
  )
}

Save a selection to display record details

This example uses the selectionSaveInto parameter to capture the clicked record's information and display the record details in a side panel next to the graph.

This example also uses the enableLevelSlider parameter to render the record knowledge graph at depth 1 on initial load. Users can expand relationship levels interactively using the depth control slider, up to the configured relationshipLevel value of 4.

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

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  a!localVariables(
    local!selectedRecord,
    a!columnsLayout(
      columns: {
        a!columnLayout(
          contents: {
            a!recordKnowledgeGraph(
              label: "Customer Relationships",
              labelPosition: "COLLAPSED",
              recordType: recordType!AT Customer,
              recordIdentifier: ri!customer[recordType!AT Customer.fields.id],
              relationshipLevel: 4,
              excludedRelatedRecords: {
                recordType!AT Customer.relationships.eventHistory
              },
              /* Saves the clicked record's information */
              /* into a local variable */
              selectionSaveInto: local!selectedRecord,
              height: "TALL",
              /* Starts the graph at depth 1 so users */
              /* can expand levels using the slider */
              enableLevelSlider: true,
            )
          }
        ),
        a!columnLayout(
          width: "NARROW_PLUS",
          contents: {
            a!sectionLayout(
              label: "Selected Record Details",
              contents: {
                if(
                  a!isNullOrEmpty(local!selectedRecord),
                  a!richTextDisplayField(
                    labelPosition: "COLLAPSED",
                    value: a!richTextItem(
                      text: "Click a record in the graph to view its details.",
                      style: "EMPHASIS"
                    )
                  ),
                  {
                    a!textField(
                      label: "Record Type",
                      value: local!selectedRecord.recordTypePluralName,
                      readOnly: true
                    ),
                    a!textField(
                      label: "Record Name",
                      value: local!selectedRecord.recordTitle,
                      readOnly: true
                    ),
                    a!textField(
                      label: "Record Identifier",
                      value: local!selectedRecord.recordIdentifier,
                      readOnly: true
                    )
                  }
                )
              }
            )
          }
        )
      }
    )
  )
}

Feature compatibility

Feedback