Configure Record Events

This page describes how to configure record events on your record types.

Prerequisites for record events

Before you begin, ensure your record type meets these requirements:

• Supported Record Types: Record events can be configured on synced or unsynced record types that use a database table as the source and have a single primary key.
• Unsupported Record Types: Record events are not supported for:
  • Record types with a composite primary key.
  • Record types that use a database view or web service as the source.
  • Legacy record types.
• Design Guidance: Review the record events guidelines to determine which events to track and which features your application requires.

How to configure record events

To configure record events:

1. Generate or manually configure record types to store event data.

   Note:  Review the event record types needed for record events.

2. Modify the Event History record type as needed.
3. Configure optional record events features:
   • Enable collaboration with record events.
   • Measure automation with record events.
4. Write events with the Write Records smart service.

Generate new event record types

If you're setting up a brand new record events configuration or you want to standardize your event data, you can generate new record types to store this data.

When you generate new record types to store your event data:

• Appian will 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.
• We'll automatically add custom record fields to your base record type to calculate key process metrics.

To generate new record types:

1. In the record type you want to track events for, go to Events.
2. Click GENERATE EVENT RECORD TYPES.

3. Under Types of Events, specify the types of events that can occur in your business processes. Use the record events guidelines to choose which events to track. The event types will be written as values in the generated Event Type Lookup record type.

   Option	Action
   Include Common Event Types	Keep the Created records, Updated records, and Commented on records checkbox selected to automatically include these event types in the generated Event Type Lookup record type. If you are using record events to improve your business processes, do not select this option since it includes ad hoc events. When this option is selected: Appian will automatically configure any generated Create or Update record actions to write records and events. Any top-level comments on an event history list component will be automatically captured as a "Commented on Record" event type. 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: Reviewed Order Approved Order Canceled Order Shipped Order Delivered Order

4. Under Record Type Names, enter names for the following record types:

   Record Type	Example Name
   Event History	Order Event History
   Event Type Lookup	Order Event Type
   Reply Thread	Order Reply Thread
   Subscriber	Order Subscriber

5. For Application, specify where you want Appian to create the new record types. This option only appears if your base record type is associated with more than one application and you have permission to view those applications.

6. 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 new record types.

   Caution:  The auto-generated database script is not saved in Appian, so we strongly recommend downloading the script now and storing it locally.

7. Click GENERATE to generate the new record types and configure record events.
8. Click SAVE.

Generated Event History record type

The generated event history record type will use optimized data access and include the following security and data model.

Object security

The generated Event History record type copies the group object security of the base record type. Generated record types do not copy individual user security.

Relationships

When you generate an Event History record type, it has the following relationships:

Base record Type	Relationship	Related Record Type	Purpose
Where you're configuring record events	One-to-many	Event History	Allows you to reference the different events associated with each record.
Event History	Many-to-one	Where you're configuring record events	Allows you to reference the record associated with each event.
Event History	Many-to-one	Event Type Lookup	Allows you to reference the types of events that can occur.
Event History	Many-to-one	User	Allows you to reference the user who completes an event.
Event History	One-to-many	Reply Thread	Allows you to reference a comment or reply from a threaded conversations on an event history list component.
Where you're configuring record events	One-to-many	Subscriber	Allows you to reference the users subscribed to conversations on an event history list component.

The following diagram shows an example of the relationships between an Order record type and its generated record events record types:

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

Fields

By default, the Event History record type contains the following fields:

Default Field	Data Type	Description
id	Number (Integer)	This is the primary key field, which is the unique identifier for each event.
recordId	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.
eventTypeId	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	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.
automationTypeId	Number (Integer)	The type of automation that completed the event.
comment	Text	The comment that a user added to the event history list component. Appian automatically writes to this field when users leave comments.
timestamp	Date and Time	The date and time when the event occurred.

Generated Event Type Lookup record type

The generated event type lookup record type will use optimized data access and include the following security and data model.

Object security

The generated Event Type Lookup record type copies the group object security of the Event History record type. Generated record types do not copy individual user security.

Fields

By default, the Event Type Lookup record type contains two fields. 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
id	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.
name	Text	The name of the event that occurred.

Generated Reply Thread record type

The generated reply thread record type will use optimized data access and include the following security and data model.

Object security

The generated Reply Thread record type copies the group object security of the Event History record type. Generated record types do not copy individual user security.

