Exchange Web Services [EWS] support in The Bat! v7 User Guide for TBBETA 7/17/2015
Page 1 of 17 Contents EWS support in The Bat! version 7... 2 New Wizard: Creating a new account... 2 Step 1... 2 Step 2... 3 Step 3... 7 Getting new mail and folder structure... 8 Synchronization... 9 Folder management... 10 Log... 13
Page 2 of 17 EWS for The Bat! version 7 If you have an Exchange Server account, you can access it from within The Bat! using the EWS (Exchange Web Services) protocol. EWS allows accessing MS Exchange Server 2007 and later versions. Using EWS The Bat! can access the Exchange Server directly, there is no need in using Outlook s profile as in the case of MAPI. The program downloads not only emails, but other Exchange items as well, such as calendar events, contacts, tasks and notes. When you first time access the EWS account, The Bat! imports the downloaded contacts into the corresponding address book automatically. If messages, tasks or calendar events have a reminder, The Bat! creates the respective reminders in the Scheduler as well. All other Exchange items are available just for information purposes. New Wizard: Creating a new account Step 1 In the Create New Account window input your email address and the password for your Exchange account and select Exchange Web Services from the Protocol Type combo box.
Page 3 of 17 The Bat! will use the Exchange autodiscover service to automatically get setup information from your Exchange server. If your Exchange server is configured properly, The Bat! will retrieve the Exchange Server Endpoint and display its address in the respective field (see step 2). Step 2 If The Bat! finds the endpoint, just click Next and go to step 3. If The Bat! does not find the Exchange web services endpoint (the Exchange Server Endpoint field remains empty), you can: change the credentials and test the connection until you reach it or input it manually
Page 4 of 17 In the Email or User ID field enter your logon user name or UPN until the endpoint is reached. Like this: (domain/login based login) Or like this:
Page 5 of 17 (UPN based login) On the 1 st screenshot EWS is accessed by domain name followed by a backslash and logon name. On 2 nd screenshot EWS is accessed by UPN: logon name followed by the "@" symbol and the domain name. Note: Usually UPN matches the SMTP address configured for the user. Click the Test now! button to make The Bat! search for the Exchange Server Endpoint. Every time the wizard will start a few concurrent tasks trying to find the best solution for you. All endpoints found will be added to the dropdown menu. Animation will be active while searching is in progress. Note: if you are not sure which user name to use to access your Exchange server, input the same logon credentials you use to access your Exchange account via OWA (Outlook Web Access).
Page 6 of 17 If The Bat! is unable to detect the Exchange Server Endpoint, ask your Exchange administrator to provide you with the Exchange web services endpoint and your credentials as UPN+password or logon+password. The last solution is to enter the EWS endpoint manually. Remember you can change it in the Transport section of the Account properties at any point later. If your EWS endpoint was not automatically discovered or is not available, this may mean your Exchange Server administrator has blocked the EWS access. To check this, try to connect to https://mail.company.com/ews/exchange.asmx in your web browser: you should get an authentication popup. After successful authentication, you should get the EWS wsdl definition. If you do not get it, contact the Exchange Server administrators and ask them to fix the Exchange Server setup. Another way to get the EWS endpoint is to use the test page provided by Microsoft: https://testconnectivity.microsoft.com On the Exchange Server tab choose the Connectivity test for Exchange Web Services section, and after testing expand the details till you find the EwsUrl value (internal and external). Once you get this url, input it as the EWS endpoint address in The Bat! Note: Microsoft Outlook 2011 on OSX and native OSX applications also rely on EWS to connect to Exchange. You can manage the security certificates behavior as well. A Security Alert dialog will appear, if your Exchange server uses a self-signed or an expired digital certificate: You can add it to the local Windows certification store (View Certificate Install Certificate Next Place all certificates in the following store Browse <appropriate store> OK Next Finish).
Page 7 of 17 Alternatively, just avoid the message for this account by selecting the appropriate security flag checkbox. Beware: use security flags only when you trust the source. When the autodiscover process is completed, click Next. Step 3 The Your name field will display your Exchange account name. If the connection was successful, you will see here the Exchange full name which has been retrieved during the connection procedure. Otherwise Your name entered at step 1 will be duplicated. The second field identifies your new account in The Bat! s account tree. The last field shows the default location of the new account folder.
Page 8 of 17 Click Finish to add the new account. Once the new account appears in the account tree, The Bat! establishes the connection with the server and downloads folders with their contents. Getting new mail and folder structure The Bat! will retrieve all folders with contents (except for the Deletions, Archive and Recoverable folders) during the first connection with the server. In addition to standard folders, you will also see Calendar, Contacts, Tasks and some other folders that will display MS Exchange items such as calendar events, contacts, notes, activities, RSS feeds, tasks. The Bat! can also download the contents of the Exchange Public Folders. If you have access to an Exchange Public Folder, it will appear in the All Public Folders folder in your EWS account. The program displays all attributes used by Outlook which can be mapped into The Bat! s functionality and RFC822, such as Subject, From, To, CC, BCC and other headers, flags, attachments, tags, encryption, date and time of creation/receiving, size. If you are connected to social media in Outlook (Twitter, Facebook, LinkedIn), folders with the respective contacts will also appear in The Bat! s account tree (like Exchange contacts extracted from corporate Active Directory). Each Contact item will have an attached personal vcard, a picture and any other attachments you have assigned to the contact. When you first time access the EWS account for the first time, The Bat! imports the downloaded contacts into the newly created address book. The name of such address book consists of the account name followed by [EWS] :
Page 9 of 17 You can change the name of this address book and it will still be connected to your EWS account. If you delete the address book, your contacts will disappear from The Bat! s interface. However, you can restore them again by importing the <contact name>.vcf file attached to each Contact item. During the next connection The Bat! will discover that the address book is missing and will create a new one. If you set a reminder for a message, task or create an appointment in Outlook or OWA, The Bat! creates the respective reminder in the Scheduler once you get this item. The Bat! will remind you about this message/event/task at the specified time. If you create an item on the Exchange server, The Bat! will download it once you connect to the server. However, in the current version, items created in The Bat! will not be synced with the server. Synchronization Once The Bat! downloads the items, they are stored and preserved unchanged unless you clear the cache of the folder.
Page 10 of 17 If you delete items using the Delete key, they are not deleted from the Exchange server. If you delete items using the alternative deletion (Shift+Delete), they will be deleted from the Exchange server as well (Exchange soft delete mode will be used in this case). Later, if you restore such items using the Folder -> Browse Deleted Messages menu (to restore a deleted message, select it and press the Delete key), they will be stored locally only. If you delete a message from the Exchange server which you have already downloaded into The Bat!, it will not be deleted from The Bat! If you, however, clear the cache of the folder, then the message will not be available anymore. Currently, The Bat! syncs the Flagged and Read/Unread flags and receives the Parked flag ( is draft in Exchange terminology). For example, if you mark a message as read in The Bat!, another email client will also display it as read. The Replied and Forwarded/Redirected flags are not synchronized. The Bat! syncs message Priority and Sensitivity as well. Sensitivity is displayed as a tag and to change it you need to right-click the message and select it under Tags. In most cases, attributes that are currently not supported in The Bat! are shown as tags. Color groups are not yet supported. At a later point, after beta testing, The Bat! will sync all flags and folders in IMAP style. Folder management Folders in The Bat! are displayed in the language set for your account on the server (OWA -> Options -> Regional Settings -> Language -> Save). If you change the language set, the folder names will change in The Bat! accordingly. If you rename, move or delete a folder in The Bat!, these changes will be reflected on the server as well. If you create a folder in The Bat!, it will appear on the Exchange server. If the folder structure on the server changes (folders are moved,
Page 11 of 17 renamed, deleted or created), The Bat! will reflect these changes as well and update the folder structure. If you do not want to see a folder in the account tree, however, do not want to delete if from the server, you can change visibility: select the folder, press the Delete key and choose the Make invisible option. To hide a folder, you should also enable the Maintain list of hidden folders options in the Account -> Properties -> Transport menu:
Page 12 of 17 If you do not enable this option, hidden folders with their contents will be restored once the folder structure is refreshed (at the next mail retrieval). Thus, you can check the Maintain list of hidden folders box and mark any folder as invisible. You can get the full folder tree again if you uncheck this box and use the Receive new mail command. The folder tree will be restored and all missing messages will be received and stored locally. It is possible to clear cache of the folders by clicking the Clear cache now button in the Folder -> Properties -> EWS-Specific menu. After you clear cache The Bat! will download messages anew from the server.
Page 13 of 17 Log To access the account log, select View Log in the Account menu. Here is an example of a log with annotations after the first successful retrieval. > 24.06.2015, 11:15:37: connected to the Exchange server "https://mail.ritlabs.net/ews/exchange.asmx" as user "ritlabs\jstevens" Successful connection >24.06.2015, 11:15:37: Folders structure refreshed. The first step is retrieving and syncing folders. When new folders appear on the server or folders are moved in the folder tree hierarchy The Bat! mirrors these changes. For now, the creation of new folders in The Bat! is considered a local operation, these changes are not reflected on the server. >24.06.2015, 11:15:38: Discovered 1 items in folder Contacts. Added 1 thread(s).
Page 14 of 17 Here we have 1 item on the server in the Contacts folder. The Bat! spawns a new task to retrieve them. >24.06.2015, 11:15:38: Discovered 1 items in folder Outbox. Added 1 thread(s). Here we have 1 item on the server in the Outbox folder. The Bat! spawns a new task to retrieve them. >24.06.2015, 11:15:38: Discovered 19 items in folder Sent Items. Added 1 thread(s). >24.06.2015, 11:15:39: Discovered 2 items in folder Copies. Added 1 thread(s). >24.06.2015, 11:15:39: Discovered 629 items in folder Imported Junk. Added 1 thread(s). >24.06.2015, 11:15:39: Discovered 7 items in folder Deleted Items. Added 1 thread(s). >24.06.2015, 11:15:39: Discovered 2 items in folder Calendar. Added 1 thread(s). >24.06.2015, 11:15:39: Discovered 5 items in folder Recipient Cache. Added 1 thread(s). >24.06.2015, 11:15:39: Begin load items from folder Contacts Here we retrieved the first item for the Contacts folder. >24.06.2015, 11:15:39: Finished a thread in folder Contacts. Timestamp of last email: Friday, February 6, 2015 10:48. All the tasks for the Contacts folder were finished. Thus, The Bat! stores the transaction timestamp, which will be used as a reference point in the next connection to the server. >24.06.2015, 11:15:39: Finished processing folder Contacts. >24.06.2015, 11:15:40: Begin load items from folder Outbox >24.06.2015, 11:15:40: Finished a thread in folder Outbox. Timestamp of last email: Friday, February 6, 2015 10:52. >24.06.2015, 11:15:40: Finished processing folder Outbox. >24.06.2015, 11:15:42: Begin load items from folder Calendar >24.06.2015, 11:15:42: Finished a thread in folder Calendar. Timestamp of last email: Thursday, June 4, 2015 9:43. >24.06.2015, 11:15:42: Finished processing folder Calendar. >24.06.2015, 11:15:43: Begin load items from folder Imported Junk >24.06.2015, 11:15:43: Begin load items from folder Recipient Cache >24.06.2015, 11:15:44: Begin load items from folder Copies >24.06.2015, 11:15:44: Finished a thread in folder Copies. Timestamp of last email: Tuesday, May 12, 2015 15:15. >24.06.2015, 11:15:44: Finished processing folder Copies. >24.06.2015, 11:15:45: Begin load items from folder Sent Items >24.06.2015, 11:15:45: Finished a thread in folder Recipient Cache. Timestamp of last email: Saturday, May 23, 2015 13:00. >24.06.2015, 11:15:45: Finished processing folder Recipient Cache. >24.06.2015, 11:15:47: Begin load items from folder Deleted Items >24.06.2015, 11:15:52: Discovered 8368 items in folder Inbox. Added 9 thread(s). >24.06.2015, 11:15:53: Finished a thread in folder Deleted Items. Timestamp of last email: Friday, May 29, 2015 11:37. >24.06.2015, 11:15:53: Finished processing folder Deleted Items.
Page 15 of 17 >24.06.2015, 11:15:56: Begin load items from folder Inbox >24.06.2015, 11:15:57: Discovered 12274 items in folder Office. Added 13 thread(s). >24.06.2015, 11:15:59: Discovered 14091 items in folder Classified 2013. Added 15 thread(s). >24.06.2015, 11:15:59: Begin load items from folder Office >24.06.2015, 11:16:00: Begin load items from folder Classified 2013 >24.06.2015, 11:16:01: Finished a thread in folder Sent Items. Timestamp of last email: Wednesday, June 24, 2015 10:58. >24.06.2015, 11:16:01: Finished processing folder Sent Items. >24.06.2015, 11:16:21: Discovered 37795 items in folder WEB. Added 38 thread(s). >24.06.2015, 11:16:22: Begin load items from folder WEB >24.06.2015, 11:19:20: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:29. >24.06.2015, 11:19:23: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 10:56. >24.06.2015, 11:19:23: Finished a thread in folder Inbox. Timestamp of last email: Tuesday, May 12, 2015 14:36. >24.06.2015, 11:19:30: Finished a thread in folder WEB. Timestamp of last email: Thursday, May 7, 2015 16:17. >24.06.2015, 11:22:23: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:33. >24.06.2015, 11:22:29: Finished a thread in folder Inbox. Timestamp of last email: Tuesday, May 12, 2015 14:40. >24.06.2015, 11:22:30: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 10:59. >24.06.2015, 11:22:30: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 11:37. >24.06.2015, 11:23:32: Finished a thread in folder Imported Junk. Timestamp of last email: Monday, May 18, 2015 9:45. >24.06.2015, 11:23:32: Finished processing folder Imported Junk. >24.06.2015, 11:24:59: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:36. >24.06.2015, 11:25:04: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 11:41. >24.06.2015, 11:25:06: Finished a thread in folder Inbox. Timestamp of last email: Tuesday, May 12, 2015 14:45. >24.06.2015, 11:25:06: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:02. >24.06.2015, 11:27:21: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:40. >24.06.2015, 11:27:26: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 11:45. >24.06.2015, 11:27:30: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:04. >24.06.2015, 11:28:01: Finished a thread in folder Inbox. Timestamp of last email: Friday, May 22, 2015 10:34. >24.06.2015, 11:29:52: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:43. >24.06.2015, 11:29:56: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 11:48. >24.06.2015, 11:30:01: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:07. >24.06.2015, 11:31:22: Finished a thread in folder Inbox. Timestamp of last email: Friday, May 29, 2015 4:29. >24.06.2015, 11:32:17: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:47.
Page 16 of 17 >24.06.2015, 11:32:21: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 11:52. >24.06.2015, 11:32:27: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:09. >24.06.2015, 11:34:26: Finished a thread in folder Inbox. Timestamp of last email: Friday, June 5, 2015 17:32. >24.06.2015, 11:34:45: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:50. >24.06.2015, 11:34:48: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 11:56. >24.06.2015, 11:34:53: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:12. >24.06.2015, 11:37:05: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:00. >24.06.2015, 11:37:09: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:54. >24.06.2015, 11:37:24: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:14. >24.06.2015, 11:37:49: Finished a thread in folder Inbox. Timestamp of last email: Monday, June 15, 2015 17:01. >24.06.2015, 11:39:36: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:03. >24.06.2015, 11:39:40: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 15:57. >24.06.2015, 11:39:54: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:16. >24.06.2015, 11:41:08: Finished a thread in folder Inbox. Timestamp of last email: Monday, June 22, 2015 11:42. >24.06.2015, 11:42:02: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:07. >24.06.2015, 11:42:06: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 16:01. >24.06.2015, 11:42:15: Finished a thread in folder Inbox. Timestamp of last email: Wednesday, June 24, 2015 11:15. >24.06.2015, 11:42:15: Finished processing folder Inbox. >24.06.2015, 11:42:19: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:19. >24.06.2015, 11:43:56: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:11. >24.06.2015, 11:44:04: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 16:05. >24.06.2015, 11:44:17: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:22. >24.06.2015, 11:45:46: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:14. >24.06.2015, 11:46:01: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 16:09. >24.06.2015, 11:46:15: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:24. >24.06.2015, 11:46:53: Finished a thread in folder Office. Timestamp of last email: Friday, May 15, 2015 11:25. >24.06.2015, 11:46:53: Finished processing folder Office. >24.06.2015, 11:47:38: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:18. >24.06.2015, 11:47:50: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 16:13. >24.06.2015, 11:49:09: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 12:22. >24.06.2015, 11:49:27: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 16:27.
Page 17 of 17 >24.06.2015, 11:49:36: Finished a thread in folder Classified 2013. Timestamp of last email: Thursday, May 7, 2015 16:28. >24.06.2015, 11:49:36: Finished processing folder Classified 2013. >24.06.2015, 11:50:37: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:04. >24.06.2015, 11:51:59: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:08. >24.06.2015, 11:53:25: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:12. >24.06.2015, 11:54:54: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:15. >24.06.2015, 11:56:21: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:19. >24.06.2015, 11:57:48: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:23. >24.06.2015, 11:59:16: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:27. >24.06.2015, 12:00:59: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:31. >24.06.2015, 12:02:31: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:34. >24.06.2015, 12:04:04: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:38. >24.06.2015, 12:05:41: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:42. >24.06.2015, 12:07:17: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:45. >24.06.2015, 12:08:58: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:49. >24.06.2015, 12:10:43: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 14:53. >24.06.2015, 12:12:24: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:12. >24.06.2015, 12:14:06: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:16. >24.06.2015, 12:15:54: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:20. >24.06.2015, 12:17:39: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:23. >24.06.2015, 12:19:36: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:27. >24.06.2015, 12:21:25: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:31. >24.06.2015, 12:23:16: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:35. >24.06.2015, 12:25:13: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:39. >24.06.2015, 12:27:07: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:43. >24.06.2015, 12:28:47: Finished a thread in folder WEB. Timestamp of last email: Friday, May 8, 2015 15:46. >24.06.2015, 12:28:47: Finished processing folder WEB. >24.06.2015, 12:28:47: Finished. Elapsed 01:13:10; 26 folders, Received 73194/73194 items, stored 73193 new items, 3800 attachments, 619.76 MB; Avg time: 57 ms per entity. The Bat! retrieved and stored all items including 3800 attachments, it also generated vcards for each contact. The program downloaded 619.76 MB, average time spent for each item (email/contact/calendar/attachment) is 57 ms. The time needed to fetch new mail depends on the network connection and the Exchange server capacity. 2015