Instant Email to IM Gateway for Microsoft Lync · 2015-04-26 · Instant Technologies February 2013...

Instant Technologies

February 2013

Instant Email to IM

Gateway for Microsoft Lync Installation and Overview Guide

Instant Technologies

Instant Email to IM Gateway

Page 1 Copyright © 2013 Instant Technologies. All rights reserved. PMM February 13, 2013

Copyright and Disclaimer

This document, as well as the software described in it, is furnished under license of the Instant Technologies Software Evaluation Agreement and may be used or copied only in accordance with the terms of such license. The content of this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Instant Technologies. Instant Technologies assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. All information in this document is confidential and proprietary.

Except as permitted by the Software Evaluation Agreement, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Instant Technologies .

Copyright © 2013 Instant Technologies, All rights reserved.

Trademarks

All other trademarks are the property of their respective owners.

Contact Information

Visit our Website for Customer Support information.

http://www.instant-tech.com/

http://www.instant-tech.com/



Contents

Introduction .................................................................................................................................................. 3

System Requirements and Installation of Core Components ....................................................................... 3

Installation Prerequisites .......................................................................................................................... 3

Server Requirements: ........................................................................................................................... 3

Other Requirements: ............................................................................................................................ 3

Steps Prior to Running the Installation Process ........................................................................................ 4

Configure Database Tables for Logging and Metrics ................................................................................ 4

Trusted Application Setup......................................................................................................................... 4

Creating an MX Record for the IM Gateway ............................................................................................. 5

Creating AD Contacts for Microsoft Lync Group Chat Rooms .................................................................. 6

Installation of IM Gateway Server and Dashboard ....................................................................................... 8

Installing the IM Gateway Service............................................................................................................. 8

Configure the IM Gateway Service ........................................................................................................... 8

Installing the IM Gateway Dashboard .................................................................................................... 11

Configure the IM Gateway Dashboard ................................................................................................... 12

IM Gateway Usage ...................................................................................................................................... 14

Sending an Email to a Chat Room ........................................................................................................... 14

Sending Email with Importance to Chat Room ....................................................................................... 16

Sending Email with Attachments ............................................................................................................ 16

Sending Emails with URL Link(s) ............................................................................................................. 17

Sending an IM to a User by Email ........................................................................................................... 19

Sending an IM to a Group of Users ......................................................................................................... 21

Sending IM Messages on Behalf of the Sender ...................................................................................... 21

Email Response to Sender....................................................................................................................... 21

Instant IM Gateway Dashboard .................................................................................................................. 23

Basic Statistics ......................................................................................................................................... 23

Incoming Messages ................................................................................................................................. 24

Group Chat Messages ............................................................................................................................. 24

Top Recipients ......................................................................................................................................... 25

Traffic Logs: Incoming Messages ............................................................................................................ 25



Introduction

These notes briefly describe the installation procedure required to install the Instant Email to IM

Gateway application. This application provides a system to receive and convert inbound email

notifications to Microsoft Lync based IM alerts and notifications. Inbound email alerts may be

addressed and delivered to individuals, groups, and Microsoft Lync Group Chat rooms.

At a high level, the system includes the following components:

Instant SMTP gateway server that will be responsible for receiving, and processing, the email

based notification requests. This server will be configured and accessed using a set of MX

records. This engine will convert the inbound email notification to a set of IM based alerts.

The core alerting service responsible for dispatching the IM based alerts to individuals or a

group chat room

A dashboard and reporting system to display and collect statistics on the system

The installation process will not require any additional software to be installed on your Microsoft Lync

server. However, the installation will require the installation of the Instant IM Gateway server, the

configuration of a Lync trusted application pool (or usage of a Lync trusted application pool), an existing

installation of the Instant Alert Manager, as well as access to instances of both Active Directory and

Microsoft SQL Server.

System Requirements and Installation of Core Components

Installation Prerequisites

Server Requirements:

