This page describes how to configure record events, capture event data, and use that data to monitor and improve your business processes.
Your enterprise is built on key business processes. Whether it’s logging support cases, completing orders, or managing employees, keeping track of who does what and when can help you better understand your business and improve how it operates.
For example, in a retail application, you can construct a clear history of how orders are completed if you know who created, updated, or shipped each order and when. Then, you can answer critical questions like: Which activities were completed on a given order and by whom? How long does it take to complete an order on average? Which order activities take the longest: creating, updating, or shipping?
That’s where record events come in. Record events allow you to seamlessly track which user or automation takes action on your records and when, with minimal configuration on your part. You can use record events to generate and capture data about your business processes within your standard Appian workflows. Then, you can easily surface that history for analysis—or even better, leverage our process mining capabilities to identify actionable insights to improve your processes.
To configure and use events in your applications:
You can configure record events on any record type that uses a database as the source and has data sync enabled.
To configure record events, you will specify two record types to store your event information:
Event History: The record type used to store who completed an event and when. For example, John Smith created order SO1234 on February 28, 2023.
Event Type Lookup: The record type used to store the different types of events that can occur in your business processes. For example, Created Order, Updated Order, Reviewed Order, Shipped Order. This data is static and allows you to consistently reference the types of events that can occur. In a database, this would be considered a lookup table.
If you’re tracking events for the first time or you want to standardize your event data, you can generate these two new record types. Alternatively, if you have record types that already store this data, you can use those existing record types as your Event History and Event Type Lookup record types.
If you haven't tracked business events before, check out the following considerations before getting started.
When you generate new record types to store your event data, Appian will also generate the underlying database tables for the new record types. The new tables will always be written to the same source used for the base record type. This source must be a MariaDB, MySQL, Oracle, SQL Server, PostgreSQL, or Aurora MySQL database.
To generate new record types:
Under Types of Events, specify the types of events that can occur in your business processes. The event types will be written as values in the generated Event Type Lookup record type.
|Include Common Event Types||Keep the Created records, Updated records checkbox selected to capture events for creating and updating records in the base record type. This will automatically configure any generated Create or Update record actions to write records and events.
If you've already configured or generated record actions before you configured record events, you will need to manually update your Write Records nodes in your process models to also write events. Learn more.
|Other Event Types||Enter any additional event types that you’d like to capture. If you included common event types, they will be automatically included with any other event types you enter.
Enter each additional event type on a separate line and format them in the past tense. For example:
Event History: By default, this value is the base record type’s name appended with
Event History. For example,
Order Event History. Keep the default or update as necessary.
Event Type Lookup: By default, this value is the base record type’s name appended with
Event Type. For example,
Order Event Type. Keep the default or update as necessary.
Keep the Download database script checkbox selected to download an auto-generated database script when you click GENERATE. This script contains the SQL commands that Appian will use to create database tables for the two new record types.
The auto-generated database script is not saved in Appian, so we strongly recommend downloading the script now and storing it locally.
The generated Event History record type has the following configurations:
Relationships: Relationships for the generated record type include:
|Base record Type||Relationship||Related Record Type||Purpose||Example|
|Where you're configuring record events||One-to-many||Event History||Allows you to reference the different events associated with each record.||The Order record type has a one-to-many relationship with the Order Event History record type.|
|Event History||Many-to-one||Where you're configuring record events||Allows you to reference the record associated with each event.||The Order Event History record type has a many-to-one relationship with the Order record type.|
|Event History||Many-to-one||Event Type Lookup||Allows you to reference the types of events that can occur.||The Order Event History record type has a many-to-one relationship with the Order Event Type record type.|
|Event History||Many-to-one||User||Allows you to reference the user who completes an event.||The Order Event History record type has a many-to-one relationship to the User record type.|
Fields: The Event History record type contains six required fields by default:
|Default Field||Data Type||Description|
||Number (Integer)||This is the primary key field, which is the unique identifier for each event.|
||Number (Integer)||The common field that establishes a relationship between the Event History record type and the base record type.
This field has a foreign key constraint in the generated database table.
||Number (Integer)||The common field that establishes a relationship between the Event History record type and the Event Type Lookup record type.
This field has a foreign key constraint in the generated database table.
||User||The user who completed the event. If this value is null, Appian assumes the event occurred due to an automated activity in the process model.|
||Number (Integer)||The type of automation that completed the event.|
||Date and Time||The date and time when the event occurred.|
You can modify the generated Event History record type to meet any additional business requirements.
The generated Event Type Lookup record type has the following configurations:
Fields: The Event Type Lookup record type contains two fields by default. Appian does not recommend adding fields to this record type, because it's meant to serve as a lookup table for the Event History record type.
|Default Field||Data Type||Description|
||Number (Integer)||This is the primary key field, which is the unique identifier for each activity.
This field is also the common field that establishes the relationship between the Event History record type and the Event Type Lookup record type.
||Text||The name of the event that occurred.|
You may already have record types that store your event history and event types. If so, you can easily configure record events using those existing record types.
When selecting an existing record type to store your event history, it must have fields that represent the following items:
If you want to capture the type of automation that completes an event, the existing record type must also have fields that represent the following items:
Once you choose your record types, you’ll need to specify the fields to use for the User, Timestamp, Automation Type ID, and Event Name. These field mappings will allow you to write events from the Write Records smart service.
To use existing record types:
Configure the following properties:
|Event History||Select a related record type to store all event data. The base record type must have a one-to-many relationship to this record type.|
|User Field||Select a field of type User from the selected Event History record type. This field will store the users who complete each event.|
|Automation Identifier Field||Select a field of type Number (Integer) from the selected Event History record type. This field will store the event's automation type. Make sure any existing data in this field corresponds to the list of supported automation identifers.|
|Timestamp Field||Select a field of type Date and Time from the selected Event History record type. This field will store the date and time when each event occurred.|
|Event Type Lookup||Select a related record type to store the different types of events. The Event History record type must have a many-to-one relationship to this record type.|
|Event Name Field||Select a field of type Text from the selected Event Type Lookup record type. This field will store the names of the different event types.|
You can modify an Event History record type to meet any additional business requirements.
For example, you may choose to add a
description field to collect more information about an event. Any fields you add to the record type will appear in the Write Records smart service so you can specify the values to write for the event.
You may already be using record events, then decide you want to start capturing the type of automation that completes each event in your business process. You can easily include the automation type in your event data by adding the automationId field to the Event History record type and updating your record events configuration.
To add the automationId field to the Event History record type:
automationTypeId. This field is created automatically if you generate new record types.
To update your record events configuration:
Once you've updated your Event History record type and your record events configuration to store the automation type, you'll need to update any existing process models so the Write Records smart services will write the correct automation type in the record. Follow the steps below to set the Automation Type you want to capture when writing events.
See Update a Source from Your Record Type to learn how to make other updates to your record type.
Once you configure record events, you can incorporate event tracking into your new and existing process models using the Write Records smart service. When you configure the smart service to write records, you can also specify what events to write, when to write them, and how the events are completed.
You can only write records and events using the Write Records smart service. You cannot use the
a!writeRecords function to write records and events at the same time.
If you generate Create or Update record actions, Appian will automatically configure the Write Records node to write events.
If you do not generate your record actions, or you want to write more specific types of events (like Reviewed Order or Shipped Order), you can manually configure the Write Records node to write events.
To write events:
Go to the Setup tab.
If you do not see the Setup tab in your node, replace the current node with a new Write Records node.
Select the values to write for the event. The field inputs are populated from the related Event History record type. You must map values for the following field inputs:
|Event Type||Use the dropdown to select an event type or use an expression to specify the event type. The dropdown list is populated from the values in the Event Type Lookup record type. If you use an expression, you must use the event type identifier to indicate the type of event. Learn more about conditionally choosing event values.|
|User||Use the dropdown to select the Process Initiator or a process variable of type User or Text, or use an expression to specify the user. If the event will be completed by an automated task, set the value to Null (Set as System Event).|
|Automation Type||Use the dropdown to select the type of automation that will complete the event, or use an expression to specify the automation type. If the event isn't automated, set the value to None (User) to indicate it will be completed by a user. Learn more about capturing automation types.|
|Timestamp||Use the dropdown to select Now (the date and time when the node is executed) or a process variable of type Date and Time, or use an expression to specify the date and time.|
The Write Records smart service only writes events for the record type associated with the Records Input value. Event data is not automatically create for any related record data, but it can be created using a separate Write Records node.
There are some scenarios where you may only want to write events and not records, like when you want to capture events for an automated task or a task escalation. See the Write Records smart service to learn how to write events without writing records.
When you're capturing automation types in your event data, remember to configure your Write Records smart services to write who or what completed each event. Even though a process might involve multiple users or automation types, you want your event data to show the user or automation type that actually completed the task.
In general, use the following guidelines to configure the User and Automation Type properties when writing events:
If the event was completed by a human, set the User property to the appropriate field from the Event History record type. Then, set the Automation Type property to None (User).
If the event was completed by automation, set the User property to Null (Set at System Event). Then, select the appropriate automation type for the Automation Type property.
Appian recommends categorizing automation types according to the following table:
|None (User)||1||User Input Tasks like submitting a form|
|RPA||2||Execute Robotic Task smart service, robotic process automation (RPA) plug-ins|
|AI||3||AI Skills smart services (Classify Documents, Extract from Document, Classify Emails), AI plug-ins|
|Integration||4||Call Integration smart service, Call Web Service smart service, Invoke SAP BAPI smart service|
|Other||5||Expression Rules, Decisions, process orchestration, other smart services|
The Write Records node will write the automation type by its corresponding identifier. If you write your own expression to capture the automation type, use a!automationId() to write the automation type's identifier.
When configuring Write Records nodes, consider how the event data you capture can best support your business needs. You can configure the User and Automation Type properties as described above, but you may want to capture more information or introduce more complicated rules for determining the automation type.
For example, one of your processes might send an automated email as the result of a user action. You could capture this as a system event by setting the Automation Type to Other, then also capture the user by setting the User to Process Initiator.
You might also choose to write an expression with conditional rules for which automation type should be captured. For more information, see a!automationId().
Of course, the full picture of how your events are completed can be complicated. You might have more than one type of automation attempting to complete the same task, or your process might require a user to complete a task after automation attempts it. In either case, Appian recommends capturing each attempt in a separate Write Records node to ensure your event data accurately reflects how the event was completed.
In the following example process, the Classify Documents Smart Service attempts to classify documents, but a user can classify them instead if it fails. The process has two Write Records nodes for the same "Classified Docs" event: one that writes event data if the AI skill successfully completes the task (1), and one that writes event data if a user successfully completes the task (2). A third Write Records node writes event data when a user reviews the documents (3).
In this example, capture the following automation type for each node:
|1||AI||Write event data if the AI skill successfully completes the task.|
|2||None (User)||Write event data if a user successfully completes the task.|
|3||None (User)||Write event data when a user reviews the documents.|
Your processes might also involve multiple automation types working together to complete an event. Whenever this is the case, Appian recommends attributing the event to the most complex automation type.
For example, if you have an event that's completed by integration to an RPA vendor, such as Blue Prism, Appian recommends attributing the event to RPA, even though an integration was part of the process.
The following lists ranks automation types in order of complexity, with 1 being the most complex and 4 being the least complex:
As you collect event data, you can display a history of events in your record views, interfaces, and reports using the Event History List component.
You can display your event history as a timeline or as a list to show a snapshot of your business operations. Use the component to display a history of events for all records, or only display the events for a specific record. This component is automatically added to any generated Summary view so users can quickly see a history of events related to their records.
To take your data a step further, you can mine your event data using Appian's process mining capabilities. Process mining helps you find new ways to optimize your business processes. Since your event data is stored in your record types, it's easy to load the data into Mining Prep and get started.
Configure Record Events