Fields

By default, the Reply Thread record type contains the following fields:

Default Field	Data Type	Description
id	Number (Integer)	This is the primary key field, which is the unique identifier for the comment or reply in a threaded conversation.
event_id	Number (Integer)	The common field that establishes a relationship between the Reply Thread record type and the Event History record type. This field has a foreign key constraint in the generated database table.
user	User	The user who added the comment or reply.
reply	Text	The comment or reply from the threaded conversation.
timestamp	Date and Time	The date and time the comment or reply was added.

Generated Subscriber record type

The generated subscriber record type will use optimized data access and include the following security and data model.

Object security

The generated Subscriber record type copies the group object security of the Event History record type. Generated record types do not copy individual user security.

Fields

By default, the Subscriber record type contains the following fields:

Default Field	Data Type	Description
id	Number (Integer)	This is the primary key field, which is the unique identifier for the subscribed user.
recordId	Number (Integer)	The common field that establishes a relationship between the Subscriber record type and the base record type. This field has a foreign key constraint in the generated database table.
user	User	The user subscribed to conversations on the event history list component.

Manually create event record types

If your record type uses a database that doesn't support event record type generation, you need to manually create the record types that store event data. You can also use this approach if you already have record types that store your event data.

Prepare your event record types

Before you configure record events, create or identify the record types that will store your event data:

1. Create a record type or identify the existing record type that stores who completed an event and when. This record type must meet the Event History record type requirements.
2. Create a record type or identify the existing record type that stores the types of events that can occur. This record type must meet the Event Type Lookup record type requirements.
3. (Optional) If you want to enable collaboration features, create record types for reply threads and subscribers.

Event History record type requirements

The Event History record type stores who completed an event and when.

When selecting an existing record type to store your event history, make sure it meets the following requirements:

• The event history record type has a many-to-one relationship to the base record type.
• The relationship to the base record type allows Appian to write related records.

The record type you select to store your event history must have the following required fields. If the record type doesn't have these fields, you can edit the record type to add new fields.

Field	Type	Required?	Purpose
User	User	Yes	Stores the user that completed the event
Timestamp	Date and Time	Yes	Stores the date and time the event occurred
Automation type	Number (Integer)	If capturing automating type	Stores event automation types using their corresponding identifiers
Comment	Text	If capturing user comments	Stores comments that users add to the event history list component

Event Type Lookup record type requirements

The Event Type Lookup record type stores the names of event types you want to track in your event data.

When selecting an existing record type to store your event types, make sure it meets the following requirements:

• The event types record type has a one-to-many relationship to the record type that stores your event history.
• The record type should contain the names of specific event types to track.

The record type you select to store your event types must have the following required fields. If the record type doesn't have these fields, you can edit the record type to add new fields.

Field	Type	Purpose
Event Name	Text	Stores the name of the event type

Reply Thread record type requirements

The Reply Thread record type stores comments and replies from threaded conversations on the event history list component. This record type is required if you want to enable threaded conversations.

When you create a new record type to store threaded conversations from an event history list component, make sure the Event History record type has a one-to-many relationship to the record type that stores threaded conversations.

The new record type must have the following required fields:

Field	Type	Purpose
User	User	Stores the user that added the comment or reply
Reply	Text	Stores comments and replies from threaded conversations
Timestamp	Date and Time	Stores the date and time the comment or reply was added
Event ID	Number (Integer)	The common field that establishes a relationship between the Reply Thread record type and the Event History record type. This field has a foreign key constraint in the generated database table.

Subscriber record type requirements

The Subscriber record type stores users subscribed to conversations on an event history list component. This record type is required if you want to enable subscribers.

When you create a new record type to store users subscribed to conversations on an event history list component, the base record type must have a one-to-many relationship to the record type that stores subscribers.

The new record type must have the following required fields:

Field	Type	Purpose
User	User	Stores the users currently subscribed to conversations on an event history list component
Record ID	Number (Integer)	The common field that establishes a relationship between the Subscriber record type and the base record type. This field has a foreign key constraint in the generated database table.

Configure record events

After you create the event record types, configure record events using those existing record types:

1. In the record type you want to track events for, go to Events.
2. Click USE EXISTING RECORD TYPES.

