Event History List (a!eventHistoryListField)

Grids and Lists

Event History List

Function

a!eventHistoryListField( label, labelPosition, instructions, helpTooltip, emptyListMessage, eventData, eventStyle, formatTimestamp, displayUser, displayUserColorScheme, previewListPageSize, pageSize, showWhen, refreshAlways, refreshAfter, refreshInterval, refreshOnReferencedVarChange, refreshOnVarChange, userFilters, eventFilters, CollapseDetailsByDefault, showSearchBox, showReverseSortButton )

Displays the event history for one or more record types. If you configured record events on your record type, we recommend using the Event History record type to populate this list.

Parameters

Name	Keyword	Types	Description
Label	`label`	Text	Text to display as the list label.
Label Position	`labelPosition`	Text	Determines where the label appears. Valid values: `ABOVE` (default) Displays the label above the component. `ADJACENT` Displays the label to the left of the component. `COLLAPSED` Hides the label. The label will still be read by screen readers; see accessibility considerations for more information. `JUSTIFIED` Aligns the label alongside the component starting at the edge of the page.
Instructions	`instructions`	Text	Supplemental text about this list.
Help Tooltip	`helpTooltip`	Text	Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is `"COLLAPSED"`.
Empty List Message	`emptyListMessage`	Text	Text to display in the list when no data is available. Default is `"No events to display"`.
Event Data	`eventData`	List of Event Data	The record event data that populates the list, created using one or more instances of a!eventData().
Event Style	`eventStyle`	Text	Determines how the component displays. Valid values include: `"PREVIEW_LIST"` (default), `"FULL_LIST"`, `"TIMELINE"`. The `"PREVIEW_LIST"` and `"FULL_LIST"` styles are sometimes referred to collectively as the "list styles." See the UX Design System for best practices on when to use which style.
Date Display	`formatTimestamp`	Text	Determines how the component formats the event data timestamp. Valid values include: `"NULL"`, `"DATE"`, `"DATE_TIME"` (default), `“DATE_TIME_TIMEZONE”`.
User Image Style	`displayUser`	Text	Determines if and how to display user avatars. Valid values include: `"NONE"`, `"INITIALS"` (default), `"IMAGE"`.
User Color Scheme	`displayUserColorScheme`	Any Type	If no profile picture is available, determines which color scheme to use for users in the event history list. Valid values: `"PARACHUTE"` (default), `"VIBRANT"`, `"CLASSIC"` or define a custom color scheme using a!colorSchemeCustom(). See Chart Color Scheme for color scheme examples.
Preview List Page Size	`previewListPageSize`	Number (Integer)	The maximum number of rows to display in each page of the initial list when the `"PREVIEW_LIST"` event style is selected. To set the paging for the View All dialog, see pageSize. Valid values include 1-10. Default: 5.
Page Size	`pageSize`	Number (Integer)	The maximum number of rows to display in each page of the list when the `"FULL_LIST"` or `"TIMELINE"` event style is selected. When the `"PREVIEW_LIST"` event style is selected, this parameter applies to the list as it appears in the View More dialog. Valid values include 1-100. Default: 10.
Visibility	`showWhen`	Boolean	Determines whether the component is displayed on the interface. When set to `false`, the component is hidden and is not evaluated. Default: `true`.
Refresh after each user interaction	`refreshAlways`	Boolean	When true, eventData will be refreshed after each user interaction and each interval refresh. Default: `false`.
Refresh after record action completes	`refreshAfter`	List of Text String	Refreshes eventData data each time a specified action completes. Valid values: `"RECORD_ACTION"`.
Refresh after an interval of time	`refreshInterval`	Number (Decimal)	How often grid data gets refreshed in minutes. When null, eventData will not be refreshed on an interval. Valid values: `"0.5"`, `"1"`, `"2"`, `"3"`, `"4"`, `"5"`, `"10"`, `"30"`, and `"60"`.
Refresh after referenced variable changes	`refreshOnReferencedVarChange`	Boolean	When true, grid data will be refreshed each time the value of any variable referenced in the eventData parameter is updated. To refresh grid data when another variable that is not used in the eventData parameter changes, use refreshOnVarChange. Default: `true`.
Refresh after variable changes	`refreshOnVarChange`	Any Type	Refreshes data each time any of these specific variables change. This allows you to refresh the data when a variable that is not referenced in the eventData parameter is updated. You can define a single variable (for example, `refreshOnVarChange: local!var1`) or a list of variables (for example, `refreshOnVarChange: {local!var1, local!var2}`).
User Filters	`userFilters`	List of Variant	List of user filter references to display, configured using the `recordType!` domain. For example, `recordType!Order.filters.status`. You may only reference user filters defined on the record type used for the eventData. This parameter only applies when there is only one instance of a!eventData().
Component Filters	`eventFilters`	List of Text	Determines which out-of-the-box filters to show. These filters exist only on the component, not on the record type. Use any combination of the following values {`"USER"`, `"EVENT_TYPE"`, `"DATE_RANGE"`}.
Initially collapse event details	`CollapseDetailsByDefault`	Boolean	Determines if the event details are collapsed when the interface first loads. Default: `true`.
Show search box	`showSearchBox`	Boolean	Determines if the record search box should be shown. Default: `true`.
Show reverse sort button	`showReverseSortButton`	Boolean	Determines if the list should include a button to reverse the event data sort. Default: `true`.