x64 Windows 7 or Server 2008 OS

Microsoft Lync 2010 UCMA 3.0 TrustedApplicationPool

.Net Framework 4.0

UCMA 3.0 Core Components

Other Requirements:

Instant Alert Manager for Microsoft Lync (http://www.instant-tech.com/Alert_Manager.cfm)

Microsoft SQL Server 2008 (for logging & reporting)

Active Directory domain controller

http://www.instant-tech.com/Alert_Manager.cfm



Steps Prior to Running the Installation Process The Instant Email to IM Gateway application will be installed primarily on one server. However, prior to

initiating the installation, the following steps should be performed and verified:

o Verify the various server components (i.e. the version of the Microsoft .Net runtime) are

installed and sufficient

o Verify that an existing instance of Instant Alert Manager is configured and running

o Configure the database for logging (using the provided scripts)

o Create and configure the trusted application pool – as well as the trusted application

‘imgateway’

o Create and configure the MX record

o Configure one or more target chat rooms using Active Directory (Optional)

o Create a new exchange user in Active Directory (an email enabled user) that will be used by the

Gateway server to send email acknowledgements

o Retrieve the GroupChat URI currently in use as part of the Lync 2010 Group Chat installation

Configure Database Tables for Logging and Metrics Follow the steps below to install the logging and reporting database for the Instant Email to IM

Gateway. These tables will be populated with the usage statistics and metrics from the IM gateway.

The IM Gateway Dashboard application relies on these tables and the tables should be created prior to

initiating the installation process.

1. Extract “IMGatewayDb.sql” from the installation package.

2. Using SQL Server Management Studio, connect to the instance of SQL Server which will host the

database.

3. Open “IMGatewayDb.sql” in a new query window. Execute the script to create the database. If

you encounter errors, you may need elevated permissions. Consult with your DBA.

Trusted Application Setup In order to dispatch inbound email notifications to the designated Lync Chat Room, it is necessary to

create, or use, a Lync trusted application pool. In order to perform the steps necessary to provision a

UCMA TrustedAppPool and TrustedApplication for the IM Gateway Service to utilize, please follow this

Microsoft MSDN article:

(http://msdn.microsoft.com/en-us/library/lync/hh347354(v=office.14).aspx )

For instance, you will want to create a new trusted application on this server, typically, the trusted

application will be named ‘imgateway’.

NOTE: In some cases, this application may be installed on the same server as an existing Instant Alert

Manager application. In this case, a new trusted application instance will still need to be created – since

the gateway application needs a unique trusted application instance.

http://msdn.microsoft.com/en-us/library/lync/hh347354(v=office.14).aspx



Creating an MX Record for the IM Gateway In order to provide the necessary internal email addressing information, the IM Gateway requires a Mail

Exchanger (MX) record be setup on the Domain Controller. This should be the Domain Controller

corresponding with your email address domain. Typically, this new MX record will provide a new child

domain address (for example: im.instant-tech.com), in order to receive all inbound email traffic

addressed to the new im Subdomain.

1.) On the Domain Controller, open DNS Manager.

2.) Expand the proper domain controller node. Underneath there should be a node name Forward

Lookup Zones. Underneath this you will find a list of domains. Select the domain corresponding

to the email domain that you would like to use the IM Gateway to IM-enable.

3.) Right-click in the main pane and select New Mail Exchanger (MX)… In the child domain input,

enter im. Thus, if the parent domain is contoso.com, the second input should then read

im.contoso.com. Enter the FQDN of the server which will run the IM Gateway in the third input.

Leave the priority field at the default.



4.) With the MX record in place, emails addressed to the new im subdomain will now be routed to

the Instant IM Gateway server.

Creating AD Contacts for Microsoft Lync Group Chat Rooms The IM Gateway requires that an Active Directory Contact object be created for each chat room that will

be email-enabled. Therefore, there should be one contact object created for each chat room that will

