Simple Process Flow and Event Handler Example

This example explains how to set up a simple process flow in Aptify. This process flow is then linked to an event handler so the functionality may be tested. It is assumed that the Process Components and Event Definitions records delivered with the standard application have been installed, and that the following services have been added to the user's profile:

• Process Categories
• Process Flows
• Event Handlers
• Companies

This topic covers the following sub-topics related to setting up a simple process flow:

• Business Case and Designing the Simple Process Flow
• Creating a Simple Process Flow Category
• Creating the Simple Process Flow
• Linking the Simple Process Flow to an Event
• Testing the Simple Process Flow Event

Keep in mind that in lieu of creating an Event Handler, you can use the Process Flow Debugger tool to test your process flow. However, this tutorial tests the process flow using an Event Handler to illustrate how an Event Handler is created.

Business Case and Designing the Simple Process Flow

In this step of the Simple Process Flow tutorial, an organization requests that the system be configured so that an immediate email notification is sent to the sales department any time a new company is added to the database. This configuration is meant to enable them to track not only Companies records created by call takers within their organization, but also any records created from web-based links to their applications.

Outlining the Process Flow

Outlining is one of the most important steps in configuring Aptify Process Flows, no matter how simple the flow may seem.

• How Many Steps?

• Does the Functionality Already Exist?

• What Data Will the Process Flow Use?

• Is Any Data Returned?

• Completing the Outline

How Many Steps?

The purpose of the business case stated above is to notify the sales department by email each time a new Companies record is created. This is a very simple process, with only one process step – sending the email message. No further processing is necessary.

Does the Functionality Already Exist?

The next step is to determine the functionality of each step. In the case of this example, there is only one step, and the functionality of this step is to send an email.

Aptify comes with a standard set of Process Components, each of which defines a set piece of functionality. These components are listed in Process Components as Delivered. One of the standard components is named Send Email, indicating that the functionality desired is available within the system. We simply need to configure the system to make use of this existing component.

What Data Will the Process Flow Use?

When a process flow starts, all required data is gathered at one time. This data is then placed in a temporary storage place, called the Context Object. This data might come from fields on a form, be derived from the database using a SQL statement, or be hard coded in the system.

Regardless of the source, it is important to remember that once the process flow starts and the Context Object is populated, it cannot go outside the Context Object to retrieve any more data. The process flow is, in a sense, surrounded by a bubble. The Context Object data is inside the bubble, and everything else is outside. For this reason, it is critical that all data which may be used by all steps within the flow be determined in advance.

Determining the data used by a process flow can be a challenging task and is yet another reason why it is important to outline the entire process flow before beginning any configuration within Aptify. This is because once all the steps in the process flow are defined in the outline, the underlying functionality of each step is known. Basic knowledge of the delivered Process Components records will help a developer or administrator determine the data required by each step in a process flow.

However, it is also possible to determine some of the data required simply by looking at the Process Flow outline. For this tutorial, we need to ask ourselves what we know so far. We know that:

• There is only one step.
• The functionality to send an email exists within Aptify.

Required Data

In order to send an email message, an email system requires specific data elements from the user. Some of these data elements are:

• The message system that will send the email (this tutorial uses Microsoft Outlook; therefore, you must have Microsoft Outlook installed and operational on your computer to successfully create and test this process flow)
• The recipient of the message
• The sender of the message
• The subject of the message
• The text of the message

email messages may be sent in a variety of formats, such as plain text or HTML. Most email programs require that the format be determined before the message is sent. Thus, the following may be added to the list of required data:

• The type of message format

To verify that the list includes all required data elements, review the items found on the Input Properties tab of all process components used in the process flow. In this case, the flow only calls the Send Email process component.

Other Data

There are other data values which could be useful for this process flow but are not required. These include:

• email addresses for the carbon copy (CC) list
• email addresses for the blind carbon copy (BCC) list

Based on what we've gathered so far, we now have a list of data which may be used by the process flow.

Is Any Data Returned?