Usage considerations

Using the eventStyle parameter

The eventStyle parameter allows you to display your event history using three different styles:

Style	Description
`"PREVIEW_LIST"`	Displays a short list of events with the ability to view all events in a dialog. The dialog will display a longer list of events that users can search and filter on. This option is best when you want to display your event history in a record view or alongside other components. Note that you cannot use this style when the component displays in a dialog.
`"FULL_LIST"`	Displays a long list of events that users can search and filter on. This option is best when you want to display your event history as a single page in a site.
`"TIMELINE"`	Displays a timeline of events where events are organized by the timestamp field. This option is best if you want to analyze events based on time rather than event type.

Examples

The following examples illustrate how to configure different styles of the event history list component.

Record type object references are specific to each environment. If you copy and paste these examples into your interface, they will not evaluate. Use them as a references only.

Preview list of events

The expression looks like this:

a!eventHistoryListField(
    label: "Event History Preview List",
    labelPosition: "COLLAPSED",
    eventData: {
      a!eventData(
        recordType: recordType!Order Event History,
        filters: null,
        timestamp: recordType!Order Event History.fields.timestamp,
        user: recordType!Order Event History.fields.user,
        eventTypeName: fv!data[recordType!Order Event History.relationships.eventType.fields.eventName],
        details: if(
          isNullOrEmpty(fv!data[recordType!Order Event History.fields.details]),
          "No additional details",
          fv!data[recordType!Order Event History.fields.details]
        ),
        recordTypeForTag: recordType!Order,
        recordIdentifier: recordType!Order Event History.fields.recordId
      )
    },
    refreshAfter: "RECORD_ACTION",
    eventStyle: "PREVIEW_LIST",
    previewListPageSize: 5,
    pageSize: 10,
    formatTimestamp: "DATE_TIME",
    collapseDetailsByDefault: false,
    displayUser: "IMAGE",
    showSearchBox: true,
    eventFilters: { "EVENT_TYPE", "DATE_RANGE" },
    showReverseSortButton: true
  )

Full list of events

The expression looks like this:

a!eventHistoryListField(
    label: "Event History Full List",
    labelPosition: "COLLAPSED",
    eventData: {
      a!eventData(
        recordType: recordType!Order Event History,
        filters: null,
        timestamp: recordType!Order Event History.fields.timestamp,
        user: recordType!Order Event History.fields.user,
        eventTypeName: fv!data[recordType!Order Event History.relationships.eventType.fields.eventName],
        details: if(
          isNullOrEmpty(fv!data[recordType!Order Event History.fields.details]),
          "No additional details",
          fv!data[recordType!Order Event History.fields.details]
        ),
        recordTypeForTag: recordType!Order,
        recordIdentifier: recordType!Order Event History.fields.recordId
      )
    },
    refreshAfter: "RECORD_ACTION",
    eventStyle: "FULL_LIST",
    pageSize: 10,
    formatTimestamp: "DATE_TIME",
    collapseDetailsByDefault: true,
    displayUser: "IMAGE",
    showSearchBox: true,
    eventFilters: { "EVENT_TYPE", "DATE_RANGE" },
    showReverseSortButton: true
  )

Timeline of events

The expression looks like this:

a!eventHistoryListField(
    label: "Event History Timeline",
    labelPosition: "COLLAPSED",
    eventData: {
      a!eventData(
        recordType: recordType!Order Event History,
        filters: null,
        timestamp: recordType!Order Event History.fields.timestamp,
        user: recordType!Order Event History.fields.user,
        eventTypeName: fv!data[recordType!Order Event History.relationships.eventType.fields.eventName],
        recordTypeForTag: recordType!Order,
        recordIdentifier: recordType!Order Event History.fields.recordId
      )
    },
    refreshAfter: "RECORD_ACTION",
    eventStyle: "TIMELINE",
    previewListPageSize: 5,
    pageSize: 5,
    formatTimestamp: "DATE_TIME",
    collapseDetailsByDefault: true,
    displayUser: "IMAGE",
    showSearchBox: true,
    eventFilters: { "EVENT_TYPE", "DATE_RANGE" },
    showReverseSortButton: true
  )

Feature compatibility

The table below lists this SAIL component's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Incompatible
Offline Mobile	Incompatible
Sync-Time Custom Record Fields	Incompatible
Real-Time Custom Record Fields	Incompatible	Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.
Process Reports	Incompatible	Cannot be used to configure a process report.
Process Events	Incompatible	Cannot be used to configure a process event node, such as a start event or timer event.

Open in Github Built: Mon, Apr 29, 2024 (04:15:21 PM)

Event History List