be enabled for inbound email notifications. This mapping structure may be updated at any time and the

system will query the Active Directory system in real time as new inbound emails are received.

The steps below are necessary in order to properly enable a chat room for the IM Gateway service.

1.) Connect to the Domain Controller and open Active Directory Users and Computers.

2.) Expand the appropriate domain and select Users from the left pane.

3.) Right-click and select New->Contact.

4.) Fill in the fields in the resultant dialog. Be sure to enter the name of the chat room in the

Display Name field exactly. Select OK to close the dialog.

5.) Double-click the newly created contact in the main pane to open the properties dialog. Verify

that the Display Name matches the chat room name exactly.

6.) Enter “Chat Room” as the description.

7.) Assign an email address to the chat room and click OK to save these changes.

NOTE: this should NOT be an im address.



8.) Repeat these steps for each chat room to be enabled.

The following screen shot demonstrates how an email enabled chat room might appear in Active

Directory.

The contact properties dialog will require both a first name and a last name field. However, the only

three fields that are utilized by the Instant gateway are:

Field Purpose

Display Name The name of the Lync 2010 chat room

Description In order to identify this contact record as a chat room object, the description must contain the text of: Chat Room

E-mail This is the inbound email address of the chat room and should not include the subdomain (i.e. IM)

The following screen shot demonstrates how this Lync 2010 chat room may appear in the Microsoft

Lync Group Chat application:



Installation of IM Gateway Server and Dashboard

Installing the IM Gateway Service 1.) Extract “EmailIMGatewaySetup.zip” from the installation package.

NOTE: It is recommended that this zip be extracted to its own subdirectory, to avoid any

potential file collisions with other installer packages.

2.) Execute the extracted setup.exe.

3.) Click through the installer. You will be prompted to accept the software license, and presented

the option to change the default installation location if you so choose. You will be prompted for

the username and password of the account under which the service will run.

See (http://msdn.microsoft.com/en-us/library/lync/hh347291(v=office.14).aspx) for the

appropriate group memberships for this account.

Configure the IM Gateway Service 1.) Once the installation has completed, close the installer. On the Start Menu, in Programs-

>Instant Technologies->IM Gateway open the shortcut “Configure IM Gateway” to configure

the settings for the IM Gateway. You should be prompted by UAC to give Administrator

credentials.

http://msdn.microsoft.com/en-us/library/lync/hh347291(v=office.14).aspx)



2.) On the first tab, input the path, username and password the IM Gateway will use to access

Active Directory. You may verify these settings using the Test Connection button.

NOTE: The path should be formed in LDAP format, e.g.LDAP://contoso.com, and the username

should be of the form DOMAIN\USERNAME.

3.) On the second tab, enter connection information for the Log database created prior to

installation, and for your pre-existing Alert Manager database.

You may verify these settings as well, before moving on.



4.) On the third tab, configure the service’s connection to the Lync and GroupChat servers. If you

have Powershell and the Lync Management Powershell Cmdlets installed, you may click Browse

Trusted Applications… to populate the Trusted Application settings from one of the available

Trusted Applications.

The GroupChat URI is a special SIP account created to lookup GroupChat rooms; contact your

GroupChat administrator/installer if you do not know it. The GroupChat URI was created for the

installation process of the Lync 2010 Group Chat server.

5.) On the final tab, configure the address and port that the IM Gateway service will utilize. The

address should match the MX record previously created. The port should be the default SMTP

port, 25. You also have the option of configuring the SMTP server and mail account that the IM



Gateway uses to send status notifications and acknowledge incoming mails.

6.) When you are finished, close the window. You will be prompted to save your changes; select

Yes.

7.) To start the service, open services.msc. Find Instant Email-To-IM-Gateway, and start the

service. If the service fails to start, examine the Logs subdirectory of the program directory, and

the EventViewer for any obvious errors.

Installing the IM Gateway Dashboard 1.) Extract “EmailIMGatewaySetup.zip” from the installation package.