Now that we know what data the process flow uses, the next question to ask is whether the process flow returns any data. Let's look at the requirement again: send an email notification when a new Companies record is created in the system. Remember, we already determined that no further processing is necessary after the email is sent. Therefore, the answer to this question is no.

Completing the Outline

We have determined the number of steps in our process flow and the functionality for each of them, the data to provide, and whether the functionality exists within the system. Now we are ready to actually create the process flow in Aptify.

Creating a Simple Process Flow Category

In this step of the Simple Process Flow tutorial, it is assumed that more than one process flow will be set up in the system over time to send email notifications. These email notifications may be sent to customers, managers, or suppliers, depending on how the application is configured. To enable these process flows to be grouped together, you should create a Process Flow Category. Follow these steps:

1. Open a new record from the Process Flow Categories service.
2. Enter email Notifications in the Name field. If desired, enter a description.
3. Enter the Messaging record as the Parent category (assuming that your system already has a Messaging category).
   
   
4. Save and close the Process Flow Categories record.

Creating the Simple Process Flow

In this step of the Simple Process Flow Tutorial, follow this procedure to create the simple Process Flow to send an email message when a new company is added to the system:

1. Open a new record from the Process Flows service.
2. In the Name field, enter XY Send email where XY are your initials. If desired, enter a description.
3. Enter email Notifications in the Category field. This links the record to the Process Flow Categories record we created earlier in the example.
   
   
4. Click the Input Properties tab and enter the properties listed below.
   
   • During the outlining process for the business case, we determined a list of data that may be used by the process flow we are generating. To tell the system which data elements to capture and store in the Context Object, the list must be created as Input Properties. 
     
     

   Name	Type	Default Value	Required	Value List Type
   To	String		Yes	None
   Subject	String		Yes	None
   TextBody	String		Yes	None

   
   

5. Click the Result Codes tab.
6. Create two Result Codes records: one for SUCCESS and one for FAILED, as shown in the following figure.
   
   
7. Save the Process Flows record.
8. Click the Design tab.
9. Select the Insert Component Step button in the toolbar.
10. Move the cursor to the design area and click the mouse button to drop the component step in the selected location.
    
    

    

    • A new step appears in the Design area. The step's details load in the Properties area on the right-side of the Process Flows record.
    • Resize the form as necessary so you can read all of the fields in the Properties area.
11. Within the step's Properties area, select the Send Email component from the Component drop-down list.
    
    • The Send Email component is located under the Messaging category.

    

    • Each Process Component set up in Aptify is configured with a list of Input Properties which detail all data elements used by that component. Components are also set up with a list of data returned by the component (if any), and all expected results when the component is run.
    • Once a component is selected in the Component field, several tabs on the Properties dialog automatically inherit information which reflects that defined at the component level: Input Maps, Output Maps, and Action Maps tabs. These must all be configured before the step is completed. Note that for this business case, no output maps are configured.
12. Modify the Step Name to read XY Send E Mail, where XY are your initials.
    • When you select a component, the system automatically updates the step's Name to match the name of that component.
13. Click the Description tab and replace the placeholder text with This step sends an email message.
    
14. Click the Properties tab and configure the step's input properties. Note that this type of interface is known as an Input Map.
    
    • On each step of any process flow, we must tell the system where the data is to be found. Do we expect the system to derive the data from the database? Do we expect it to be stored within that Context Object bubble? Or are we going to provide a value that remains constant, no matter how and when that process step is called?
    • Only certain Input Maps are required for this step, so for the purposes of this tutorial, only those Input Maps are configured.
    • Each input map may be edited directly within the grid. You may also double-click on the line item in the grid to display an Edit Mapping dialog box. Note that you can select a value from a Source drop-down list for Context Object inputs. The drop-down list displays the items you specified for the Process Flow's Input Properties tab.
    • Note that this tutorial uses Microsoft Outlook; therefore, you must have Microsoft Outlook installed and operational on your computer to successfully create and test this process flow.
    • Configure the following Input Maps as follows:

    Name	Source Type	Source
    MessageSystemName	Static	Outlook Mail
    To	Context Object	To
    Subject	Context Object	Subject
    TextBody	Context Object	TextBody

    

