\input texinfo
@setfilename excorporate.info
@settitle Excorporate Manual

@dircategory Emacs
@direntry
* Excorporate: (excorporate).  Exchange Web Services integration for Emacs.
@end direntry

@copying
Copyright @copyright{} 2016 Free Software Foundation, Inc.

@quotation
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.
@end quotation
@end copying

@titlepage
@title Excorporate Manual
@author Thomas Fitzsimmons
@page
@insertcopying
@end titlepage

@contents

@node Top
@top 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 an 83% chance that Excorporate will enable you
to retrieve your calendar entries from the comfort of Emacs.

The 17% failure rate is because authenticating against an Exchange
server can be challenging.

Kerberos/GSSAPI authentication is known to fail.  Accessing the server
through a proxy may be possible now that
@uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10} is fixed.

Reports of success or failure of different connection types are
welcome, as are patches to enable more of these access scenarios.  See
@pxref{Reporting Bugs}.

@menu
* Installation::                Getting and installing @code{excorporate}.
* Configuration::               Configuring @code{excorporate}.
* Usage::                       Using @code{excorporate}.
* Troubleshooting::             Debugging why a connection failed
* Reporting Bugs::              Reporting bugs
@end menu

@node Installation
@chapter Installation

Excorporate works on Emacs versions >= 24.1.

@noindent
Install @code{excorporate} from the GNU ELPA repository:

@code{M-x package-install RET excorporate}

@node Configuration
@chapter Configuration

@noindent
Ideally you won't need to configure Excorporate beyond providing your
account email address.  On friendly Exchange setups, Excorporate can
discover the EWS URL automatically.

@noindent
Run:

@code{M-x excorporate}

@noindent
which will prompt you for the Exchange account configuration.  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.  Using the
prompts, you can first try with autodiscovery.  If autodiscovery runs
out of URLs to try, re-run @code{excorporate}, saying 'n' to the
autodiscovery attempt, at which point you will be asked for the EWS URL.

@noindent
To save a working configuration, customize
@code{excorporate-configuration}:

@code{M-x customize-variable RET excorporate-configuration}

@noindent
After saving the configuration, try @code{M-x excorporate} again.

@noindent
If neither autodiscovery nor specifying the EWS URL work,
@pxref{Troubleshooting}.

@node Usage
@chapter Usage

@noindent
Excorporate can put entries it retrieves into the Emacs Diary, and use
@code{appt} to remind you a few minutes before a meeting starts.  To
enable this support, do:

@code{M-x excorporate-diary-enable}

@noindent
Open the calendar with:

@code{M-x calendar}

@noindent
move the cursor to the date you want to see meetings for, and press
`d'.  Some time later, asynchronously, a window will pop up containing
events retrieved from the Exchange server in addition to
locally-entered diary events.  The events are all sorted by time.

Excorporate also binds `e' in @code{*Calendar*} buffers to
@code{excorporate-calendar-show-day-function} to allow a different
view of retrieved events.  By default,
@code{excorporate-calendar-show-day-function} is set to
@code{exco-org-show-day} which displays meetings in a temporary
read-only Org Mode buffer named @code{*Excorporate*}.

If you prefer, you can install the @code{calfw} package, and set
@code{excorporate-calendar-show-day-function} to
@code{exco-calfw-show-day}.

After you've retrieved today's meetings, @code{appt} will warn you
several minutes before your next meeting starts by popping up a window
with the meeting details.

If you leave Emacs running overnight, at 12:01 AM @code{appt} (via
Excorporate) will retrieve your meetings and display your diary so
that you see the day's events first thing in the morning.

@node Troubleshooting
@chapter Troubleshooting

@noindent
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.  This is called the ``EWS
endpoint''.  It can be as simple as, e.g.:

@code{https://mail.gnu.org/ews/exchange.asmx}

@noindent
First you need to make sure you can access the endpoint.

@noindent
For Exchange Web Services (EWS) which Excorporate uses, you'll have to
determine the EWS endpoint for your Exchange account, call it
@code{ews-url}.  It is usually something like:

   https://<mail host name>/ews/exchange.asmx

@noindent
Excorporate calculates the WSDL URL, call it @code{wsdl-url}, by
replacing the endpoint's last path element with ``Services.wsdl'':

   https://<mail host name>/ews/Services.wsdl

@noindent
Before even attempting Excorporate, you have to make these succeed:

@example
(with-current-buffer
 (url-retrieve-synchronously ews-url)
 (buffer-string))
@end example

@noindent
When this works, you'll see web page text in *Messages*, containing a
message about having created a service.

@example
(with-current-buffer
 (url-retrieve-synchronously wsdl-url)
 (buffer-string))
@end example

@noindent
When this works, it will show a bunch of WSDL (XML) in *Messages*.

@noindent
Debug the above URL retrievals with (setq url-debug t), and with this
patch:

@example
diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
index d49e527..0f1c8ae 100644
--- a/lisp/url/url-http.el
+++ b/lisp/url/url-http.el
@@ -869,6 +869,7 @@ url-http-parse-headers
       (url-handle-content-transfer-encoding))
     (url-http-debug "Finished parsing HTTP headers: %S" success)
     (widen)
+    (url-http-debug "Response: %s" (buffer-string))
     (goto-char (point-min))
     success))

@end example

@noindent
(Beware that HTTP responses are out-of-order with this patch.)

@noindent
Once you're sure the above steps are working, try @code{M-x
excorporate}.

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

@noindent
Also check @code{*Messages*} for anything obvious.

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

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

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

@node Reporting Bugs
@chapter Reporting Bugs

@noindent
To report a bug, use @code{M-x report-emacs-bug}, and put Excorporate
somewhere in the subject.

@bye
