code.delx.au - gnu-emacs-elpa/blob - packages/excorporate/excorporate.texi

   1 \input texinfo
   2 @setfilename excorporate.info
   3 @settitle Excorporate Manual
   4
   5 @dircategory Emacs
   6 @direntry
   7 * Excorporate: (excorporate).  Exchange Web Services integration for Emacs.
   8 @end direntry
   9
  10 @copying
  11 Copyright @copyright{} 2016 Free Software Foundation, Inc.
  12
  13 @quotation
  14 Permission is granted to copy, distribute and/or modify this document
  15 under the terms of the GNU Free Documentation License, Version 1.2 or
  16 any later version published by the Free Software Foundation; with no
  17 Invariant Sections, with the Front-Cover, or Back-Cover Texts.  A copy of
  18 the license is included in the section entitled ``GNU Free Documentation
  19 License'' in the Emacs manual.
  20
  21 This document is part of a collection distributed under the GNU Free
  22 Documentation License.  If you want to distribute this document
  23 separately from the collection, you can do so by adding a copy of the
  24 license to the document, as described in section 6 of the license.
  25
  26 All Emacs Lisp code contained in this document may be used, distributed,
  27 and modified without restriction.
  28 @end quotation
  29 @end copying
  30
  31 @titlepage
  32 @title Excorporate Manual
  33 @author Thomas Fitzsimmons
  34 @page
  35 @insertcopying
  36 @end titlepage
  37
  38 @contents
  39
  40 @node Top
  41 @top Excorporate Manual
  42
  43 Excorporate provides Exchange Web Services (EWS) support for Emacs.
  44
  45 If the Exchange server you access is configured to provide EWS
  46 support, then there's a 76% chance that Excorporate will enable you to
  47 retrieve your calendar entries from the comfort of Emacs.
  48
  49 The 24% failure rate is because accessing -- in particular,
  50 authenticating against -- an Exchange server can be challenging.
  51
  52 Known to fail are Kerberos/GSSAPI authentication and accessing the
  53 server through a proxy
  54 (@uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10}).
  55
  56 Patches are welcome to enable more of these access scenarios.
  57
  58 @menu
  59 * Installation::                Getting and installing @code{excorporate}.
  60 * Configuration::               Configuring @code{excorporate}.
  61 * Usage::                       Using @code{excorporate}.
  62 * Troubleshooting::             Debugging why a connection failed
  63 * Reporting Bugs::              Reporting bugs
  64 @end menu
  65
  66 @node Installation
  67 @chapter Installation
  68
  69 Excorporate works on Emacs versions >= 24.1.
  70
  71 @noindent
  72 Install @code{excorporate} from the GNU ELPA repository:
  73
  74 @code{M-x package-install RET excorporate}
  75
  76 @node Configuration
  77 @chapter Configuration
  78
  79 @noindent
  80 Ideally you won't need to configure Excorporate at all.  On friendly
  81 Exchange setups, Excorporate can discover the EWS URL automatically.
  82
  83 @noindent
  84 First try:
  85
  86 @code{M-x excorporate}
  87
  88 @noindent
  89 which will prompt you for the Exchange account email address.  Follow
  90 the prompts and if all goes well, you'll see a message in the
  91 minibuffer or in *Messages* saying that the connection is ready.
  92
  93 @noindent
  94 If autodiscovery runs out of URLs to try, then customize
  95 @code{excorporate-configuration}:
  96
  97 @code{M-x customize-variable RET excorporate-configuration}
  98
  99 @noindent
 100 From the value menu select ``Skip autodiscovery''.  This allows you to
 101 enter the Exchange account email address and the EWS URL directly.
 102 The EWS URL is of the form
 103 @code{https://mail.gnu.org/ews/exchange.asmx}.
 104
 105 @noindent
 106 After saving the configuration, try @code{M-x excorporate} again.
 107
 108 @noindent
 109 If that doesn't work, then you're probably out of luck, or you'll have
 110 to start a troubleshooting deep dive (@pxref{Troubleshooting}).
 111
 112 @node Usage
 113 @chapter Usage
 114
 115 @noindent
 116 Excorporate binds `e' in @code{*Calendar*} buffers.  Open the calendar
 117 with:
 118
 119 @code{M-x calendar}
 120
 121 @noindent
 122 move the cursor to the date you want to see meetings for, and press
 123 `e'.  This will show the meetings in a temporary read-only Org Mode
 124 buffer named @code{*Excorporate*}.
 125
 126 @node Troubleshooting
 127 @chapter Troubleshooting
 128
 129 @noindent
 130 First, you'll want to double-check that the Exchange server you're
 131 trying to access provides EWS support.  If it doesn't, Excorporate
 132 can't do anything for you.  Before asking your Exchange administrator,
 133 check intranet wikis and so forth; other users of non-standard clients
 134 may have already found the EWS URL.  This is called the ``EWS
 135 endpoint''.  I can be as simple as something like:
 136
 137 @code{https://mail.gnu.org/ews/exchange.asmx}
 138
 139 @noindent
 140 First you need to make sure you can access the endpoint.
 141
 142 @noindent
 143 For Exchange Web Services (EWS) which Excorporate uses, you'll have to
 144 determine the EWS endpoint for your Exchange account, call it
 145 @code{ews-url}.  It is usually something like:
 146
 147    https://<mail host name>/ews/exchange.asmx
 148
 149 @noindent
 150 Excorporate calculates the WSDL URL, call it @code{wsdl-url}, by
 151 replacing the endpoint's last path element with ``Services.wsdl'':
 152
 153    https://<mail host name>/ews/Services.wsdl
 154
 155 @noindent
 156 Before even attempting Excorporate, you have to make these succeed:
 157
 158 @example
 159 (with-current-buffer
 160  (url-retrieve-synchronously ews-url)
 161  (buffer-string))
 162 @end example
 163
 164 @noindent
 165 When this works, you'll see web page text in *Messages*, containing a
 166 message about having created a service.
 167
 168 @example
 169 (with-current-buffer
 170  (url-retrieve-synchronously wsdl-url)
 171  (buffer-string))
 172 @end example
 173
 174 @noindent
 175 When this works, it will show a bunch of WSDL (XML) in *Messages*.
 176
 177 @noindent
 178 Debug the above URL retrievals with (setq url-debug t), and with this
 179 patch:
 180
 181 @example
 182 diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
 183 index d49e527..0f1c8ae 100644
 184 --- a/lisp/url/url-http.el
 185 +++ b/lisp/url/url-http.el
 186 @@ -869,6 +869,7 @@ url-http-parse-headers
 187        (url-handle-content-transfer-encoding))
 188      (url-http-debug "Finished parsing HTTP headers: %S" success)
 189      (widen)
 190 +    (url-http-debug "Response: %s" (buffer-string))
 191      (goto-char (point-min))
 192      success))
 193
 194 @end example
 195
 196 @noindent
 197 (Beware that HTTP responses are out-of-order with this patch.)
 198
 199 @noindent
 200 Once you're sure the above steps are working, try @code{M-x
 201 excorporate}.
 202
 203 @noindent
 204 The buffer @code{*fsm-debug*} shows @code{excorporate} state
 205 transitions and should provide details of where things went wrong.
 206
 207 @noindent
 208 Also check @code{*Messages*} for anything obvious.
 209
 210 @noindent
 211 If you suspect something wrong with accessing the EWS URL, try setting
 212 @code{url-debug} to t and retry @code{M-x excorporate}, then check the
 213 @code{*URL-DEBUG*} buffer for output.
 214
 215 @noindent
 216 If you suspect NTLM authentication is failing, as a long shot, you
 217 might try setting @code{ntlm-compatibility-level} to 0 and retrying
 218 @code{M-x excorporate}.
 219
 220 @noindent
 221 Excorporate's dependencies implement the tricky elements of
 222 asynchronous Exchange access: a state machine (@code{fsm}), TLS
 223 negotiation (@code{gnutls}), NTLM authentication (@code{ntlm} and
 224 @code{url-http-ntlm}) and SOAP communication (@code{soap-client}).
 225
 226 @node Reporting Bugs
 227 @chapter Reporting Bugs
 228
 229 @noindent
 230 To report a bug, use @code{M-x report-emacs-bug}, and put Excorporate
 231 somewhere in the subject.
 232
 233 @bye