15. Save the record.
16. Click the Action Map tab.
    • The Action Map tells the system what to do once the step has finished. Should it trigger another step, or should it tell the system that the process flow has ended?
    • Remember, we determined in the process flow outline that this process flow has only one step. This means that no more steps are called upon completion of the XY Send Email step, no matter what happens.
17. By default, the Send Email component has one outcome, SUCCESS. For this item, select End Process from the Action drop-down list.
    
    
18. Enter the corresponding SUCCESS process flow result code (which you previously specified on the Process Flows record's Result Codes tab) in the Process Flow Result Code field for this outcome.
    
    
19. Close the Process Flows record. When prompted, click Yes to save the record.

At this point you can use the Process Flow Debugger tool to test your process flow without having to create an Event Handler. See Using the Process Flow Debugger for details.

Linking the Simple Process Flow to an Event

In this step of the Simple Process Flow tutorial, the business case developed for this example specifies that the email must be sent when a new Companies record is added to the system. This indicates that the XY Send Email process flow must be somehow connected to the Companies service, so that the system knows why and when to send a notification.

There are several events that occur within the normal life cycle of a record in a database. These include when the record is created, saved, updated, and deleted. The standard Event Definitions are listed and defined in Event Definitions as Delivered. The appropriate event must be determined to allow the functionality we are implementing in this example to work correctly.

Examine what is known about the business case. The email will be sent only when a new Companies record is created, not when existing Companies records are updated. We also make the assumption that this email will only be sent after the record has been saved in the database. This information indicates that the AfterRecordCreated event is the most appropriate event to use for the process flow.

Perform these steps to link the simple process flow to an event:

1. Open a new record from the Event Handlers service.
   • You can also review Event Handlers using the Aptify Event Handler Management dashboard component. See Using the Event Handler Management Dashboard for details.
2. Leave Event Scope set to Entity.
   
3. Enter Companies in the Entity field.
   
4. In the Event field, enter AfterRecordCreated.
   
5. In the Process Flow field, enter your XY Send email process flow.
   • Once the process flow is specified, the Input Map tab populates with the Context Object input properties defined in the process flow. In this case, this corresponds to the To, Subject, and TextBody input properties.
     
6. Leave the Active option selected.

7. Fill out the input map as described below:
   
   

   Input Property	Source Type	Source
   To	Static Value	<<enter your email address>>
   Subject	Static Value	New Company Created: <%Name%>
   Body	Static Value	A new Company record has been entered for <%Name%>. The assigned ID is <%ID%>.

   • Each row may be configured directly in the grid. You may also double-click on the row, or click on the ellipsis (...) button in the Source field to display an Edit Mapping dialog box.
   • While the business case indicates that the notifications are to go to the Sales department, for the purposes of testing, enter your own email address instead of <<your email address>> in the To row.
   • Aptify will automatically insert field data from the new Companies record in the placeholders surrounded by the brackets and percent signs.

   

8. Save and close the record.
9. Close and reopen Aptify before continuing.

Testing the Simple Process Flow Event

In the final step of the Simple Process Flow tutorial, the process flow has been created and linked to the Companies entity. All that remains now is to test the functionality. Follow these steps:

1. Open a new record from the Companies service.
2. Enter XY Test Only in the Name field, where XY are your initials.
3. Save the record.

Depending on the version and settings of your Microsoft Outlook installation, you may receive a message stating that an outside source is attempting to send an email. Click the OK button to allow this to occur.

If the configuration is successful, an email message soon appears in your Inbox, with the subject and body text set up in the Input Maps for the event handler, as illustrated below:

Cleaning Up

Unless you make the Event Handler inactive, you will continue to receive email messages each time anyone creates a new Companies record in the system.

1. Open the Event Handler created in this example.
2. Clear the Active option.
3. Save and close the record.
4. Close Aptify and re-open before performing any more configuration within the system.