Copyright © 2016 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover, or Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual.

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

     All Emacs Lisp code contained in this document may be used, distributed, and modified without restriction.

Excorporate Manual
******************

Excorporate provides Exchange Web Services (EWS) support for Emacs.

If the Exchange server you access is configured to provide EWS support, then there's a 76% chance that Excorporate will enable you to retrieve your calendar entries from the comfort of Emacs.

The 24% failure rate is because accessing -- in particular, authenticating against -- an Exchange server can be challenging.

Known to fail are Kerberos/GSSAPI authentication and accessing the server through a proxy (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10).

Patches are welcome to enable more of these access scenarios.

Installation
************

Excorporate works on Emacs versions >= 24.1.

Install excorporate from the GNU ELPA repository:

M-x package-install RET excorporate

Configuration
*************

Ideally you won't need to configure Excorporate at all.  On friendly Exchange setups, Excorporate can discover the EWS URL automatically.

First try:

M-x excorporate

which will prompt you for the Exchange account email address.  Follow the prompts and if all goes well, you'll see a message in the minibuffer or in *Messages* saying that the connection is ready.

If autodiscovery runs out of URLs to try, then customize excorporate-configuration:

M-x customize-variable RET excorporate-configuration

From the value menu select ``Skip autodiscovery''.  This allows you to enter the Exchange account email address and the EWS URL directly. The EWS URL is of the form https://mail.gnu.org/ews/exchange.asmx.

After saving the configuration, try M-x excorporate again.

If that doesn't work, then you're probably out of luck, or you'll have to start a troubleshooting deep dive (see Troubleshooting).

Usage
*****

Excorporate binds `e' in *Calendar* buffers.  Open the calendar with:

M-x calendar

move the cursor to the date you want to see meetings for, and press `e'.  This will show the meetings in a temporary read-only Org Mode buffer named *Excorporate*.

Troubleshooting
***************

First, you'll want to double-check that the Exchange server you're trying to access provides EWS support.  If it doesn't, Excorporate can't do anything for you.  Before asking your Exchange administrator, check intranet wikis and so forth; other users of non-standard clients may have already found the EWS URL.

The buffer *fsm-debug* shows excorporate state transitions and should provide details of where things went wrong.

Also check *Messages* for anything obvious.

If you suspect something wrong with accessing the EWS URL, try setting url-debug to t and retry M-x excorporate, then check the *URL-DEBUG* buffer for output.

If you suspect NTLM authentication is failing, as a long shot, you might try setting ntlm-compatibility-level to 0 and retrying M-x excorporate.

Excorporate's dependencies implement the tricky elements of asynchronous Exchange access: a state machine (fsm), TLS negotiation (gnutls), NTLM authentication (ntlm and url-http-ntlm) and SOAP communication (soap-client).