mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 16:55:07 -05:00
c2e74a3033
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@4232 4b5297f7-1745-476d-ba37-a9c6900126ab
344 lines
12 KiB
XML
344 lines
12 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Out-of-Office Messages</title>
|
|
<abstract>This document defines an XMPP protocol extension for communicating out-of-office status.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0109</number>
|
|
<status>Experimental</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>XEP-0060, XEP-0163</dependencies>
|
|
<supersedes>None</supersedes>
|
|
<supersededby>None</supersededby>
|
|
<shortname>ooo</shortname>
|
|
<author>
|
|
<firstname>Darrell</firstname>
|
|
<surname>Piner</surname>
|
|
<email>dpiner@cisco.com</email>
|
|
<jid>dpiner@cisco.com</jid>
|
|
</author>
|
|
<author>
|
|
<firstname>Robert</firstname>
|
|
<surname>Norris</surname>
|
|
<email>rob@cataclysm.cx</email>
|
|
<jid>rob@cataclysm.cx</jid>
|
|
</author>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2010-05-24</date>
|
|
<initials>rdp</initials>
|
|
<remark>Modified specification to use PEP instead of a dedicated protocol; streamlined use cases; changed namespace to urn:xmpp:ooo:0.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2003-08-12</date>
|
|
<initials>rn</initials>
|
|
<remark>Added use cases for removing vacation settings; described semantics when start and end times are not specified; changed document type to Informational; small editorial changes.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2003-07-28</date>
|
|
<initials>rn</initials>
|
|
<remark>Initial version.</remark>
|
|
</revision>
|
|
</header>
|
|
|
|
<section1 topic='Introduction'>
|
|
<p>Popular electronic mail systems include features allowing users to set up
|
|
automated messages that are returned to message senders when the user is not
|
|
able to deal with the message immediately. This feature is commonly known as
|
|
"out-of-office" or "vacation" messages, because it is most commonly used when
|
|
a user is unable to read their messages because they are out of the office
|
|
(e.g., on vacation).</p>
|
|
<p>This document describes a similar system that enables XMPP users to setup
|
|
out-of-office messages when they are away.</p>
|
|
<p>The basis for the e-mail system mechanism is considering an incoming
|
|
message at the server level and determining whether to respond with a canned
|
|
out-of-office message. While a system may send a response for each incoming
|
|
message, many systems provide an optimization where a response to subsequent
|
|
e-mail messages is sent after some period of time expires.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Requirements'>
|
|
<p>The requirements for this feature are fairly straightforward. A user MUST be able to:</p>
|
|
|
|
<ul>
|
|
<li>Retrieve their current out-of-office settings.</li>
|
|
<li>Set new out-of-office settings.</li>
|
|
<li>Remove out-of-office settings.</li>
|
|
<li>Notify interested parties of the out-of-office settings when it
|
|
is in effect.</li>
|
|
</ul>
|
|
|
|
<p>All these requirements are satisfied by &xep0163;, which is a subset of &xep0060;.</p>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Format'>
|
|
<p>The out-of-office setting contains a start-time, an end-time and a
|
|
short message text.</p>
|
|
|
|
<example caption="Sample Out-of-Office message"><![CDATA[
|
|
<start>2003-07-06T10:30:00+10:00</start>
|
|
<end>2003-07-13T08:00:00+10:00</end>
|
|
<message>I'm attending OSCON in sunny Portland and won't be able to
|
|
read your message until I get back. If its urgent, please
|
|
send email to rob@cataclysm.cx.</message>
|
|
]]></example>
|
|
|
|
<p>The start and end times are informational only; i.e., the server does
|
|
nothing with these values other than store them. PEP does not include node
|
|
lifetime management (i.e., start and end times for the node); therefore, the server is unable
|
|
to enforce any start and end times included in the settings.</p>
|
|
|
|
<p>Using the PEP mechanism a client creates
|
|
out-of-office settings on a PEP node with the desired access model (such as Presence or Open). When
|
|
a user (or their client) sends presence containing CAPS (see &xep0115;) with an
|
|
entry for out-of-office to a contact with an out-of-office message, the user's
|
|
client is notified of the out-of-office message and may display, in a client-defined
|
|
fashion, the out-of-office settings information.</p>
|
|
|
|
<p>Clients may rely on the PEP node for notifications of changes as well as
|
|
automatic notification when the user logs-in (i.e., a user is notified of the
|
|
current item on the out-of-office PEP node of another user on sending initial
|
|
presence).</p>
|
|
</section1>
|
|
|
|
<section1 topic='Use cases'>
|
|
|
|
<section2 topic='Retrieving the current out-of-office settings'>
|
|
|
|
<p>A user may request their current out-of-office message by sending an IQ get to the local server like so:</p>
|
|
|
|
<example caption='Retrieving the current out-of-office settings'><![CDATA[
|
|
<iq type='get'
|
|
from='user@example.com'
|
|
to='example.com'
|
|
id='get1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<items node='urn:xmpp:ooo:0'/>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<example caption='Server returns out-of-office settings'><![CDATA[
|
|
<iq type='result'
|
|
from='example.com'
|
|
id='get1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub>
|
|
<items node='urn:xmpp:ooo:0>
|
|
<item id='current'>
|
|
<ooo xmlns='urn:xmpp:ooo:0'>
|
|
<start>2003-07-06T10:30:00+10:00</start>
|
|
<end>2003-07-13T08:00:00+10:00</end>
|
|
<message>I'm attending OSCON in sunny Portland and won't be able to
|
|
read your message until I get back. If its urgent, please
|
|
send email to rob@cataclysm.cx.</message>
|
|
</ooo>
|
|
</item>
|
|
</items>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<p>The <start/> and <end/> elements define the times between which this vacation
|
|
message should be considered valid by a supporting client; the times are in
|
|
the format specified by &xep0082;.</p>
|
|
|
|
<p>The <message/> element contains the text of the message which the client may
|
|
display for the user (when appropriate).</p>
|
|
|
|
<p>If the user has no stored vacation message, the user will receive a
|
|
result like the following:</p>
|
|
|
|
<example caption='User does not have any out-of-office settings'><![CDATA[
|
|
<iq type='result' id='get1'/>
|
|
]]></example>
|
|
|
|
</section2>
|
|
|
|
<section2 topic='Publishing new out-of-office settings'>
|
|
|
|
<p>A user may set new vacation message by publishing a new item with an id
|
|
of 'current' to the out-of-office node:</p>
|
|
|
|
<example caption='Publishing new out-of-office settings'><![CDATA[
|
|
<iq type='set'
|
|
from='user@example.com/client'
|
|
to='example.com'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='urn:xmpp:ooo:0'>
|
|
<item id='current'>
|
|
<ooo xmlns='urn:xmpp:ooo:0'>
|
|
<start>2003-07-06T10:30:00+10:00</start>
|
|
<end>2003-07-13T08:00:00+10:00</end>
|
|
<message>I'm attending OSCON in sunny Portland and won't be able to
|
|
read your message until I get back. If its urgent, please
|
|
send email to rob@cataclysm.cx.</message>
|
|
</ooo>
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<example caption='Out-of-office settings published successfully'><![CDATA[
|
|
<iq type='result'
|
|
from='example.com'
|
|
to='user@example.com/client'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='urn:xmpp:ooo:0'>
|
|
<item id='current'>
|
|
<ooo xmlns='urn:xmpp:ooo:0'>
|
|
<start>2003-07-06T10:30:00+10:00</start>
|
|
<end>2003-07-13T08:00:00+10:00</end>
|
|
<message>I'm attending OSCON in sunny Portland and won't be able to
|
|
read your message until I get back. If its urgent, please
|
|
send email to rob@cataclysm.cx.</message>
|
|
</ooo>
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<p>And by design, PEP sends a notification to all the user's resources.</p>
|
|
|
|
<example caption="PEP node notification sent to user"><![CDATA[
|
|
<message from='user@example.com'
|
|
id='notification_1781477179'
|
|
to='user@example.com/client' type='headline'>
|
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
|
<items node='urn:xmpp:ooo:0'>
|
|
<item id='current'>
|
|
<ooo xmlns='urn:xmpp:ooo:0'>
|
|
<start>2003-07-06T10:30:00+10:00</start>
|
|
<end>2003-07-13T08:00:00+10:00</end>
|
|
<message>I'm attending OSCON in sunny Portland and won't be able to
|
|
read your message until I get back. If its urgent, please
|
|
send email to rob@cataclysm.cx.</message>
|
|
</ooo>
|
|
</item>
|
|
</items>
|
|
</event>
|
|
</message>
|
|
]]></example>
|
|
|
|
<p>The meaning of each element is as outlined above. All elements are required.</p>
|
|
|
|
<p>Additionally, the <start/> and <end/> elements MAY be empty (i.e.,
|
|
have no CDATA). When <start/> is empty, the client MUST take this to mean
|
|
that the settings should take effect immediately. Similarly, when <end/>
|
|
is empty, the client MUST take this to mean that the settings should never
|
|
expire (unless they are explicitly removed).</p>
|
|
|
|
</section2>
|
|
|
|
<section2 topic='Removing out-of-office settings'>
|
|
|
|
<p>A user may remove all stored vacation settings by sending an IQ to the local server like so:</p>
|
|
|
|
<example caption='Remove vacation settings'><![CDATA[
|
|
<iq type='set'
|
|
from='user@example.com/client'
|
|
to='example.com'
|
|
it='retract1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<retract node='urn:xmpp:ooo:0'>
|
|
<item id='current' />
|
|
</retract>
|
|
</pubsub>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<example caption='Vacation settings removed successfully'><![CDATA[
|
|
<iq type='result'
|
|
from='example.com'
|
|
to='user@example.com/client'
|
|
id='retract1' />
|
|
]]></example>
|
|
|
|
<p>TODO: Is the Delete And Notify functionality described in XEP-0060
|
|
7.2.2.1 widely implemented? If so, should that case be included here?</p>
|
|
|
|
</section2>
|
|
|
|
<section2 topic='Hiding vacation settings'>
|
|
<p>In PEP, a node's default access model is 'presence' (i.e., any other user
|
|
with a subscription type "from" or "both" may subscribe to the node. PEP
|
|
provides other access models including a 'whitelist.' See &xep0060; section
|
|
4.5 for a list of Node Access Models.</p>
|
|
|
|
<p>The whitelist access model can be used to hide the current
|
|
out-of-office message. With an empty whitelist, no other users
|
|
receive notification when the node changes. The client may also use this
|
|
fact to allow the client's user to set up an out-of-office message
|
|
before it becomes active.</p>
|
|
|
|
<p>See &xep0060; Section 8.2 for details on configuration the out-of-office
|
|
node's access model.</p>
|
|
|
|
<p>See also &xep0223;.</p>
|
|
|
|
<p>PEP and PubSub allow for publishing an item and setting configuration on
|
|
a node. A user may wish to create an initial, hidden out-of-office
|
|
setting. They may do so by publishing an item with id='archive' and an
|
|
access model of 'whitelist.' When the user enables the
|
|
out-of-office settings, a configuration changing the access model
|
|
to some other mode sends notifications as defined by PEP.</p>
|
|
|
|
<p>TODO: add an example of publishing an item and setting configuration with
|
|
a single stanza i.e., find the appropriate example from &xep0060; or
|
|
&xep0163; and include it here.</p>
|
|
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Server requirements'>
|
|
<p>A server implementing out-of-office messages MUST implement
|
|
&xep0163;.</p>
|
|
</section1>
|
|
<section1 topic='Security Considerations'>
|
|
<p>None yet defined.</p>
|
|
</section1>
|
|
<section1 topic='IANA Considerations'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations'>
|
|
<p>The 'urn:xmpp:ooo:0' namespace shall be registered with the ®ISTRAR; as a result of this document.</p>
|
|
</section1>
|
|
|
|
<section1 topic='XML Schema'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:ooo:0'
|
|
xmlns='urn:xmpp:ooo:0'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:element name='item'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='start' minOccurs='0' maxOccurs='1' type='xs:string'/>
|
|
<xs:element name='end' minOccurs='0' maxOccurs='1' type='xs:string'/>
|
|
<xs:element name='message' minOccurs='0' maxOccurs='1' type='xs:string'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section1>
|
|
|
|
</xep>
|