Exchange Web Services [EWS] support in The Bat! v7

(1)

Ritlabs, SRL

Exchange Web Services [EWS]

support in The Bat! v7

User Guide for TBBETA

(2)

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

(3)

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

(4)

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:

(5)

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)

(6)

(

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.

(7)

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:

(8)

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.

(9)

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.

(10)

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

(11)

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.

(12)

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.

(13)

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.

(14)

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.

(15)

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.

(16)

>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: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 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: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: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:31:22: Finished a thread in folder Inbox. Timestamp of last email: Friday, May 29, 2015 4:29.

(17)

>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: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:49: Finished a thread in folder Inbox. Timestamp of last email: Monday, June 15, 2015 17:01.

>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: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:46:53: Finished processing folder Office.

(18)

>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.

Exchange Web Services [EWS] support in The Bat! v7

Ritlabs, SRL