KB001385

The following changes in K2 4.6.5 make it easier to install and configure the Exchange Integration:

• The K2 Setup Manager uses the Microsoft Exchange Autodiscover Service to discover required settings.
• The installer works for Exchange On–premises or Exchange Online. If you need to configure different features for different Exchange environments that will need to be accomplished manually post-installation.
• Creation of Exchange Service Instances and SmartObjects.
• EWS is configured once for all E-mail events, escalations e-mails, task notifications and SmartActions.
• Support for Microsoft Exchange 2013 (On-premises and Online), 2010 and 2007.

Details

The K2 Setup Manager is enhanced to use Exchange Autodiscover to pre-populate the required Exchange server settings, making the install experience easier and faster. However, if Autodiscover is not enabled on the Exchange server, you must manually configure the settings. It is recommended that Autodiscover be available in your environment prior to installation. Autodiscover is used before making a call to Exchange. The K2 Service Account’s email address is  used for the discovery process, however for Online the specified account is used.

Online: Exchange Online always has Autodiscover available. During the setup you are asked for an email address and password of one of the online accounts, this account is used for the discovery process and to reply to SmartActions. Recommendation: Use the K2 Service email account in Active Directory as the Online account. Note that the Exchange Online integration only uses Static credentials for all interaction with Exchange. RunAs does not apply when configuring Exchange Online.

Autodiscover provides the following values required by the K2 Setup Manager: 

• EWS URL
• TLS encryption setting
• SMTP Server 
• Port

If you require Exchange integration for SmartActions but use a different SMTP server, you must configure this manually post-installation using the Connection String Editor found in the [program files]K2 blackpearlHost ServerBin folder. See the Exchange/SMTP Mixed Mode section below.

There are three screens in the installer that deal with the Exchange configuration:

1. Exchange Server Configuration
2. Exchange Integration
3. SmartActions  Configuration

Exchange Server Configuration

Here you select whether or not your environment requires Exchange Integration. Selecting the Use Exchange for mail integration will configure the following functionality: 

• SmartActions (if selected)
• Exchange wizards in all the K2 designers 
• Registering the Exchange Service Instance (if selected)
• Creation of Exchange SmartObjects

The EWS URL is a required field that can be discovered by clicking the Discover button, or the URL can be typed in the text field and subsequently verified by clicking the Test button.

Exchange Integration

Uses the Exchange Admin and the Exchange Management SmartObjects to allow the functionality to enable and disable mailboxes, send calendar and task requests, and check for meeting availability. On this screen if Autodiscover is enabled it is used to discover the required settings. This screen is dependent on the “Use Exchange for mail integration” checkbox being selected on the first Exchange panel in the Setup Manager.

The following logic applies when selecting Configure Exchange On-premises or Configure Exchange Online on the Exchange Server Configuration screen:

If On-premises

• Selecting the Enable administrative Exchange Integration (Mailbox) option will create or enable the mailbox
• Deselecting the Enable administrative Exchange Integration (Mailbox) option will disable the mailbox

If Online

• Selecting the Enable administrative Exchange Integration (Mailbox) option will remove or restore access to a mailbox
• Deselecting the Enable administrative Exchange Integration (Mailbox) option will not allow the Exchange wizard to remove or restore access to a mailbox

SmartActions Configuration

On this screen you select whether or not SmartActions are used in the environment and define the e-mail account to be used by SmartActions.

SMTP

The SMTP screen is no longer required when configuring Exchange Integration. However, if installing in an environment that will not make use of Exchange but a different mail provider the SMTP screen will be displayed to allow for the required configuration.  The connection string created by K2 Setup Manager will be an anonymous connection string. To change this to authenticated SMTP you must manually change the connection string using the ConnectionStringEditor.exe found in the ..K2 blackpearlHost ServerBin folder.

Configuration Analysis Tool

When configuring for Exchange Online the static account used to install with needs to be part of the “Organizational Management” role group in Exchange. This is required for the analysis to be performed.

Clean Install

When installing the Autodiscover flag is set to TRUE. If Autodiscover fails an exception is raised notifying the installer. If Autodiscover is not enabled the installer is required to manually input the required fields. It is suggested in this instance that the following details are known before installing K2:

• EWS URL
• Exchange Server name (SMTP server name)
• TLS encryption setting
• Port number

The K2 Setup Manager guides you through the installation process. For more information refer to the K2 Installation and Configuration documentation. 

Upgrade

When upgrading to K2 4.6.5 the Autodiscover flags are set to False. This ensures that the environment continues to function as in previous versions. If you want to make use of the new integration settings and functionality, upgrade to K2 4.6.5 and then reconfigure your environment by re-running the K2 Setup Manager and update the design templates of each existing workflow.

Performing a reconfigure 

When the Use previously configured values checkbox is unchecked on an upgrade, with the functionality gained through Autodiscover the Advanced Settings screen available in the E-mail Event and in escalations allowing for the configuration of SMTP settings are no longer required. When upgrading this advanced screen is visible in the wizards, but when the Design Templates are updated the mail server screen no longer appears. New events do not have this screen.

For existing processes it is possible to send mail with Authenticated SMTP. Follow the steps below for On-premises and Online to send mail with Authenticated SMTP:

