UCCX Integration with Office 365 for Agent Email

Introduction

This document describes how Unified Contact Center Express (UCCX) solution, starting from version 11.5 along with SocialMiner (SM) supports Office 365 as an email server for agent email functionality. This is the first cloud email provider supported for the agent email functionality.

Design and Topology

The UCCX server now provides cloud email support starting from 11.5. This functionality is achieved by an integration to the Office365 email service via a SOCKS 5 proxy. It is important to note that having a proxy server is not mandatory, but most deployments have external network access blocked and therefore connection has to be established via a proxy server.

Apart from the one additional step of setting up the proxy, there is no other change for the customer. The messaging flow is shown in the image:

Configuration

1. Having a proxy server to connect to Office 365 is not mandatory. If your network connectivity is setup in such a way that the SM server can set up a TCP connection on the Internet Message Access Protocol (IMAP) and Simple Mail Transfer Protocol (SMTP) ports of office365.com, a proxy server is not needed.
   
   
2. If you wish to use a proxy between the SM and Office 365, SOCKS 5 is the only supported protocol. SOCKS4, SSH tunnels, and other protocols are not supported.
   
   
3. Cisco does not recommend which proxy server needs to be used.

Setting up the Proxy

As a part of this technote, an open source proxy server for Linux called Dante is used. Please note that this does not mean that this is the Cisco recommended proxy server; it is one of the servers used in the lab for creating this document. You are free to use any server of choice as long as the SOCKS5 protocol is used.

Note: The server that is being configured as a proxy should have access to office365.com, without the need to have further proxies.

On a Linux server with root access:

Step 1. Install the Dante server.

Step 2. Configure the server by adding the following info into the /etc/danted.conf file.

Step 3. Start the server, ready to use.

More information about the Dante server and downloading the install packages can be found here: https://www.inet.no/dante/index.html

Office365 Account

Login Portal:https://login.microsoftonline.com

To buy a paid Office365 account, go to https://products.office.com/en/exchange/compare-microsoft-exchange-online-planswith your credit card. (The basic pricing option costs $4 before tax per email account per month.)

Note: When signing up for the Office365 service, ensure that the service allocated to you is from the same country where the SocialMiner server is. This is very important, or you will have issues with connectivity. 

Configure the UCCX/SM

This section provides the high-level tasks and related information for configuring Unified CCX integration with office 365 for Agent Email.

Configuration Tasks	Reference	Detailed steps
1. Configure the Unified Communications Manager server.	SeeCisco Unified Communications Manager Install and Upgrade Guides
2. Configure the Unified Communications Manager for the Unified CCX.	SeeCisco Unified Communications Manager Configuration Guides
3. Configure Unified CCX.	SeeCisco Unified Contact Center Express Install and Upgrade Guides
4. Configure SocialMiner.	See the SocialMiner Configuration chapterof the Cisco Unified CCX Administration Guide, Release 11.5	Step 1.  From the Unified CCX Administration menu bar, navigate to Subsystems > Chat and Email > SocialMiner Configuration. The SocialMiner Configuration web page appears. Step 2.  Complete or modify the following fields for SocialMiner: IP Address / Host Name: IP address or fully qualified domain name of the SocialMiner server. For example, 192.168.1.5 or host.example.com. Username/Password of the SocialMiner administrator. Note: Unified CCX and SocialMiner servers must have DNS entries. SocialMiner must be accessible to Unified CCX by hostname. If the entries are not valid, an error is displayed. Step 3.  Click Save to save the changes. If you see an error message, click Save to re-create feeds, campaigns, and notifications for chat and email in SocialMiner.
5. Configure Unified CCX Mail Server.	See the Mail Server Configuration chapter  of the Cisco Unified CCX Administration Guide, Release 11.5	Step 1. From the Unified CCX Administration menu bar, navigate to Subsystems > Chat and Email > Mail Server Configuration. The Mail Server Configuration web page opens. Step 2. Complete the fields for the Office 365 mail server, as shown in the image:
6. Configure Socks Proxy Server		If the proxy is required for Office 365 access: System parameter Configuration Add hostname, port, username and password fields in the proxy parameters section of System Parameters page. (Username / Password is optional)
7. Contact Service Queues Configuration	See the Contact Service Queues Configuration chapter of the Cisco Unified CCX Administration Guide, Release 11.5
8. Predefined Responses Configuration	See the Predefined Responses chapter of the Cisco Unified CCX Administration Guide, Release 11.5
9. Channel Parameters Configuration	See the Channel Parameters chapter of the Cisco Unified CCX Administration Guide, Release 11.5

