Linking Process Flows to Events

Aptify Process Flow functionality allows an organization to configure the system to execute business-specific logic automatically. Event handlers provide the means by which these process flows may be applied.

An organization can specify event handlers at a Global, Application, or Entity level. For example, an organization can specify a process flow that sends a notification email each time a new Companies record is created in the system. For example, a process flow is configured to send an e-mail to a customer when their order is shipped. This process flow must be linked to the Orders entity. Because it relies on a specific subset of Orders records (those with a status of Shipped), it runs only when the record is saved with a Status value of Shipped.

Because all events are cached for performance reasons, it is recommended that the user close and re-open the Aptify application after modifying existing or configuring new event handlers.

This topic covers the following sub-topics:

• Setting Up Event Handlers
• Configuring Event Handler Input Maps

Setting Up Event Handlers

There are two ways to create, edit, and review Event Handlers:

• Setting Up Event Handlers from the Event Handlers Service
• Setting Up Events Handlers Using the Dashboard

Setting Up Event Handlers from the Event Handlers Service

This topic describes how to set up event handlers from the Event Handlers service.

1. Open a new Event Handlers record from the Event Handlers service.
2. Select the Event Scope of the event by selecting a type from the drop-down list.
3. If the Event Scope is set to Global, continue on to the next step. Otherwise:
   • If the Entity Scope is set to Entity, enter an entity for the event handler in the Entity field. The grid in the lower portion of the form displays a list of all other event handlers configured for that entity.
   • If the Entity Scope is set to Application, enter an application for the event handler in the Application field. The grid in the lower portion of the form displays a list of all other event handlers configured for that application.  
     
4. Enter the event definition in the Event field.
5. Enter the process flow to fire in the Process Flow field.
   • The input properties flow down from the process flow to the event handler's Input Map.
6. Specify the event's Sequence if the entity or application has more than one event associated with it.
   • The sequence determines the order in which multiple events are run if more than one event handler exists for the entity or application selected. This may be critical to business-specific functionality.
7. Configure the Input Map, as described in Configuring Event Handler Input Maps.
   • Note that for Event Handlers with a Global Event Scope, the Input Map populates automatically and cannot be edited by a user.
8. Save and close the record.

Setting Up Events Handlers Using the Dashboard

This topic describes how to set up event handlers using the Process Pipeline Administration dashboard:

1. Open the default Process Pipeline Administration dashboard, or another dashboard that includes the Event Handler Management component.
2. Locate the Event Handler Management window (shown in the figure below).
     
3. Select an Event Scope (Global, Application, or Entity).
4. If the Event Scope is set to Global, continue on to the next step. Otherwise:
   • If the Entity Scope is set to Application, enter an application for the event handler. The grid in the lower portion of the form displays a list of all other event handlers configured for that application.
   • If the Entity Scope is set to Entity, enter an entity for the event handler. The grid in the lower portion of the form displays a list of all other event handlers configured for that entity.
     
     
5. Open a new Event Handler Management record by clicking the Add Event Handler button on the Event Handler Management Dashboard.
   • If the Event Scope is set to Entity, the Entity field inherits the entity selected and is read-only.
   • If the Event Scope is set to Application, the Application field inherits the application selected and is read-only. 
6. Enter the event definition in the Event field.
7. Enter the process flow to fire in the Process Flow field.
8. The input properties flow down from the process flow to the event handler's Input Map. 
   
9. Specify the event's Sequence if the entity or application has more than one event associated with it.
   • The sequence determines the order in which multiple events are run if more than one event handler exists for the entity or application selected. This may be critical to business-specific functionality. 
10. Configure the Input Map, as described in Configuring Event Handler Input Maps.
    • Note that for Event Handlers with a Global Event Scope, the Input Map populates automatically and cannot be edited by a user. 
11. Save and close the record.

Configuring Event Handler Input Maps

The Input Maps tab inherits a list of rows which reflect all input properties configured on the process flow selected. Each input map describes data that is used and may be required for proper functionality of the process flow. Configuration of the input maps tells the system how to access the necessary data.

You can configure the input maps directly in the grid on the Input Maps tab or you can double-click the individual rows to display an Edit Mapping dialog box. Required input properties appear in red. You must provide a source value for these properties.

The Input Map populates automatically for Global Event Handlers and cannot be edited by a user. See Capturing Message Details from a Message Run for Use in a Process Flow for an Example of a Global event handler using the AfterSendMessage Event.

Follow these steps to configure an input map:

1. Select Source Type for the input map. Available values are:
   • Static Value: The system uses the alphanumeric text entered in the Source field.
   • Entity Field: The system uses the current record's value from a specified field in the entity to which the event handler is attached.
     • For example, if saving a new Entities record fired the Event Handler, this option retrieves the specified field's value from that new record and adds it to the Context Object, so it is available to the Process Flow.
   • SQL Statement: The system obtains a value for the input map by executing a specified SQL statement.
   • GE Object: The system obtains a value for the input map from the Generic Entity (GE) object.
     • For this option, the source is automatically set to the GE Object, and the user may not specify a value for the source.

     • This setting is suitable if a developer has created a Process Component that obtains record information from the Generic Entity interface. 

2. Enter a Source for the input map. The format of the value for the Source field is dependent on the Source Type selected:

   • Source Type of Static Value: Enter an alphanumeric text statement. To include field data from the entity record that fired the event within the text, surround the field name with field tags (<%field name%>).
   • Source Type of Entity Field: Enter the name of a field within the entity to which the event is linked. The Event Handler retrieves the field value from the current record that fired the event.
   • Source Type of SQL Statement: Enter a SQL statement to derive the data.
   • Source Type of GE Object: The Source field is populated automatically with the GE Object entry.
     
3. Enter Comments for each input map as necessary (optional).
4. After configuring all of the input maps, click OK to save and close the record.