• Update the Design Templates for all existing processes.
• Edit the connection strings according to the requirements set by the SMTP server, for example,  Port=25;TLS=BootTLS;Host Name=mail.denallix.com;User ID=DENALLIXK2Service;Password=XXXXX;Authentication=Windows.

For authenticated SMTP, every From address that will be used to send mails should be supplied a corresponding connection string.  Use the ConnectionStringEditor.exe found in the ..K2 blackpearlHost ServerBin folder.

If the SMTP server is configured so that the authenticated sender must use a valid sender address, then every SMTP connection string should contain the credentials corresponding to the connection string identity (email address) and Authentication should be set to “Plain”.

Configuring SMTP connection strings: 

1. SMTP connection strings can be added using the ConnectionStringEditor.exe tool.
2. When creating a new connection string, an e-mail address must be provided as the connection string identity. This identity (e-mail address) will be used to compare and retrieve connection settings when sending e-mails.
3. The Authentication and TLS fields will be populated by default on creation of the connection string.
4. The Host Name and Port fields must be populated before using the connection string.
5. If Authentication is set to “Anonymous”, the mail will be sent without authentication. For example, Port=25;TLS=BootTLS;Host Name=mail.denallix.com.
6. If Authentication is set to “Windows”, the K2HostServer (service account) credentials will be used to authenticate with the SMTP server and the User ID and Password will be ignored. For example: Port=25;TLS=BootTLS;Host Name=mail.denallix.com;Password=XXXXX;Authentication=Windows.
7. If Authentication is set to “Plain” the User ID and Password will be used to authenticate with. For example, Port=25;Host Name=mail.denallix.com;UserID=DENALLIXAdministrator;Password=XXXXX;Authentication=Plain

Known Issue: When deploying pre K2 blackpearl 4.6.5 workflows either in the K2 designers or using K2 Package and Deployment in a clean Exchange Online environment, the E-mail event and mail Escalations will fail with a timeout exception and the workflows will go into an error state. 
Workaround:  Update the Design Templates and redeploy the workflow.

Rights

If the K2HostServer service account’s e-mail address is different from the From Address specified,  the K2HostServer account will have to have Send As permissions on the From account’s mailbox. To configure SendAs permissions refer to the following articles:

• Exchange 2007: http://technet.microsoft.com/en-us/library/aa998291(v=exchg.80).aspx
• Exchange 2010: http://technet.microsoft.com/en-us/library/bb676368(v=exchg.141).aspx
• Exchange 2013: http://technet.microsoft.com/en-us/library/bb124403.aspx or http://www.techieshelp.com/exchange-2013-setup-send-as-and-send-on-behalf/
• Exchange Online: http://help.outlook.com/140/ff852815.aspx or http://www.techieshelp.com/exchange-2013-setup-send-as-and-send-on-behalf/

For Exchange Services (Meetings, Tasks, Mailboxes) for Online Integration the following rights will be required:

• For Enable/Disable mailbox the static account used to install with needs to be part of the “Organizational Management” or “Recipient Management” role group; or create the account as a “Global Administrator” in Exchange Online. If the account is part of the “Recipient Management” role group, the Setup Manager gives a warning stating that the user is required in the "Organizational Management" role. This error can be ignored and the installation can be completed.

When configuring for Exchange Online the static account used to install with needs to be part of the “Organizational Management” role group in Exchange. This is required for the Configuration analysis to be performed.

Exchange/SMTP Mixed Mode

A mixed mode environment is possible but will require additional manual configuration to setup the SMTP. For sending mails and escalations K2 will first look for and use the SMTP settings and if not found will then look for and use the EWS URL. For notifications, SmartActions and Exchange services (Meetings, Tasks, Mailboxes) K2 will always use the EWS URL.

1. On a clean environment install K2 to use Exchange Integration. Complete the install.
2. Use the ConnectionStringEditor.exe found in the ..K2 blackpearlHost ServerBin folder to configure the SMTP connection. Edit the connection strings according to the requirements set by the SMTP server, for example,  Port=25;TLS=BootTLS;Host Name=mail.denallix.com;User ID=DENALLIXK2Service;Password=XXXXX;Authentication=Windows.
3. For authenticated SMTP, every From address that will be used to send mails should be supplied a corresponding connection string.

Troubleshooting

When troubleshooting view the hostserver log files for error and warning messages. Below describes some issues that could be encountered:

• If the EWS URL is empty, an exception will be thrown that the URL is empty.  To resolve this issue reconfigure K2 to supply the required URL.
• If e-mails fail to send with a supplied EWS URL, K2 will log the issue, then try to auto-discover the EWS URL and then log the fact that it is auto-discovering and then send the mail again.
  • If the mail still fails with the Autodiscovered EWS URL, an exception will be thrown.
  • If Autodiscover failed, an exception will be thrown.
  • If the Autodiscover service is not available an exception will be thrown stating this.
• If the e-mails fail to send because the “From” address is not authenticated, an exception will also be thrown. A corresponding connection string will have to be created for that From address using the ConnectionStringEditor.exe.
• The following error message will be displayed when using Exchange Online if the installer is unable to Autodiscover: 
  "Unable to get auto discover information for the given Email and Password. For Exchange Online to work auto discover must be validated”.
  This could be caused by an invalid or blocked e-mail address. It is recommended that you test your Exchange connectivity and Autodiscover settings using a tool such as https://www.testexchangeconnectivity.com/.