Troubleshoot

Relevant logs

These logs are important to debug the O365 related issues.

• Runtime Logs: https://<SocialMiner Server IP/Host>/ccp-webapp/logs/runtime/
  File Pattern: CCBU-runtime.*.startup.log, Error-runtime.*.startup.log
  
  
• API Logs: https://<SocialMiner Server IP/Host>/ccp-webapp/logs/ccapi/
  File Pattern: CCBU-ccpapi.*.startup.log, Error-ccpapi.*.startup.log

Checklist

Check these to ensure that Office365 functionality is working fine as expected in a SocialMiner system:

• Check if SocialMiner is able to reach Office365 directly.
  
  
• If SocialMiner is not able to reach Office365, configure Socks Proxy in SocialMiner and enable it.
  
  
• Only Socks 5 Protocol is supported.
  
  
• Ensure that the Socks Proxy server is able to reach Office365.
  
  
• Check Office365 credentials in CCX.
  
  
• Check Office365 email feed status in SocailMiner

  • If the feed is fetching normally, it would be green and not red with cross mark (X) as shown in the image.

  • If the feed is broken, you can hover over the red cross mark (X) to know the reason.

Note: Upon Socks Proxy reconfiguration, all existing email feeds would be automatically updated to use the latest Socks Proxy Configuration.

Common Scenarios

Problem: Agents are not able to receive emails.

Possible Cause 1: Socks Proxy is not configured/enabled

In the runtime logs,  the following error is shown:

exception=javax.mail.MessagingException: connect timed out;

Recommended action:

• Configure the Socks Proxy Server and enable it.
  
  
• Make sure that Socks Proxy is reachable from SocialMiner and Socks Proxy Server is able to reach the O365.

Possible: If using authenticated Socks Proxy, credentials provided are wrong

In the runtime logs,  the following error is shown:

exception=javax.mail.MessagingException: SOCKS : authentication failed;

Recommended action :

• Resolve the authentication issue by providing the correct credentials.
  
  

• Ensure that the Socks Proxy is reachable from SocialMiner and Socks Proxy Server is able to reach the O365.

Problem: Delay in sending emails using Office365.

Recommended action: 

• If sending an email takes > 10 seconds, find if SMTP connection to Office365 is causing the delay.
  
  
• Configure Office365 using Thunderbird or outlook client via IMAP. If sending an email takes long time with authenticated SMTP connection, then it indicates the same slowness issue in SocialMiner as well.
  
  
• The issue is from Office365. Contact Office365 support.

Microsoft Diagnostics tool

If you are having trouble with the connectivity with the Office365 service and want to check on the status of your service, there is a tool from Microsoft that can be used. The tool is called Support and Recovery Assistant and can be downloaded from here: https://diagnostics.outlook.com/#/

More details about the same: https://blogs.office.com/2016/05/11/new-tool-for-helping-resolve-office-365-issues/

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see  What’s New in Cisco Product Documentation at:  http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html.

Subscribe to What’s New in Cisco Product Documentation, which lists all new and revised Cisco technical documentation, as an RSS feed and deliver content directly to your desktop using a reader application. The RSS feeds are a free service.

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

All printed copies and duplicate soft copies are considered un-Controlled copies and the original on-line version should be referred to for latest version.

Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at www.cisco.com/go/offices.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

© 2016 Cisco Systems, Inc. All rights reserved.