Email Event Connector

The Alemba® Email Event Connector is implemented to generate calls or requests in Alemba Service Manager™ 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. New calls or requests are created from emails with unique Subjects. Existing event calls or requests are updated from emails with Subjects matching previously received 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 ASM Core and the incoming emails.

For compatibility and version support details, refer to the ASM 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 ASM.

Connector Description

The table below provides a description of the connector.

Information fields

Name

Connector

Emails -> ASM Core 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 ASM 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.

Installation

No install is required for this connector. Upon ASM Core install, this connector is visible in the Integration module, ready to be configured.

Additional Information

This connector does not include any Federated CMDB population functionality.

Connector Operation

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

Set up an Incoming Email Server in ASM Core
Configure an Integration Source for the Email Event Connector
Configure the XML file
Create an Integration Event Mapping

Set up an Incoming Email Server in ASM Core

Follow the steps detailed in the Email Settings topic to create an incoming email server in ASM Core that will be used by the Email Connector to retrieve emails and create calls or requests.
Enter the details of the server and email account that will receive event emails from the third party application.
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.
In the settings for the incoming email server in ASM Core, the Active checkbox must be unselected.
Conflicts will occur if the mail server is not set to be inactive in the Email Settings.
Continue completing the settings for the incoming email server in ASM Core, as instructed in the Email Settings topic.
Select to save the changes.

Configure an Integration Source for the Email Event Connector

Select ≡ > Admin > Integration.
In the Explorer pane, under Integration, select Sources.
Select the button on the toolbar. In the pop up window, select Alemba® Email Event Connector from the drop-down list.
In the Integration Source Details window, complete the details.

Name

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

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.

Run the configuration GUI
- Log onto the ASM web server, if you're not already logged on
- Navigate to the ASM root folder and run Alemba®.Connector.Email.Config.exe
- C:\Program Files\Alemba\ASM\Alemba®.Connector.Email.Config.exe
- The ASM 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, select Open and select the file Alemba®.Connector.Email.xml.
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.

Connect

After selecting the System and Incoming Email, press 'Connect'

Get Email

select 'Get Email' to display the contents of the first email in the inbox.

From - The from address of the email

Subject - The subject of the email

Body- The body of the email

Headers - The header information contained in the email

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

Save Data

Save the configured System and Incoming Email settings.

Configs

Use the Configs table to create fields for each unit of data you want imported into ASM from the emails. Fields created here appear as selectable Event Fields in the Incoming tab of the Event Type Mappings Details screen. Create a row for each field to be mapped to a field in a ASM call or request, configuring the columns as follows:

Field - The name of the field to display in the Event Fields column in the Incoming tab of the Event Type Mappings Details screen in ASM.
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 applicable.
Expression - Define a formula, based on Regular Expression parsing, to extract the required parameters from the email.
The email contains UserID: 123
Therefore the expression would be defined as UserID: (?<value>.+) 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, select .

Test

Test the field mapping configuration. The outcome for each configured field (row) appears in the Test column.

Select Save to save the field mapping settings to the XML file.
Ensure you have the correct account permissions required to modify the XML file.

Create an Integration Event Mapping

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 ASM Core.

Follow the steps detailed in the Managing Event Type Mappings topic, up to the section that describes the Actions tab.
In the Actions tab, it is recommended to select Update as the action for "When Deleted externally". For more information refer below - Configuring the Actions Tab.
After the Actions tab is configured, continue completing the settings for the Event Mapping as instructed in the Managing Event Type Mappings topic.
Select to save the changes.

Configuring the Actions Tab

Settings defined in the Actions tab of the Event Type Mappings will have a significant impact on calls and requests created by the connector.

New calls or requests are created when the connector finds an email with a unique Subject.

Existing calls or requests created from event emails, are updated when the connector finds an email with a Subject that was previously processed.

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.

Reopen- 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