NOTE: It is recommended that this zip be extracted to its own subdirectory, to avoid any

potential file collisions with other installer packages.



2.) Execute the extracted setup.exe.

3.) Click through the installer. You will be prompted to accept the software license, and presented

the option to change the default virtual directory and application pool. Be sure that the

selected application pool supports .NET 4.0.

Configure the IM Gateway Dashboard 1.) Once the installer has completed, open IIS Manager. Find the newly installed web application.

Under Authentication, ensure that Anonymous Authentication is disabled and Windows

Authentication is enabled.

2.) Browse to the site. You should see something similar to the screen shot below, with error

messages indicating that the database connections are incorrect.

3.) Select Database Settings from the left panel. Enter the connection information for the IM

Gateway Log database previously created, and for the AlertManager database. You may test

these settings with the Test Connection buttons. When you are finished, click the save button.



4.) Next, select Directory Settings from the left pane. Enter connection information for your Active

Directory server. You may test these settings using the Test Connection button. When you are

finished, click the save button.



5.) The IM Gateway Dashboard is now configured, and you should be able to access the charts and

record logs.

IM Gateway Usage

Sending an Email to a Chat Room To send a message to a chat room using the Instant IM Gateway, simply compose an email to the

address defined for the chat room, with the (im.) subdomain prepended to the domain. For instance, in

the screen shot below, a message is being sent to the Microsoft Development chat room, which is

defined in AD as [email protected]. The (im.) subdomain is essential to ensure

that the message is correctly routed to the IM Gateway server, rather than the normal mail server. In

the following example, the ‘To’ address of the email is: [email protected].

You have three options when sending a message to a chat room through the IM Gateway.

1.) A message with a subject, but no body, will appear in the chat room as a single line of text.

mailto:[email protected]



2.) A message with a body and no subject will also appear as a single line of text, unless the body

text exceeds the max length limit of the chat client. If this limit is exceeded, the chat will be

converted to a story.

3.) A message with subject and body will be displayed as a story, with the subject of the mail as the

subject of the story.

NOTE: When possible, emails should be sent as plain-text, not as HTML. The IM Gateway currently

supports HTML formatted email, but HTML is not rendered with the Lync 2010 Group Chat room.

Therefore, the IM Gateway will attempt parse the HTML contained within an email into a format suitable

for the Lync 2010 Chat Room.

The following screen shot demonstrates how a message will be displayed in the Group Chat room when

the message is consolidated to a Group Chat story:



In the event that an email contains a significant amount of information, then the email message will

automatically be split into different ‘stories’ and placed into the Lync Group Chat room as a collection of

‘parts’. For example, the following screen shot demonstrates several emails that have been submitted

to the chat room and they have been split across a collection of story segments:

Sending Email with Importance to Chat Room By default, the gateway supports the ability to convert emails marked with ‘importance’ to a similar

message in the Lync Group Chat room. So, if an email is marked as important, the message will be

dispatched to the chat room and flagged as important.

Sending Email with Attachments The gateway supports the ability to receive emails with attachments and the application will

automatically post attachments to the designated Microsoft Lync Group Chat room. Currently the

gateway does not support the ability to distribute attachments to individuals via the Lync IM protocol.

The following screen shots demonstrate sending an email with either one, or multiple attachments, to a

Group Chat room.



By default, the Lync Group Chat room may provide specific ‘hover’ behavior for certain types of files.

For example, the following screen shot demonstrates how an image might be rendered via a hover

action:

Sending Emails with URL Link(s) It is also possible to send an email to a chat room that contains hyperlinks. In many cases, the IM

Gateway server will attempt to map hyperlinks to the appropriate structure within the Lync Group Chat

room. The Lync Group Chat room will display the link as ‘clickable’ and the link will be represented with

a story structure. In many cases, the IM Gateway will attempt to parse the email message and identify



the various ‘link’ references. In order to explicitly indicate a link, please surround the link with the

