Connector for Event Emails

The Alemba Email Event Connector is implemented to generate calls or requests in vFire from 3rd party event tools that send event notifications by email. Fields in the generated calls and requests are populated with data from the emails. A configuration XML file defines field mappings between the template and the contents of event emails.

This section of the documentation describes the details of the connector and how to configure it to extract data from incoming emails, including:

  • The name of the .NET assembly file
  • Connection methodology
  • The requirements involved in the handling of Event Management between vFire Core and the incoming emails.

For compatibility and version support details, refer to the Fire Connector Matrix.

Use Case Scenario

Purpose

An organization receives emails from a 3rd party application to notify them of an event.

Role

The role of this connector is to pass parameters from the email into calls or requests in vFire.

Connector Description

The table below provides a description of the connector.

Information fields

Name

Connector

Emails -> vFire Core 9.x Connector

Third-party application

any supported email applications

Assembly

Alemba.Connector.Email.dll

Configuration file

Alemba.Connector.Email.xml
Configuration GUI Alemba.Connector.Email.Config.exe

Connection methodology

not applicable

Connection Parameters

The connection parameters for this connector are contained within an XML file on the application server where vFire is installed. This file must be mapped to the connector Source.

Connection parameters

Description
Incoming Email Source The incoming email server source configured in System Admin, to be used by the connector.

Configuration File

The file path and name of the XML file which contains the connection details and parameters for the connector. Required.

Licensing

This connector is not licensed software and can be used free of charge as part of the vFire Core license.

Installation

No install is required for this connector. Upon install or upgrade to vFire Core 9.9 or higher, this connector is visible in the Integration module, ready to be configured.

User Diagnostics

The connector has the facility to trace information. The data can be obtained through Polling tracing or Application tracing.

Additional Information

This connector does not include any Federated CMDB population functionality.

Connector Operation

Overview

To make the Alemba Event Email Connector work, you must:

  1. Set up an Incoming Email Server in vFire Core
  2. Configure an Integration Source for the Email Connector
  3. Configure the XML file
  4. Create an Integration Event Mapping

 

Set up an Incoming Email Server in vFire Core

  1. Follow the steps detailed in the Email Settings topic to create an incoming email server in vFire Core that will be used by the Email Connector to retrieve emails and create calls.
  2. Enter the details of the server and email account that will receive event emails from the third party application.

    3. The Call Template field in the Email Settings is ignored by the connector, which instead uses the Using template field in the Event Type Mapping Details window.

  3. In the settings for the incoming email server in vFire Core, the Active checkbox must be unselected.

    4. Conflicts will occur if the mail server is not set to be inactive in the Email Settings.

  4. Continue completing the settings for the incoming email server in vFire Core, as instructed in the Email Settings topic.
  5. Select to save the changes.

Configure an Integration Source for the Email Connector

  1. Select and then Admin. From the submenu, select Integration.
  1. Select the Sources option from the explorer pane.
  2. Select the button on the toolbar. In the pop up window, select Alemba Email Event Connector from the drop-down list.
  3. In the Integration Source Details window, complete the details.

    4. Name Key in a name for the integration source. Required.
    Status This field is pre-filled with the Active status.
    Connector This field is pre-filled with the Connector type.
    Assembly.TypeName This field is pre-filled based on the selected connector as defined in the Connector DLL. Read-only.
    Incoming Email Source

    Use the drop down to select the Incoming Email Server, configured in Email Settings in System Admin, that will receive the event emails. The connector will regularly check the inbox of that mail account.

    The account configured in Email Settings must be set to Inactive.

    Configuration File

    The file path and name of the XML file which contains the field mappings for the connector. Required.

  4. Select to save the changes.

Configure the XML file

An executable has been provided to assist in the configuration of the Alemba.Connector.Email.xml file, where the field mappings are defined.

  1. Run the configuration GUI
    • Log onto the vFire web server, if you're not already logged on
    • Navigate to the vFire root folder and run Alemba.Connector.Email.Config.exe

      • C:\Program Files\Alemba\vFire\Alemba.Connector.Email.Config.exe

    • The vFire Email Event Connector Config window opens

      • On first-time configuration, the GUI opens with a simple email example to demonstrate how the configuration tool works. The XML file is pre-configured with field mappings for the example email. To see the example field mappings, press and select the file Alemba.Connector.Email.xml.

  2. Configure the settings:
System Select the system configured with the Email Connector Source. The default system is selected by default.
Incoming Email Select the incoming mail account configured in the Email Settings window in System Admin, that will receive the event emails.

The selected mail account must be set to Inactive in the Email Settings.
After selecting the System and Incoming Email, press

Press to display the contents of the first email in the inbox.

From The from address of the event email
Subject The subject of the event email
Body The body of the event email
Headers The email header information contained in the event email

If no email contents are displayed, the settings may be incorrect, or there is no email in the inbox.

Save the configured System and Incoming Email settings.
Configs

Use the Configs table to create field mappings between the event emails and the fields in the Call Template linked to the mail account in the Email Settings. Complete a row for each field to be mapped, configuring the columns as follows:

Field The field name in the call template
Type Select the type of field from the list
Source Select the source from the list
Header Enter the Name of the record in the Headers section to extract data from, if
Expression

Define a formula, based on Regular Expression parsing, to extract the required parameters from the event email.

The email contains UserID: 123

Therefore the expression would be defined as UserID: (?<timeMin>\d+)

And the extracted value is 123
Date Format

Enter a format if DateTime was selected as the Type. If blank, will default to the server format. Leave this field blank if Date/Time was not selected as the Type.

dd/MM/yyyy

Default Enter a value to use as default if none can be extracted from the email.
Test This column displays the value that will be extracted from the email using the configured settings. To run the test, press .

Press to test the field mapping configuration. The outcome for each configured field (row) is displayed in the Test column.
  1. Press to save the field mapping settings to the XML file.

    2. Ensure you have the correct account permissions required to modify the XML file.

Create an Integration Event Mapping

Before you start

If the Event Management checkbox in the Integration Platform administration screen is selected, the Event Management functionality starts running as soon as a proper Event Mapping is saved. When starting, the connector checks the configured database table and logs a call or request for every item that is present and fulfills the criteria that are implemented in the Event mapping. This could lead to a large number of calls/requests being created when activating the Event Management functionality.

One solution to avoid this behavior is to include in the Event criteria setting an item based on a date attribute. For example, you could plan to “go live” with Event management on a precise date and, as a consequence, specify that the value of date field in the external table has to be after this date before any action can be triggered in vFire Core.

  1. Follow the steps detailed in the Managing Event Type Mappings topic to create an event mapping for the Email Connector.
  2. For this connector the Incoming Transaction settings in the Action tab will have the following results:
    3. When Updated externally

    This transaction is used when an email is received that has the same subject as a previous email that already generated a call or request through the connector. The action that is selected from the dropdown list determines what happens to the existing call or request.

    Close This action has no effect on the existing call or request.
    Update Updates the existing call or request, updating mapped field values (if needed) and writes an 'update' entry into the call or request history.
    Add Note Adds a note to the existing call or request's history. Mapped fields are not updated.
    Take no action This action has no effect on the existing call or request.
    When Updated externally and Call or Request is closed

    This transaction is used when an email is received that has the same subject as a previous email that already generated a call or request through the connector, and that call or request is closed. The action that is selected from the dropdown list determines what happens to the existing call or request.

    Re-open Reopens the closed call or request, updates mapped field values (if needed) and writes an 'update' entry into the call or request history.
    Log new and link existing Logs a new call or request and links it to the closed call.
    Add Note Adds a note to the closed call or request's history. Mapped fields are not updated.
    Take no action This action has no effect on the existing call or request.
    When Notified externally This transaction is not used by this connector and can be ignored.
    When Notified externally and Call or Request is closed This transaction is not used by this connector and can be ignored.
    When Resolved externally This transaction is not used by this connector and can be ignored.
    When Resolved externally and Call or Request is closed This transaction is not used by this connector and can be ignored.
    When Deleted externally

    This transaction is used when a new email is found in the inbox, and a call or request is generated by the connector for the event. The action that is selected from the dropdown list determines what happens to the call or request at the time it is created.

    Close Logs the call or request and then immediately closes it
    Update Logs the call or request and then adds a note to the history
    Add Note Logs the call or request and then adds a note to the history
    Take no action No call or request is logged
    When Deleted externally and Call or Request is closed This transaction is not used by this connector and can be ignored.
  1. Continue completing the settings for the Event Mapping, as instructed in the Managing Event Type Mappings topic.
  2. Select to save the changes.