3. Configure the following Event History properties:

   Property	Value
   Record Type	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 identifiers. For more information, see Measure Automation with Record Events.
   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.
   Comment Field	Select a field of type Text from the selected Event History record type. This field will store user comments on the event history list component. For more information, see Enable Collaboration with Record Events.

4. Configure the following Event Type Lookup properties:

   Property	Value
   Record Type	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.
   Event Name for Adding Comments	Select a field of type Text from the selected Event Type Lookup record type. This field will store the event name to capture if a user adds a comment on the event history list component. For more information, see Enable Collaboration with Record Events.

5. (Optional) Configure the properties for Reply Thread and Subscriber. Review the requirements for Reply Thread record type and the Subscriber record type.
6. Click FINISH to configure record events.

7. Click SAVE.

   Record events are configured on the record type. Appian also automatically adds custom record fields to the base record type to calculate key process metrics.

Modify the Event History record type

You can modify an Event History record type to meet any additional business requirements.

For example, you may want to add fields to the Event History record type in the following scenarios:

• Add more context: Add a field like description to collect more information about an event. Any new fields will automatically appear in the Write Records smart service, allowing you to specify the values to write for the event.
• Track automation: Add an automationIdentifier field to indicate whether an event was completed by an automation or a human.
• Enable collaboration: Add a comment field to allow users to add comments on an event history list component. You could also add additional relationships to the Event History record type to support threaded conversations and subscribers.

Modify the base record type

Appian helps you calculate common success metrics for your business processes using custom record fields on the base record type in your record events configuration.

When you configure record events, we automatically add the following custom record fields to the record type where you're configuring record events:

Field Name	Description
minEventTimestamp	The timestamp for the first event related to the record.
maxEventTimestamp	The timestamp for the most recent event related to the record.
duration	The difference between minEventTimestamp and maxEventTimestamp, in days.

These fields are used to calculate how long it takes to complete your business process for each record in the record type. You can use this calculation to measure monthly process performance, average process duration, and more.

If you have an existing record events configuration, you can easily add these custom record fields with the Calculate Duration template.

Edit the record events configuration

You can edit your record events configuration as your application grows and changes.

For example, you may want to update a field in your record events configuration if the original field was removed. Or, perhaps you want to enable threaded replies and subscribers in your event history list component, so you need to add record types to store that data.

To edit the record events configuration:

1. In the record type you want to track events for, go to Events.
2. Click EDIT.
3. Update or remove the record types and fields associated with each event record type.
4. Click UPDATE.
5. Click SAVE.

Write events

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.

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:

1. (Optional) Configure record events for any record types you want to capture events for. You can only write records and events at the same time if the record type has record events configured.
2. In your process model, open the Write Records node.

3. Go to the Setup tab.

   

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

4. For Records Input, specify the data to write. You can select one or more process variables of type Record Type, or use an expression to pass data.

   To write to a base record and its related records:

   • Select a single process variable of type Record Type.
   • This allows you to write to the base record and any related records configured to Write or delete related records in a single transaction.

   Note:  If a record type has a composite primary key, the variable must contain values for all fields that make up the key.

   To write to unrelated record types:

   • Select multiple process variables of type Record Type.
   • This allows you to write to each unrelated record type in a single transaction.
   • Use this option for related records that are configured to Do not write or delete related records.

5. For Record Type for Events, select the record type you want to capture events for. You can only write events for one record type per node.

   Note:  If the record type does not have record events configured or multiple record types are selected, no events will be written.

6. If the record type in Record Type for Events has record events configured, choose when to write events:

   Option	Description
   Always	Write events whenever the node executes.
   Never	Never write events whenever the node executes.
   Only when…	Specify the condition in which events are written. Click Edit Condition to write an expression defining the specific condition.

7. 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:

   Input	Description
   Event Type	The type of event that occurred. 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	Who completed the event. If the event will be completed by an automated task, set the value to Null (Set as System Event).
   Automation Type	The type of automation that completed the event. If the event isn't automated, set the value to None (User) to indicate it will be completed by a user.
   Timestamp	The date and time when the event occurred. Select Now to capture the date and time when the node executed.

8. Click OK.
9. Click Save & Publish in the process model.

The Write Records smart service can only write events for a single record type, and that record type must be specified in Record Type for Events. Event data is not automatically create for any related record data, but it can be created using a separate Write Records node.

Feedback