Edit1 What is the Exchange Server Integration?
The integration allows e-mail sent to an Exchange Server mailbox to be processed based on commands entered in the e-mail subject and body. These commands can be used to create new items such as issues, update existing items, execute workflow transitions, and execute workflows.
Edit2 Basic Installation and Configuration
This sections installing and configuring the Exchange Server integration.
Edit2.1 System Requirements
The integration requires IssueNet 4.7 or greater and Exchange Server 2000 or greater.
Edit2.2 Installation
The required IssueNet software components are installed as an optional component of the IssueNet Suite installation package. The components are installed by default during a complete installation but can also be selected or unselected during a custom installation or modification of an existing installation.
Note: if you do not want to run the IssueNet Installation package on the Exchange Server, you can copy the required files from another computer on which IssueNet has been installed to a directory on the Exchange Server. The integration components are installed to the following sub-directory structure of the IssueNet installation directory. The default location is the C:\Program Files\Elsinore Technologies\IssueNet\Integrations\Exchange directory.
In addition to this readme, the following files are installed:
- Elsinore.Core.dll (core IssueNet platform component)
- Elsinore.Engine.dll (core IssueNet platform component)
- Elsinore.Exchange.dll (IssueNet platform Exchange integration component)
- Elsinore.MMFWebClient.dll(core IssueNet platform component)
- Elsinore.SQLClientEngine.dll(core IssueNet platform component)
- Elsinore.Exchange.dll.config (configuration file for integration options)
- regvent.vbs (Microsoft VB script for registration of Exchange store event sink)
- response.txt (provides configurable e-mail response for e-mail commands which cannot be processed)
- register.bat (registers the Elsinore.Exchange.dll and executes the regvent.vbs with mail domain and mailbox parameters)
Edit2.3 Configuration
Once the integration components are installed, the integration components must be registered and the integration must be configured to connect to an IssueNet database. To register the integration components, run the register.bat file from the command prompt on the Exchange server. This file will register the Elsinore.Exchange.dll and run the regvent.vbs script. When you run the .bat file you will be prompted to register or unregister the integration for a specific mail domain and mailbox. For more detailed information on and options please consult he comments in the .bat file.
To configure the integration for a specific IssueNet database, open the Elsinore.Exchange.dll.config and enter the name of an IssueNet connection as the value of ConnectionName. An IssueNet connection profile must be defined on the server. There are two ways to define IssueNet connection profiles on the server:
- Copy an IssueNet connections.xml and datasources.xml from a computer which has the desired connection profiles and place them in the directory with the other integration files. The connections.xml and datasources.xml are typically located in the C:\Documents and Settings\All Users\Application Data\Elsinore Technologies directory.
- Perform an IssueNet client or server installation on the Exchange Server and define the necessary connection profiles using a client application such as the IssueNet Manager Once the integration is registered and the Elsinore.Exchange.dll.config is configured for a valid connection profile the integration is ready to use.
Edit3 Using the Integration
Once the integration is configured, Exchange server will process e-mail sent to the specified inbox and perform actions in IssueNet based on the commands contained in the e-mail subject and parameters body. The command and parameter format can be customized by editing the regular expressions in the Elsinore.Exchange.dll.config. This section describes the use of the default command format.
Edit4 Email Subject Commands
The integration syntax consists of four basic commands. Each command takes specific parameters based on the kind of action it executes. The command parameters can be entered in the e-mail subject or the e-mail body. The commands are not case sensitive.
Edit4.1 Create
This command creates a new item of a specified class. The create command is specified by entering the command "create" in the subject followed by the ID or the display name of the class to be created. The subject of an e-mail to create a defect would have one of the following forms:
- Create Defect (the class is specified by display name)
- Create b9c8ab1f-6216-4ee2-862c-6c6b3a3f14f1 (the class is specified by GUID class ID)
For a new item to be successfully created and inserted into the database values for all required, i.e., not null, properties must be specified. For information on specifying class properties, consult the following section on E-mail Body Parameters.
Edit4.2 Update
This command updates properties of a specific item. The update command is specified by entering the command "update" in the subject followed by the GUID of the object to be updated. The subject of an e-mail update an issue would have the following form:
- Update b9c8ab1f-6216-4ee2-862c-6c6b3a3f14f1
Obviously the user sending the e-mail to the mailbox cannot be expected to know the GUID of the object to be updated. This command is designed for the use case where the user updates an item by responding to an IssueNet e-mail notification which is formatted using a template that contains the GUID of the object. By placing the variable $(Property.ObjectID) in a notification template the user can forward the e-mail notification to the mailbox with the update command and have the e-mail processed. For information on specifying the property values to be updated, consult the folowing section E-mail Body Parameters.
Edit4.3 Transition
The transition command allows a user to execute a workflow transition on a task. The transition command is specified by entering the command "Transition" followed by the GUID of the task to be transitioned and the transition name. The command to transition a task with ID c1be3507-8296-46eb-982b-fb48e356a30c using a transition named Review would be entered as:
- Transition c1be3507-8296-46eb-982b-fb48e356a30c Review
Like the update command, the user is not expected to know the GUID of the object to be transitioned. This command is designed for the use case where the user executes the transition by forwarding or replying to an e-mail notification that contains the object GUID.
Edit4.4 Workflow
The workflow command allows a user to execute a workflow for a specific issue. The workflow command is specified by entering the command "workflow" followed by the GUID of the issue, the GUID of the project, and the GUID of the workflow. The command to execute a workflow on an issue would have the following form:
- Workflow e34755c6-6fec-4271-ba2c-9a08257130e5 b9c8ab1f-6216-4ee2-862c-6c6b3a3f14f1 8d19936f-2a11-42d1-b00d-9965824417e7
Like the update, and transition commands, the user is not expected to know the GUIDs of the issue, project and workflow. This command is designed for the use case where the user executes the workflow by forwarding or replying to an e-mail notification that contains the required object GUIDs.
Edit5 Email Body Parameters
The Create and Update commands allow you to specify parameters for setting the properties of an item to be created or updated. These parameters are entered in the body of the email. The parameter format can be customized by editing the regular expression in the Elsinore.Exchange.dll.config that defines the body format. This section covers the use of the default format.
Edit5.1 Single Line Values
Single line values are specified by entering the display name of the property followed by a colon and the property value. For example, the body of an e-mail to create a high priority defect with a subject line would be:
- Subject: The scheduling web site become unresponsive after submitting an event that spans multiple days
- Priority: High
Edit5.2 Multi Line Values
To specify multi line values that preserve line breaks, the property value is enclosed in quotes. To enter a multi line value in the description field of an issue the body of the e-mail body would contain:
- Description: “scheduling web site becomes unresponsive after submitting an event that spans multiple days. Here is the error message:Error Code 2112 – The event date is null.”
Edit5.3 Appending Values
When updating properties such, as large text fields, it is important to be able to append information to the existing entry. If an update is not specified as an append the property value will replace the current value as opposed to being added to it. To append a value when updating, the parameter in the e-mail body should have a “+” precede the colon. For example, to append text to the description of a issue, the body of an e-mail would contain:
- Description+: “scheduling web site becomes unresponsive after submitting an event that spans multiple days. Here is the error message:Error Code 2112 – The event date is null.”
Edit6 Additional Configuration Settings
There are several response and error reporting options which can be set in the Elsinore.Exchange.dll.config:
- SendAcknowledgementDefault-Setting this value to true will cause the integration to send a response to the sender which acknowledges the successful processing of the e-mail command.
- ShowFullErrorDefault-Setting this value to true will cause the integration to send a verbose error report to the sender if there was an error processing the e-mail.
- AppendOriginalToReply-Setting this value to true will append the original message sent to the mail box to any response sent from the integration.
- UnrecognizedResponseFile- This value specifies the location of the file that contains the response text sent to the sender when the integration cannot process a command. The content of the response file can be used to provide the user with instructions on the proper command format.
Edit7 New in Version 5.3
In version 5.3 additional functionality has been added to the Exchange Integration. This includes the ability to designate a specific mailbox where received emails are automatically inserted into the database. This feature does not require IssueNet to be installed on the Exchange server; using the instructions below you can copy the files from an existing 5.3 installation.
Using the IssueNet Administrator (Tools|Options|Connectivity->Connections) add a connection that is configured for Auto-Login using the IssueNet Adminstrator account. You should name this connection to a friendly name that identifies it as the Exchange Connection.
Edit7.1 Preparing the Exchange Server
Copy the following files into a folder and place the folder on the Desktop of the Exchange Server
Copy the following files from the All Users\Application Data\Elsinore Technologies directory:
- Connections.xml
- Datasource.xml
- Servers.xml
Copy the following files from the Assemblies directory:
- Elsinore.Core.dll
- Elsinore.Engine.dll
- Elsinore.Exchange.dll
- Elsinore.MMFWebClient.dll
- Elsinore.SqlClientEngine.dll
- Interop.ADOBD.dll
- Interop.CDO.dll
- Interop.Exoledb.dll
- Microsoft.Exchange.Transport.EventInterop.dll
- Elsinore.Exchange.dll.config
- ICSharpCode.SharpZipLib.dll
Copy the following files from the Integrations\Exchange directory:
- Regevent.vbs
- Register.bat
- Response.txt
Open the Elsinore.Exchange.dll.config file using notepad and specify the Connection in the ConnectionName Value. Remember that the connection you use must be configured for auto-logon. It is recommended that you use the IssueNet Administrator account.
Edit7.2 Register the bat file
Open a Command line and change directory to the Folder which contains the register.bat.
In the following command put in your domain name and mailbox user:
register.bat r mailtriggerprocessor domain name mailbox user
Edit7.3 Create a Custom Trigger
A new Trigger type ‘Custom’ has been added to IssueNet to support this integration. This trigger is created using the IssueNet Adminstrator.
- Name – Provide a name for the trigger.
- Event- Custom.
- Conditon- not required.
Edit7.4 Create a Create Object Action
Start with a very simple Create Object action
- Name
- Select Type of object to Create (Customer Support Ticket)
- VariableName – Not required.
- Properties- Use the Variable CurrentMailItemID.Desription.