Show / Hide Table of Contents

    The Event Manager Service

    Overview

    The Event Manager Service is a Windows service that runs at set intervals, starting and continuing process instances in response to predefined conditions - these conditions describe certain events and the responses are referred to as triggers.

    A Configuration Manager is required to configure the two parts pertaining to an Event Manager Service, the first of which relates to the service as Windows Service and includes access to an accompanying Activity Server, and the second relates to the service’s runtime behaviour and entails the definitions of events and the associated triggers.

    Important

    Only a Configuration Manager with matching version can configure and manage a specific Event Manager Service.

    Configuring the Windows Service

    The configuration of the Windows Service part of an Event Manager Service primarily entails connecting to an Activity Server, and is typically persisted on the machine hosting the Event Manager Service. Open the Configuration Manager and select the specific Event Manager Service.

    Event Manager - Configuration Manager Started

    Tip

    To configure an Event Manager Service it should be stopped. A running service is stopped by clicking Stop Service on the (right-click) context menu or from the Actions pane.

    Event Manager - Configuration Manager Stopped

    Double-click the specific Event Manager Service, or click Configure Service in the Actions pane to open the service configuration window.

    Event Manager - Service Configuration

    The Windows Service part of an Event Manager Service is configured on the Service tab.

    Server Address

    The address of the Activity Server to which the Event Manager Service should connect. The Activity Server hosts the activities to be triggered by the Event Manager Service, and persists the event definitions described later.

    Username and Password

    The username and password for the user account used by the Event Manager Service to access the associated Activity Server. On selecting Windows Authentication, the Windows Service username under which the Event Manager Service was installed will be displayed - the associated Windows password needs to be provided prior to configuring the service.

    Note

    The password provided under the Windows Authentication option is required to access the Activity Server, it is not persisted in any way and therefore needs to be provided every time the service is to be configured.

    Important

    Review the section Service User Access Rights for the required rights of the associated user account, both for accessing the Activity Server and for running an Event Manager Service.

    Tip

    To validate a specific user account, sign into a Web Navigator that connects to the same Activity Server. Once the credentials are validated, try accessing the activities that will be used in subsequent configurations in order to verify the user's access to these.

    Timer Interval

    The interval (in minutes) between service activations, during which time the service is effectively dormant. Once this interval expires the service is activated, resulting in it performing its primary function (matching event definitions), after which the next interval of inactivity begins.

    Debug Service

    Instructs the Event Manager Service to log more verbose information to the associated Windows Event Log.

    Note

    As the Windows Event Log has a limit on its number of entries, and to prevent the service from filling it up, the Debug Service option is not persisted. The service will log more verbose information the next time it starts up, but once it is restarted (after this run) this option will be reset, falling back to normal (less verbose) logging to the Event Log.

    Configuring Events for the Event Manager Service

    The primary function of the Event Manager Service is to match events and responding accordingly. These events are defined using the Configuration Manager, and the definitions (and the possibly many execution states thereof) will be persisted by the Activity Server associated with the service.

    Design Considerations

    Activities that are to be used by an Event Manager Service should be designed with this context in mind (even though this is not a requirement, it makes the overall process less prone to errors). A typical activity to be completed by a human participant, might have complex business logic and rules, extensive validations, and all sorts of objects and visual logic (showing and hiding objects based on input) to aid such a user in correctly participating in the process, whereas at most, the Event Manager Service might be able to populate simple objects based on external input (and based on the event types discussed next) without the ability to react to errors returned on the activity. To this end it might make sense to have activities specifically designed and accessible by the service user associated with the Event Manager Service and an, almost duplicate but more comprehensive, set of activities for non-service users (the alternative might include more complicated logic, including the use of task parameters to direct logic accordingly).

    Tip

    Always test activities manually via a client (such as the Web Navigator) before using them with the Event Manager Service - if the manual test fails, the automated case, via the service, will most probably also fail.

    Important

    The Event Manager Service does not support multiple Command Options on activities - the first one, by index, will always be selected to complete an associated activities.

    File Based Events

    The file-based event type expresses an event type relating a preconfigured file system change, the event, with a configured outcome that includes starting a process or continuing a pending process instance. The process instantiation or continuation occurs as a file becomes available in some location - the file can become part of the process instance by being associated with a File Attachment on an associated activity and/or content from the file being imported to objects on the activity.

    The file-based events are located in the File Based Events tab in the Configuration Manager. A new file-based event definition is created by right-clicking the Event Definition node in the File Based Events pane, adding a new one accordingly:

    Event Manager - Add File-Based Event

    Activity Configuration

    The Activity Configuration screen is displayed next to the associated event definition with default layout similar to the following:

    Event Manager - File Activity Configuration

    Activity Type

    A value that indicates whether a process instance will be instantiated, New, or continued, Pending, based on the availability of files defined in the remaining sections.

    Event Manager - File Activity Type

    Important

    To continue a Pending process instance, the file name must be the database id of the target pending activity instance associated with the process instance.

    Activity

    The name of the activity that should be triggered once a file that conforms to the criteria (defined next) becomes available. Select the applicable activity - the name of the event definition will be updated to reflect this.

    Event Manager - File Activity

    Important

    The user account configured for the Event Manager Service must have access to the specific activity.

    Type Activities available (in Active Processes)
    New Any activity with Creation Type set to First Activity
    Pending Any activity that the associated service user will participate on.
    File Object

    The name of a File Attachment object on the specific activity to which a conforming file will be attached before completing the activity.

    Event Manager - File Object

    Monitor Path

    The physical path that the Event Manager Service should monitor for conforming files.

    Event Manager - File Monitor Path

    Important

    The user under which the Event Manager Service runs must have read and write access to the monitor path. The write access is required for the service to remove any files that it has successfully processed, preventing it from using the same files.

    Warning

    Network locations are not supported.

    File Type

    The file type that the Event Manager will be looking for under the specified Monitor Path. The options include CSV and XML, for files with these respective extensions, and Other for all other file extensions.

    Event Manager - File Type

    File Identifier

    Defines an optional prefix for the file names to be monitored. This option allows the same Monitor Path to be the source for multiple File Based Events.

    Event Manager - File Identifier

    Processed Action

    Indicates what should happen to a conforming file once it has been processed.

    Event Manager - File Processed Action

    Note

    The specified Processed Action will only be applied once the associated event is successfully triggered.

    • Delete the file

      Once the file-based event is triggered, the processed file should be deleted.

      Event Manager - Delete File

    • Move the file

      Moves a processed file to the specified path once the file-based event is triggered.

      Event Manager - Move File

    • Prefix the file name

      Prepend a processed file’s name with the specified value once the file-based event is triggered.

      Event Manager - Prefix Text

    How do I Start a Process Using a File?

    In this example, a file is going to be used to start a process. The activity with Creation Type set to First Activity has a File Attachment that will be used to upload the file via a file-based event, and a single Command Option to complete the activity (starting the process).

    Event Manager - Example 1 Activity

    Event Definition - Activity Configuration

    The Activity Configuration on the associated Event Definition has been updated with the New activity name, File Attachment set, path to monitor updated and moving the Other typed file to the some location once successfully processed.

    Event Manager - Example 1 Activity Configuration

    Running the Event Manager Service

    Once the configuration is updated and saved, the service can be started in the Configuration Manager. Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution (with a file matching the criteria), looks as follows:

    Event Manager - Example 1 Success

    Following the successful execution, the file is moved to the folder specified:

    Event Manager - Example 1 File Moved

    The created process instance will be available for the next participant to complete. The activity completed by the service is displayed in the branch history, and will look similar to:

    Event Manager - Example 1 History

    How Do I Use a File to continue a Process Instance?

    In this example, the following two Pending activity instances are assigned to the service's user, the first indirectly through a Role Group membership and the second directly to the user.

    Event Manager - Example 2 Pending Tasks

    Event Definition - Activity Configuration

    The Activity Configuration on the associated Event Definition has been updated with the Pending activity name, File Attachment set, path to monitor updated and prefixing the Other typed file with the value Processed once successfully processed.

    Event Manager - Example 2 Activity Configuration

    To be associated with Pending activities, the files must have the database id of the activity targetted by it as name:

    Event Manager - Example 2 Files

    Running the Event Manager Service

    Once the configuration is updated and saved, the service can be started in the Configuration Manager. Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution (with files matching the criteria), looks as follows:

    Event Manager - Example 2 Success

    The original file names should be prefixed with the value Processed as configured in the Event Definition:

    Event Manager - Example 2 Results

    The continued process instances will be available for the next participants to complete. The first activity instance that was assigned to a Role Group, was completed by the service and displayed in the branch history will look similar to:

    Event Manager - Example 2 Group Task

    The second activity instance, that was assigned to the service user, was completed by the service and displayed in the branch history will look similar to:

    Event Manager - Example 2 User Task

    Additional Considerations

    Consider a scenario where there are Pending activities available, but there is either:

    • No file(s) available in the monitor path, or
    • File(s) are available in the monitor path, but the file names do not correlate (by id) with the pending activities instances

    When the service executes, informational messages that will be logged might look like:

    Event Manager - Example 2 Filter Failed

    Event Manager - Example 2 Filter Failed Message

    Compare this with the following, displaying error (rather than informational) messages due to issues on an activity:

    Event Manager - Exmple 2 Broken Activity

    The error, in this case, was caused due to a missing Creation Type on the activity suceeding the pending instance:

    Event Manager - Exmple 2 Broken Activity Message

    Tip

    This issue would have been encountered and resolved were the specific pending instance completed manually in some testing environment.

    How Do I Populate an Activity Using a CSV (comma separated value) File - Ungrouped Objects only?

    In this example, an activity with Creation Type set to First Activity has been designed with ungrouped objects (only), that are to be populated once a CSV file becomes available in the associated monitor path, and with the values contained in the file.

    Event Manager - Example 3 Activity Definition

    Event Definition - Activity Configuration

    The Activity Configuration on the associated Event Definition has been updated with the New activity name, File Attachment set, path to monitor updated and deleting the CSV file once successfully processed.

    Event Manager - Example 3 Activity Configuration

    The values in a corresponding CSV file need to be mapped to the objects on the activity for the Event Manager Service to populate the activity. objects can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item:

    Event Manager - Example 3 Add Objects

    Unnecessary objects can be removed by right-clicking on them and selecting the Remove Control option:

    Event Manager - Example 3 Remove Object

    The (column) values from the CSV file can be mapped using the following technique:

    Source Mapping 0 1 2 3 4
    Comma Separated Values ID Name Surname Job Description Phone Number

    Therefore, the source for object FB10_Field_0 should be 0:

    Event Manager - Example 3 Object 1

    And for object FB10_Field_1, the source should be 1:

    Event Manager - Example 3 Object 2

    The source for object FB10_Field_2 is 2, and 3 for object FB10_Field_3.

    Running the Event Manager Service

    Once the configuration is updated and saved, the service can be started in the Configuration Manager. Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution (with files matching the criteria), looks as follows:

    Event Manager - Example 3 Success

    The created process instance will be available for the next participant to complete. The activity completed by the service is displayed in the branch history, and will look similar to:

    Event Manager - Example 3 History

    The CSV file used to populate the activity instance will be deleted, as per configuration.

    How Do I Populate an Activity Using a CSV (comma separated value) File - Grouped Objects only?

    In this example, an activity with Creation Type set to First Activity has been designed with grouped objects, that are to be populated once a CSV file becomes available in the associated monitor path, and with the values over multiple rows contained in the file.

    Event Manager - Example 4 Activity Definition

    Event Definition - Activity Configuration

    The Activity Configuration on the associated Event Definition has been updated with the New activity name, File Attachment set, path to monitor updated and deleting the CSV file once successfully processed.

    The rows a corresponding CSV file need to be mapped to the Object Group on the activity for the Event Manager Service to populate the activity. Object Group can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item:

    Event Manager - Example 4 Add Object Group

    Note

    The Group Node and Repeating Node are left empty for CSV files as these apply to XML files only.

    Event Manager - Example 4 Object Group Configuration

    Grouped objects can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item on the Object Group:

    Event Manager - Example 4 Add Grouped Objects

    The rows and (column) values from the CSV file can be mapped using the following technique:

    Source Mapping 0 1 2 3 4
    Row 1 ID Name Surname Job Description Phone Number
    Row 2 ID Name Surname Job Description Phone Number
    Row 3 ID Name Surname Job Description Phone Number
    Row 4 ID Name Surname Job Description Phone Number

    Therefore, the source for object FB3010_Field_0 should be 0:

    Event Manager - Example 4 Grouped Object 1

    And for object FB3010_Field_1, the source should be 1:

    Event Manager - Example 3 Object 2

    The source for object FB3010_Field_2 is 2, and 3 for object FB3010_Field_3.

    Running the Event Manager Service

    Once the configuration is updated and saved, the service can be started in the Configuration Manager. Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution (with files matching the criteria), looks as follows:

    Event Manager - Example 4 Success

    The created process instance will be available for the next participant to complete. The activity completed by the service is displayed in the branch history, and will look similar to:

    Event Manager - Example 4 History

    The CSV file used to populate the activity instance will be deleted, as per configuration.

    How Do I Populate an Activity Using an XML File - Ungrouped and Grouped Objects?

    In this example, an activity with Creation Type set to First Activity has been designed with ungrouped and grouped objects, that are to be populated once an XML file becomes available in the associated monitor path, and with the values over multiple elements contained in the file.

    Event Manager - Example 5 Activity Definition

    The XML file that will be used to populate the activity repeats the element transaction under statement and will be used to populate the grouped objects, the remaining elements will be used to populate the ungrouped objects:

    <accountstatement>
      <statementdate>2016/01/07</statementdate>
      <account>123456789</account>
      <accounttype>Loan</accounttype>
      <interestrate>16.25%</interestrate>
      <openingbalance>33562.55</openingbalance>
      <statement>
        <transaction>
          <date>2016/07/01</date>
          <description>Admin Fee</description>
          <debit>57.00</debit>
          <credit>0.00</credit>
          <balance>33619.55</balance>
        </transaction>
        <transaction>
          <date>2016/07/01</date>
          <description>Interest</description>
          <debit>455.26</debit>
          <credit>0.00</credit>
          <balance>34074.81</balance>
        </transaction>
        <!-- more transactions -->
      </statement>
    </accountstatement>
    
    Event Definition - Activity Configuration

    The Activity Configuration on the associated Event Definition has been updated with the New activity name, File Attachment set, path to monitor updated and moving the XML file to the specified path once successfully processed. The Group Node is updated with the root element name, accountstatement, to indicate that its contained (child) elements are to be imported.

    Event Manager - Example 5 Activity Configuration

    Objects can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item:

    Event Manager - Example 5 Add Objects

    Unnecessary objects can be removed by right-clicking on them and selecting the Remove Control option:

    Event Manager - Example 5 Remove Object

    Per (ungrouped) object provide the Source value based on corresponding element name:

    <accountstatement>
      <statementdate>2016/01/07</statementdate>
      <account>123456789</account>
      <accounttype>Loan</accounttype>
      <interestrate>16.25%</interestrate>
      <openingbalance>33562.55</openingbalance>
    

    Therefore, the source for object FB50_StatementDate should be statementdate:

    Event Manager - Example 5 Object 1

    And for object FB50_AccountNumber, the source should be account:

    Event Manager - Example 5 Object 2

    The source for object FB50_AccountType is accounttype, interestrate for object FB50_InterestRate and openingbalance for object FB50_OpeningBalance.

    Object Group can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item:

    Event Manager - Example 5 Add Object Group

    For the Object Group, specify the Group Node and Repeating Node for the elements:

      <statement>
          <transaction>...</transaction>
          <transaction>...</transaction>
          <transaction>...</transaction>
      </statement>
    

    Event Manager - Example 5 Object Group Configuration

    Grouped objects can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item on the Object Group:

    Event Manager - Example 5 Add Grouped Objects

    Per (grouped) object provide the Source value based on corresponding element name:

        <transaction>
          <date>2016/07/01</date>
          <description>Admin Fee</description>
          <debit>57.00</debit>
          <credit>0.00</credit>
          <balance>33619.55</balance>
        </transaction>
    

    Therefore, the source for object FB5010_Date should be date:

    Event Manager - Example 5 Grouped Object 1

    And for object FB5010_Description, the source should be description:

    Event Manager - Example 5 Grouped Object 2

    The source for object FB5010_Debit is debit, credit for object FB5010_Credit and balance for object FB5010_Balance.

    Running the Event Manager Service

    Once the configuration is updated and saved, the service can be started in the Configuration Manager. Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution (with files matching the criteria), looks as follows:

    Event Manager - Example 5 Success

    The created process instance will be available for the next participant to complete. The activity completed by the service is displayed in the branch history, and will look similar to:

    Event Manager - Example 5 History

    The XML file used to populate the activity instance will be moved, as per configuration.

    Time Based Events

    The time-based event type expresses an event type relating a preconfigured occurrence in time, the event, with a configured outcome, starting a process at some specific point in time.

    All examples in this section will reference an activity with Creation Type set to First Activity with a single Command Option:

    Event Manager - Time Activity

    The time-based events are located in the Time Based Events tab in the Configuration Manager. A new time-based event definition is created by right-clicking the Event Definition node in the Time Based Events pane, adding a new one accordingly:

    Event Manager - Add Time-Based Event

    Additional Design Considerations for Time Based Events

    In addition to the design considerations discussed earlier, time-based events only support specifying the Command Option that must be selected on the activity for starting the associated process - none of the other available objects can be populated.

    Activity Configuration

    The Activity Configuration screen is displayed next to the associated event definition with default layout similar to the following (the Start Date and End by date initialized with the current date):

    Event Manager - Time Activity Configuration

    Activity

    The name of the activity that should be triggered once a specific point in time conforms to the criteria (defined next). Select the applicable activity - the name of the event definition will be updated to reflect this.

    Event Manager - Time-Based Activity

    Important

    The user account configured for the Event Manager Service must have access to the specific activity.

    Type Activities available (in Active Processes)
    New Any activity with Creation Type set to First Activity
    Range of recurrence

    The Range of recurrence section defines the range in which the associated event is considered active (or alternatively, recurring, depending on the pattern defined in a later section), with a standard Start Date and Start Time, as well as options for potentially ending the recurrent range.

    Event Manager - Time Recurrence Range

    The Start Date, in conjunction with the Start Time, specifies when this time-based event definition will start its lifecycle.

    Note

    The first occurrence of any time-based event will be calculated relative to the selected start date and time combination.

    Important

    If the Event Manager Service is stopped at a point in time and started again at a later point in time, the time-based events will play catch-up, starting process instances missed during this service inactivity period.

    Time Based Configuration Service Stopped Service Started Outcome
    1x Event Hourly Yesterday evening @ 8pm Today @ 6am 10 New Process Stated
    1x Event Daily @ 9am Friday afternoon @ 4pm Monday morning @ 10am 3 New Processes Started

    The time based event may be configured to end:

    • Never - by selecting No end date,
    • On a specifc date, by specifying an End by date, or
    • After a certain number of occurrences - once this number has been exceeded, the event will be marked as completed and removed from the list of active events.

      Note

      If the Event Manager Service misses an occurrence (due to not running), the number of occurrences left will not be decreased - the next viable date will be calculated and the event triggered accordingly.

    Range of pattern

    The Range of pattern section configures the pattern on which the event occurs.

    Note

    The time-based event will repeat this pattern for the duration of its lifecycle as specified in its range of recurrence.

    Hourly

    Event Manager - Time Pattern Hourly

    • Every (x) hour(s)

      The time-based event will be triggered every (x) number of hours.

    Daily

    Event Manager - Time Pattern Daily

    • Every (x) day(s)

      The time-based event will be triggered every (x) number of days.

    • Every weekday

      The time-based event will be triggered on every week day (that is, Monday to Friday).

    Weekly

    Event Manager - Time Pattern Weekly

    • Recur every (x) weeks on:

      The time-based event will be triggered every (x) weeks, and on the days of the week selected.

    Monthly

    Event Manager - Time Pattern Monthly

    • Day (x) of every (y) month(s)

      The time-based event will be triggered every day (x) of every (y) months.

    • The (x) (y) of every (z) month(s)

      The time-based event will be triggered on the (x) occurrence of day (y) of every (z) months.

    Yearly

    Event Manager - Time Pattern Yearly

    • Every (x) (y)

      The time-based event will be triggered yearly on day (y) of month (x).

    • The (x) (y) of (z)

      The time-based event will be triggered yearly on the (x) occurrence of day (y) of month (z).

    Troubleshooting

    Once the configuration is updated and saved, the Event Manager Service can be started in the Configuration Manager. When the calculated time expires, the associated process should have been started by the service.

    • The service failed to start the process

      If there are issues on the activity an error message will be logged similar to the following:

      Event Manager - Time Failed Activity

      In this particular case, an object was configured to require a value, that was not set by the service, as indicated by the associated message:

      Event Manager - Time Failed Activity Message

      Tip

      These type of issues would have been encountered and resolved were the specific activity completed manually in some testing environment.

    • No event triggered

      A time-based event did not conform to the predefined conditions (whether within the range of recurrence or the range of pattern did not apply). No errors will be logged:

      Event Manager - Time Failed No Event

    • Success

      Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution, looks as follows:

      Event Manager - Time Success

      The created process instance will be available for the next participant to complete. The activity completed by the service is displayed in the branch history, and will look similar to:

      Event Manager - Example 5 History

    Email Based Events

    The email-based event type expresses an event type relating a preconfigured mail box change, the event, with a configured outcome that includes starting a process or continuing a pending process instance. The process instantiation or continuation occurs as an email becomes available - the email can become part of the process instance by being associated with a File Attachment on an associated activity and/or part of the email being imported to objects on the activity.

    The email-based events are located in the Email Based Events tab in the Configuration Manager. A new email-based event definition is created by right-clicking the Event Definition node in the Email Based Events pane, adding a new one accordingly:

    Event Manager - Add Email-Based Event

    Activity Configuration

    The Activity Configuration screen is displayed next to the associated event definition with default layout similar to the following:

    Event Manager - Email Activity Configuration

    Activity Type

    A value that indicates whether a process instance will be instantiated, New, or continued, Pending, based on the availability of emails defined in the remaining sections.

    Important

    To continue a Pending process instance, the subject of the email must include the database id of the target pending activity instance associated with the process instance.

    Activity

    The name of the activity that should be triggered once an activity that conforms to the criteria (defined next) becomes available. Select the applicable activity - the name of the event definition will be updated to reflect this.

    Event Manager - Email Activity

    Important

    The user account configured for the Event Manager Service must have access to the specific activity.

    Type Activities available (in Active Processes)
    New Any activity with Creation Type set to First Activity
    Pending Any activity that the associated service user will participate on.

    Email Configuration

    The Email Configuration section configures the mailbox that will be monitored, including server configuration and authentication.

    Email Protocol

    The standard or method, utilised by the email server to define the communication channel, used to transmit information.

    Event Manager - Email Protocol

    Server Address

    The incoming mail server address for the mailbox to be monitored.

    Event Manager - Email Server Address

    A list of some of the popular email servers follows:

    Setting Gmail Outlook Office 365
    IMAP imap.gmail.com imap-mail.outlook.com outlook.office365.com
    Port 993 993 993
    Require SSL TRUE TRUE TRUE
    POP pop.gmail.com pop-mail.outlook.com outlook.office365.com
    Port 995 995 995
    Require SSL TRUE TRUE TRUE
    Important

    These accounts usually require an application specific password to work.

    Port & Secure Connection

    The transport layer protocol port that should be used to communicate with the email server being monitored. Selecting Secure Connection indicates that the email server being monitored is configured to use a secure connection.

    Event Manager - Email Port and Secure Connection

    Username and Password

    The username and password that should be used to identify the email client at the server. In most cases this is an email address and an associated password.

    Event Manager - Email Credentials

    Important

    Account access that requires two-step verification will need to supplement the password with an application specific password.

    Subject and Body Filter

    A text filter that are to be used to filter specific email messages by subject and/or body content.

    Event Manager - Email Filters

    Tip

    By not specifying a filter value, all emails will end up getting processed.

    Processed Action

    Indicates what should happen to a conforming email once it has been processed.

    Event Manager - Email Processed Action

    Note

    The specified Processed Action will only be applied once the associated event is successfully triggered.

    • None

      The email message will be marked as read and no additional action will be taken.

      Warning

      The next time the service timer elapse, all email messages previously processed will be processed again.

    • Delete email message

      The email message will be deleted on the server once the event is triggered.

    • Move email message

      Moves a processed email message to the specified folder within the mailbox.

      Event Manager - Move Email

      Important

      The folder must already exist on the server

      Event Manager - Outlook Folder

    How do I Start or Continue a Process Using an Email Message?

    In this example, an activity with Creation Type set to First Activity has been designed with objects to capture the data from an email message once it is received, starting or continuing the associated process, with a single Command Option:

    Event Manager - Email-Based Activity

    The Email Configuration section is assumed to be completed.

    Event Definition - Activity Configuration

    Supported email fields on a received email message need to be mapped to the objects on the activity for the Event Manager Service to populate the activity. objects can be added one-by-one, or all at once by selecting the appropriate (right-click) context menu item:

    Event Manager - Email Example Add Objects

    Unnecessary objects can be removed by right-clicking on them and selecting the Remove Control option:

    Event Manager - Email Example Remove Object

    The following table details the supported email fields that can be extracted from an email message:

    Source Data Type Object Target
    From Address Text Simple Text Box EM10_From
    To Address Text Simple Text Box EM10_To
    CC Address Text Simple Text Box EM10_CC
    BCC Address Text Simple Text Box EM10_BCC
    Date Received Date Simple Text Box or Date Picker EM10_ReceivedDate and EM10_ReceivedDateText
    Message Subject Text Simple Text Box EM10_Subject
    Message Body (Plain) Text Large Text Box EM10_BodyPlain
    Message Attachments Attachment File Attachment EM10_Attachments
    Message EML File Attachment File Attachment EM10_MimeFile

    Event Manager - Mapping Objects

    Important

    The associated File Attachment objects should be configured to allow for multiple attachments.

    Running the Event Manager Service

    Once the configuration is updated and saved, the service can be started in the Configuration Manager. Typical information logged to the Windows Event Log for running the service with Debug Service enabled, upon successful execution (with emails matching the criteria), looks as follows:

    Event Manager - Email Example Success

    The created process instance will be available for the next participant to complete. The activity completed by the service is displayed in the branch history, and will look similar to:

    Event Manager - Email Example History

    Troubleshooting

    Once the configuration is updated and saved, the Event Manager Service can be started in the Configuration Manager. On receiving email messages, the associated processes should have been started or continued by the service.

    • Connection to the email server

      There may be numerous reasons for the connection to the email server to fail, including:

      • incorrect email server address for the associated mail protocol, as an example, the following configuration:

      Event Manager - Email Incorrect Address

      should result in an error such as:

      Event Manager - Email Incorrect Address Error

      with message:

      Event Manager - Email Incorrect Address Error Message

      • incorrect port and/or Secure Connection, as an example, the following configuration:

      Event Manager - Email Incorrect Connection

      should result in an error such as:

      Event Manager - Email Service Connection Failed

      with message:

      Event Manager - Email Service Connection Failed Message

      • Invalid credentials will result in an error such as:

      Event Manager - Email Invalid Credentials Error

      with message:

      Event Manager - Email Invalid Credentials Error Message

    • The service fails to start or continue processes

      If there are issues on the activity an error message will be logged similar to the following:

      Event Manager - Email Failed Activity

      In this particular case, an object was configured to require a value, that was not set by the service, as indicated by the associated message:

      Event Manager - Email Failed Activity Message

      Tip

      These type of issues would have been encountered and resolved were the specific activity completed manually in some testing environment.

    • No event triggerd

      The provided criteria may result in none of the email messages getting processed, and no errors are logged:

      Event Manager - Email Failed No Event

    • Processed Actions failing

      The Processed Action might have been configured to move the email to non-existing folder causing the following error:

      Event Manager - Email Action Failing

      with message:

      Event Manager - Email Action Failing Message

    Troubleshooting the Event Manager Service

    Windows Event Log

    Every Event Manager Service will log messages to the FlowCentric Event Log. Each of these messages can be viewed in the Configuration Manager, grouped by service. The Event Manager Service can provide more detailed information by enabling the Debug Service option on the service's configuration.

    Service User Access Rights

    File System Access

    The service account, under which the Event Manager Service executes, requires read and write access to any folders that it should monitor and write to.

    Processware Access

    The user account with which the Event Manager Service is to access an Activity Server must be a valid Processware User, active, available and with an associated Role.

    Machine Access

    The service account, under which the Event Manager Service executes, requires read access to the machine's RSA key container in order to encrypt the content stored in its configuration. The Event Manager Service installer grants appropriate access to the associated service account and is the preferred way of changing the associated service account (via re-installation of the Event Manager Service). To manually set up the access rights for the service account, the following command needs to be executed in an elevated Command Prompt:

    %WINDIR%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -pa "NetFrameworkConfigurationKey" "domain\user"

    Back to top Copyright © FlowCentric Technologies (PTY) Ltd - Processware Developer Guide