<> characters.

The following screen shot demonstrates how to send a clickable link to the chat room – this is

accomplished by enclosing the link URL with <> characters.

The following screen shot demonstrates how the message will be displayed in the IT Support group chat

room:

When the story is expanded, or read, then the link will appear as a clickable entity:



Sending an IM to a User by Email You may send an IM to a user via email with the IM Gateway by composing an email to the user’s

normal email address, and then prepending the (im.) subdomain to the domain portion of the address.

In this example, the following IM will be sent to the user with the email address:

[email protected]. In this example, the IM Gateway server will receive the email (since the

mailto:[email protected]



subdomain im.instant.local was provided) and then the email will be converted to an IM message and

dispatched, using the user’s SIPURI, to the user in Active Directory who matches the user

[email protected].

These IM alerts are entirely one-way; responses to the messages will not be delivered to the sender of

the alert, and if a recipient attempts to reply, they will receive notification that their response will not be

delivered.



Sending an IM to a Group of Users In addition to sending an email, and thus an IM, to an individual user, the Instant IM Gateway has the

ability to dispatch messages to standard Microsoft Exchange distribution groups. So, the Instant IM

Gateway will expand the distribution list, stage the IM messages, and distribute the IM messages to all

users within the distribution group.

Distribution lists composed of Lync Group Chat rooms are not supported. In order to send a message to

multiple Lync Group Chat rooms, the rooms should be specified as unique email addresses in the email

message.

Sending IM Messages on Behalf of the Sender By default, the IM Gateway application will send messages, both to individuals and to the Microsoft Lync

Group Chat rooms, on behalf of the user who originally sent the email. In order to accomplish this

behavior, the IM Gateway server will impersonate the specified user (the person who originally sent the

email) via a login to the Microsoft Lync server. This login will take place using the Microsoft Lync

trusted application pool. So, as IM messages are dispatched to both individuals and Group Chat rooms,

they will appear to originate from the original email ‘sender’.

Email Response to Sender The IM Gateway will automatically acknowledge each email request by providing a return email

notification to the original email sender. This email acknowledgement will include information on the

status of the request and whether or not the user’s SIPURI was located.

The following return receipt indicates that the participant of the original message was located:

If the designated person was not located (i.e. their email address did not resolve against a user in Active

Directory and the system was not able to determine a SIPURI in Active Directory), then an email

message will be returned indicating that the user was not located in the directory.



For example, the following screen shot demonstrates an email message that is returned from the IM

Gateway server if the recipient is not located (i.e. their SIPURI was not located in Active Directory):



Instant IM Gateway Dashboard

The Instant IM Gateway provides a dashboard application in order to provide high level statistics and

additional information to administrators and system engineers. The dashboard is available using a

standard browser and provides information on overall IM Gateway usage statistics, various charts, and

traffic logs.

The dashboard is designed to provide a high level view of the system and provide information on

general IM gateway traffic patterns and usage.

Basic Statistics The following screen shot demonstrates the high level statistics area:

In addition to basic statistics, additional information is available in order to highlight traffic patterns and

help identify which users and group chat rooms are receiving inbound traffic.



Incoming Messages The Incoming Messages chart is designed to display inbound gateway traffic consolidated on a daily

basis:

Group Chat Messages The GroupChat Messages chart provides the total number of inbound gateway messages that have been

delivered to various Lync 2010 Group Chat rooms.



Top Recipients The Top Recipients chart provides an overview of which users, and chat rooms, are receiving the most

traffic:

Traffic Logs: Incoming Messages In addition to a variety of charts, and metrics, the Traffic Logs provide more detailed information on

both the inbound email messages as well as the status of the IM delivery.

Date post:	06-Aug-2020
Category:	Documents
Upload:	others
View:	2 times
Download:	0 times

Instant Email to IM Gateway for Microsoft Lync · 2015-04-26 · Instant Technologies February 2013...

Documents