[Search] [txt|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
       Internet-Draft                                     Bill Spencer, Ph.D.
       Scheduling Protocol                                      Mark M. Smith
       draft-spencer-swtp-00.txt                  Phase2 Software Corporation
       Expires in 6 months                                       24 June 1996
                      Scheduling Wide-area Transport Protocol
       1.  Status of this Document
       This document is an Internet-Draft.  Internet-Drafts are working docu-
       ments of the Internet Engineering Task Force (IETF),  its  areas,  and
       its  working groups.  Note that other groups may also distribute work-
       ing documents as Internet-Drafts.
       Internet-Drafts are draft documents valid for a maximum of six  months
       and  may  be updated, replaced, or obsoleted by other documents at any
       time.  It is inappropriate to use Internet-Drafts as  reference  mate-
       rial or to cite them other than as "work in progress."
       To  learn  the  current status of any Internet-Draft, please check the
       "1id-abstracts.txt" listing  contained in the  Internet-Drafts  Shadow
       Directories   on   ds.internic.net   (US  East  Coast),  nic.nordu.net
       (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
       2.  Abstract
       This  document  describes  the Scheduling Wide-area Transport Protocol
       (SWTP), a protocol designed to allow calendar and scheduling  informa-
       tion  repositories  to  be accessed in a uniform and consistent manner
       across the network.
       1.  Status of this Document .............................. 1
       2.  Abstract ............................................. 1
       3.  Overview ............................................. 4
       4.  History and Motivation for this Protocol ............. 4
           4.1  Enterprise-wide Scheduling ...................... 4
       5.   Protocol Overview ................................... 5
           5.1  Synchronous Requests ............................ 5
           5.2  Connecting via SWTP ............................. 5
       6.  Transport Services ................................... 6
           6.1  Transmission Control Protocol (TCP) ............. 6
       7.  Protocol Definitions ................................. 6
           7.1  Character strings ............................... 6
           7.2  Dates ........................................... 6
           7.3  Request Message ................................. 7
           7.4  Response Message ................................ 9
           7.5  Error Messages .................................. 9
       8.  Operations .......................................... 10
           8.1  Bind Operation ................................. 10
           8.2  Bindserver Operation ........................... 12
           8.3  Unbind Operation ............................... 12
           8.4  Id Operation ................................... 13
           8.5  List Operation ................................. 13
           8.6  Add Operation .................................. 14
           8.7  Replace Operation .............................. 14
           8.8  Delete Operation ............................... 15
           8.9  Compare Operation .............................. 15
           8.10 FreeTimeSearch Operation ....................... 15
           8.11 Projection Operation ........................... 15
           8.12 Confirmation Operation ......................... 15
           8.13 AccessPermission Operation ..................... 15
           8.14 Abandon Operation .............................. 15
           8.15 SetCalendar Operation .......................... 16
       9.  Name Directory Operations ........................... 16
           9.1  Add/Replace/Delete/List/Forward Name ........... 17
           9.2  Forward ........................................ 17
           9.3  Delete ......................................... 17
       10. Protocol Element Encodings .......................... 17
       11. Security Considerations ............................. 18
       12. Appendix A. Definition of Scheduling Operations ..... 20
       13. Appendix B. BNF Description of SWTP ................. 22
       14. Appendix C. Attribute Definitions ................... 26
           14.1 Event Attributes ............................... 26
           14.2 Name Attributes ................................ 29
           14.3 Other Attributes ............................... 30
       15. Appendix D. Access to a Demonstration Server ........ 32
       16. Appendix E. Bibliography ............................ 32
       17. Appendix F. Authors' Address ........................ 32
       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       3.  Overview
       The practical implications of widespread adoption of a scheduling pro-
       tocol  is  to  allow  easy  dissemination of calendar information like
       sports schedules, entertainment schedules, etc., and to allow users to
       invite  other  users to meetings, or to reserve resources like meeting
       rooms, or other mundane scheduling tasks by  passing  simple  messages
       across  the Internet. An important aspect of any scheduling service is
       that it interface consistently with existing directory services.  This
       protocol  is designed to work with RFC822 [3] compliant addresses like
       bspencer@p2software.com and in  the  future,  can  be  compliant  with
       directory access protocols such as LDAP [1].
       The protocol is designed to be simple, and "lightweight". A scheduling
       agent (or client software) does not need to know a  great  deal  about
       the  network  to  use this protocol.  All data elements are encoded as
       ordinary strings, and are managed in manner similar to other  internet
       Some  care  has  been taken here to define scheduling operations which
       are common to most commercial group scheduling software packages.   In
       this way, gateways to this protocol can be quickly built, and users of
       competing scheduling packages could communicate with each other.
       4.  History and Motivation for this Protocol
       4.1  Enterprise-wide Scheduling
       In the past, most group scheduling has confined itself to  just  that,
       groups.   Within  a  business,  engineering  formed a group, marketing
       formed a group, or a building defined a group.  If people  used  group
       schedulers  at  all,  each group would have its own scheduler, and ran
       that scheduler on its own preferred platform.  There was little commu-
       nication between scheduling software located in different locations.
       To extend this model to the larger enterprise, people will continue to
       work and schedule in groups, however those groups must  be  connected.
       Individual  groups  may  have their own scheduling server, however, it
       must appear to an individual scheduling within one logical group, that
       scheduling  an  individual  in  another  group, is exactly the same as
       scheduling one in the local group.
       We also must allow a wide variety of personal scheduling  software  to
       communicate with with other scheduling software across the enterprise.
       People are very attached to the interface presented by their  personal
       Spencer                                             [Page 4]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       scheduler, even though the basic attributes of an event can be handled
       by almost any scheduler.
       This is possible using the internet, and its  resources.   Scaling  to
       the enterprise level is done using a collection of servers communicat-
       ing via this protocol, instead of the massive mainframe,  or  high-end
       database  software  approach.   Third  party  scheduling  software can
       interoperate with  this  protocol  or  through  an  intermediate  HTTP
       5.  Protocol Overview
       The  model  for  this protocol is that of a client performing protocol
       operations against a server.  The client transmits a data set  includ-
       ing  an  operation, and a response format definition.  Upon completion
       of the request, the server returns a response containing  any  results
       or errors to the client.  In preparing the response, the server itself
       may act as a client to other SWTP servers on the  network.   There  is
       not  the  need  for  the  client to prepare multiple requests to other
       servers on the network, nor is there the need for the client to expect
       that  the  server  will refer the client to another server on the net-
       work.   Instead, the  server  will  initiate  the  contact,  and  pass
       through the results from the other server in the appropriate manner to
       the client.
       5.1  Synchronous Requests
       Certain of the protocol requests require  synchronicity.   The  client
       must  observe  this when requesting add/delete/modify, particularly of
       the same record.  The server will process the requests  in  the  order
       they  are  received, with the sole exception being the abort or unbind
       requests which will cause all pending requests to be removed, and back
       out of the current request as much as is possible.
       Generally,  multiple servers may be operating on the same data reposi-
       tory.  This eliminates the need for one server to manage multiple ses-
       5.2  Connecting via SWTP
       SWTP is connection oriented.  To utilize SWTP, the client must put the
       server through a binding process, followed by a sequence of  requested
       operations,  then an unbind operation.  In theory, there could be many
       clients maintaining open sessions  to  the  SWTP  server(s)  for  long
       Spencer                                             [Page 5]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       periods  of  time.   In  practice,  most  scheduling operations do not
       require remaining in an open session for a long period of time.  It is
       usually  more  of  a  retrieve and display operation.  When building a
       client, or gateway to the SWTP server, the developer is encouraged  to
       take  advantage  of  the long periods of wait time between user opera-
       tions to break the connection and re-establish it again.  This can  be
       especially  useful  for  users  utilizing expensive phone-line connec-
       6.  Transport Services
       This protocol is designed to run  over  connection-oriented,  reliable
       transports,  with all 8 bits in an octet being significant in the data
       stream.  Specifications for two underlying services are defined  here,
       though others are also possible.
       6.1  Transmission Control Protocol (TCP)
       Server  implementations running over the TCP should provide a protocol
       listener on port 5551. (Note: This is an unregistered user level port,
       and may change in later revisions of the document.)
       7.  Protocol Definitions
       7.1  Character strings
       Legal characters in the strings are encoded as 8 bit bytes, limited to
       the International IA5 character set.
       7.2  Dates
       Understanding when a event occurs requires three parameters:
         1.  The date using an unambiguous format (eg.  16-Oct-1996).  (Note:
             multiple formats are accepted, see the appendix for a full list.
         2.  The time formatted by a 24 hour clock (eg. 14:23).
       Spencer                                             [Page 6]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
         3.  The timezone.  This is always specified at the beginning of  the
             session  during  the "bind" operation.  Generally, the client is
             expected to specify its own timezone.  Timezones should be  gen-
             erally  specified  in a manner understood by the UNIX tzset sub-
             routine, or using the +/-hhmm offset described in RFC1036 [4].
       Communication between the client and the server will occur  using  the
       timezone  specified  by  the  client during the binding process.  This
       need not be UTC, or GMT!  The reason for this is that when  scheduling
       many  events,  we  must not only keep track of the universal time when
       the event occurs, but the day interval which surrounds it as well.
       Note that 9:00PM in New York on 16-Oct-1996 is the same time as 2:00AM
       on  17-Oct-1997  in  London,  so a date of 16-Oct-1996 is not the same
       world over.  Also note that an event occuring  every  Tuesday  in  New
       York,  may  occur  every  Wednesday when viewed from London.  Thus the
       definition of the day of the week is very dependent on  the  timezone,
       and it is insufficient to just give times in UTC based units when cou-
       pled with a repeating parameter.
       A more complicated example is an event which occurs on the  first  Wed
       of  January every year may on some years occur on Tueday of the previ-
       ous month in the previous year when viewed from a different  timezone.
       To  keep  all  this  straight,  and  to  allow for timezone definition
       changes in the future, it is beneficial to  be  able  to  perform  the
       extra computations in the server rather than communicate in UTC, which
       is the natural tendency for network communications.
       The protocol also allows the specification of the timezone for  commu-
       nication  of dates between the client and server for individual opera-
       tions.  Thus, an event scheduled in New York in EST, involving a meet-
       ing in San Francisco, can be specified as occuring at 2:00 PM PST.
       7.3  Request Message
       For  the  purposes  of protocol exchanges, all protocol request opera-
       tions are encapsulated in a common format, as follows:
       Spencer                                             [Page 7]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       ; swtprequest - This is the formulation of the message to the server
            messageID newline
            "operation =" operationname newline
            *[ attributename "=" attributevalue  newline ]
       (A full description of the protocol may be found in Appendix C.   This
       uses  the modified BNF form found in RFC1738 [2]. ) Note that all nor-
       mal request messages consist of a set of name-value pairs,  terminated
       by  a blank line.  All values are URI encoded (see description below).
       The sequence of possible name-value pairs is defined in an appendix.
       Depending on the value of the variable  with  name  "operation",  only
       certain  name-value  pairs have meaning in the context of a given mes-
       sage.  The 4 basic database operations are "add", "delete", "replace",
       and "list", which may be modified by "name" to gather or update infor-
       mation in the calendar directory service.  For  example  the  sequence
            operation=add name
       defines  that  this request is to add a named calendar to the calendar
       data repository.  There are an additional set  of  calendar  operation
       modifiers which combined cause special operations, for example,
            listtype="search 'other'"
       will  cause  a  listing of all events that contain the word "other" in
       them within the domain restricted by the other name=value pairs.
       The format for the request message is the same for all  SWTP  messages
       except  the  "id"  function described below.  The function of the SWTP
       message is to provide an envelope containing common fields required in
       all protocol exchanges. The only common field is the message ID, which
       is required to have a value different from the  values  of  any  other
       requests  outstanding  in  the SWTP session of which this message is a
       part.  The message ID "0" is treated as special.  A server receiving a
       message  ID  0 will stop processing the current operation, and perform
       ID 0 before continuing.  Generally use of this number is restricted to
       the   passing   of  the  "abort",  or  "unbind"  messages  which  will
       Spencer                                             [Page 8]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       discontinue any processing in an orderly fashion.
       7.4  Response Message
       The message ID value must be echoed  in  all  SWTP  message  envelopes
       encapsulting  responses  corresponding to the request contained in the
       SWTP message in which the message ID value was originally used.
       ; swtpresponse - This is the response of the server.
       ; A "0" response indicates success
       ; A "1" response indicates error
            messageID newline
            1*[ "0" newline |
            "0" data newline |
            "1" errormsg newline ]
       In the event of a success, a resultcode of 0 is returned, and optional
       set  of  data.  If a sequence of non-zero error responses is returned,
       there will be no "0" response.
       The data returned is a table of information  representing  a  list  of
       events,  tasks,  or calendar names.   The first line is an ordered set
       of attribute field names.  All subsequent lines contain  corresponding
       data in that same order.
       7.5  Error Messages
       In  the  event  of an error, the response SWTPmessage will have a non-
       zero response code, and an error message.  The error messages are for-
       matted with a numeric entry, followed by an English translation of the
       result code.  For example the result message:
            1  0023 Invalid user name: bill
       says that this is a response to message #1.  There is an  error,  with
       error  code  0023, which in English says that the user "bill" is not a
       valid user name.  The presence of the error  codes  allow  non-English
       Spencer                                             [Page 9]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       clients to translate the error codes to an appropriate language.
       8.  Operations
       This  is  the  list  of operations which the server may perform.  Each
       operation is specified within a message by the variable  name  "opera-
       tion". For example, the name=value pair of
       specifies the "bind" operation.
       8.1  Bind Operation
       The  function  of the Bind Operation is to initiate a protocol session
       between a client and a server, and to allow the authentication of  the
       client  to  the server. The Bind Operation must be the first operation
       request received by a server from a client in a protocol session.  The
       Bind Request is defined as follows:
       Parameters of the Bind Request are:
         version           A  version  number  indicating  the version of the
                           protocol to be  used  in  this  protocol  session.
                           Note  that this is set by the client.  The version
                           defined by this protocol definition is 2.
         user              The name of an allowed user of this  SWTP  server.
                           This  request  will  not  be  forwarded  to  other
                           servers, so if this name is  not  known  here,  it
       Spencer                                            [Page 10]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
         password          Initially  we  only do simple authentication.  The
                           password  is  unencrypted  and  easily   viewable.
                           Later versions are expected to have an authentica-
                           tion attribute, which could be set to kerberos for
                           example.  Then the password could be more complex.
         timezone          This indicates the timezone that the  conversation
                           between  the  server  and client will be conducted
                           in.  This may only be set once, at  the  beginning
                           of  the session.  All dates and times will be con-
                           verted by the server to this timezone.  All  dates
                           and  times  sent by the client will be interpreted
                           in this timezone.  Allowed values are those of the
                           tzset call in UNIX, or a numerical offset relative
                           to UTC (formerly GMT) in minutes (see [4]).   Note
                           that  repeating  events  which  cross the Daylight
                           savings time barrier prefer the use the tzset UNIX
                           format  to be treated correctly in all other time-
                           zones.  The interpretation of an  individual  time
                           may  be overridden by appending a time zone speci-
         currentdate       This is an optional field.  This is the  date  and
                           time  as  viewed  by the client in the given time-
                           zone.  This time formatted as specified in RFC1036
                           [4]. There are several other date formats commonly
                           recognized on the Internet, and it is  recommended
                           that  the  server  recognize these as well.  These
                           are also mentioned in [4].  The server  uses  this
                           to  validate  its  understanding  of  the time and
                           timezone reference of the client.   If  the  times
                           agree  within  15  minutes of each other, then the
                           server will continue  with  the  binding  process,
                           otherwise  an  error  will  be printed, giving the
                           server's understanding of the current time in  the
                           given timezone.  The client could make adjustments
                           and attempt a  re-connect,  or  the  client  could
                           choose  to  ignore  the  error,  and attempt a re-
                           connect without specifying this optional field.
         locale            This is an optional  field.   This  specifies  the
                           locale  of the client.  The primary effect here is
                           on the format of dates.  In version 2 of the  SWTP
                           server,  only  the  standard American date formats
                           and English weekday names  are  guaranteed  to  be
       Spencer                                            [Page 11]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
                           understood correctly.
       Upon  receipt of a Bind Request, the SWTP server will authenticate the
       requesting client, and set up a protocol session with that client. The
       server will then return a response to the client indicating the status
       of the session setup request.  Note that the bind operation is  always
       the first request, and usually is given the messageID of 1.
       8.2  Bindserver Operation
       This operation is to facilitate server to server communication.
       For the purposes of allowing unknown servers to connect as a client to
       a given server, the name "anonymous" using the permissions granted  to
       anonymous  by  the  local administrator are used.  It is expected that
       the anonymous name will use a password of the e-mail address  obtained
       by  the  "id" operation.  Known servers are known by "Name" located at
       DomainName, and are given a Password.  This allows  known  servers  to
       have a higher level of access permission than the anonymous name would
       allow.  Servers may maintain their own set of Name and  Passwords  for
       accessing  different servers through the network.  Authenticated peers
       should have the "Full" permission level to allow complete  transparent
       inter-server scheduling.
       8.3  Unbind Operation
       The  function  of the Unbind Operation is to terminate a protocol ses-
       sion.  The Unbind Operation is defined as follows:
       Upon receipt of the unbind request, the SWTP server will terminate the
       session.   The  use  of  messageID 0 is not required here.  The use of
       messageID 0 will terminate all processing of all current operations if
       Spencer                                            [Page 12]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       There is no response required from this request.
       8.4  Id Operation
       This  request  may be performed on any server, without first authenti-
       cating, or binding to the server.  The operation  simply  consists  of
       "id"  followed  by  two  newline's.   The server will respond with the
       date, time and timezone of the server, the fully qualified domainname,
       a  serial  number  and product name, and optionally, an e-mail address
       which can be used to report problems.  The response message is  termi-
       nated by two newline's.
       8.5  List Operation
       The  List  operation  outputs  information about events on the current
       calendar.  Rather than outputing all information, the desired list  of
       attributes may be specified to minimize the response size.
            messageID newline
            "operation = list" newline
            [ "attributes = " 1*attributename newline ]
            [ "listtype" = SearchCriteria newline ]
            [ "sizeLimit =" digits newline ]
            [ "timeLimit =" digits newline ]
            daterange |
            searchpattern |
            taskonly |
            eventonly |
            undonetasks |
       Parameters of the List Request are:
         sizeLimit         A  sizelimit  that restricts the maximum number of
                           entries to be returned as a result of the list.  A
                           value  of  0 in this field indicates that no size-
                           limit restrictions are in effect for the list.
       Spencer                                            [Page 13]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
         timelimit         A timelimit that restricts  th  maximum  time  (in
                           seconds)  allowed for a list. A value of 0 in this
                           field indicates that no timelimit restrictions are
                           in effect for the list.
         listtype          A  filter that defines the conditions that must be
                           fulfilled in order for a given entry to be listed.
         attributes        A  list of the attributes from each entry found as
                           a result of the list operation to be returned.  An
                           empty list signifies that all attributes from each
                           entry found  in  the  list  operation  are  to  be
                           returned.  Attributes which the user/calendar does
                           not have permission to see  will  be  returned  as
                           empty  fields.   Several  special  attributes  are
                           defined for the purposes of being confirmcookie --
                           a  magic  number indicating that this event can be
                           confirmed by  a  sending  the  server  an  unbound
                           cookie message in the form of an HTTP message.
       8.6  Add Operation
       The  add  operation adds an event to the calendar database.  There are
       three major complicating factors.  The first is a conflict check, con-
       firming  that no attendees have a conflict at the indicated time.  The
       second is resource pooling, allowing the server to  select  at  random
       one  or  more resources from a pool of resources that may be available
       at the indicated time. And third  is  setting  up  a  methodology  for
       another user confirming that they can attend an event.
       The  conflict check returns an error if the flag "ignoreconflicts" has
       not been set and there  are  timing  conflicts  between  resources  or
       users.   Users  of the FreeTimeSearch operation should still check for
       this error, even if a time has previously been found to be free.
       The  add  operation  also  allows  the  definition  of  "non-standard"
       attributes.   These  attributes  allow  developers  to define links to
       other databases through unique  id  fields,  or  whatever  they  need.
       There  is  a  set of standard attributes  and reserved attribute names
       defined in a separate document.
       8.7  Replace Operation
       This takes the new attributes, replaces them  in  an  existing  event,
       then  replaces that event in the database.  The same conditions of the
       Spencer                                            [Page 14]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       "Add" operation apply here.
       8.8  Delete Operation
       This deletes the existing event.  If the user is not the originator of
       the  event, it is only deleted within their schedule.  A deleted event
       serves to indicate that a person will not attend a  given  event.   If
       the  event  is  updated  by the originator, and the users name has not
       been removed from the original list, the user will again be  scheduled
       for the event.
       8.9  Compare Operation
       Find  an  event  in  the current schedule matching the attributes set.
       The list operation is generally better at finding events than this.
       8.10  FreeTimeSearch Operation
       This operation searches for the next n  freetimes  for  the  indicated
       event within a specified timerange.
       8.11  Projection Operation
       This  operation displays a projection of the busy times for a calendar
       or calendars during a time interval.
       8.12  Confirmation Operation
       This operation confirms a persons attendance at an event.  This is  an
       isolated  operation,  which  is  performed  without a "bind".  A magic
       cookie value is used to bind to the server, perform  the  confirmation
       then automatically unbind.  Only an acknowledgement that the operation
       has been performed is given.
       8.13  AccessPermission Operation
       This operation sets/resets the permissions other  users  have  to  the
       current calendar.  Note that this is an attribute of the calendar, not
       of the user.  Thus, it is a calendar operation, not a  Name  Directory
       8.14  Abandon Operation
       The  function of the Abandon Operation is to allow a client to request
       that the server abandon an outstanding operation.  The Abandon Request
       is defined as follows:
       Spencer                                            [Page 15]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
            messageID newline
            "operation=abandon" newline
            "messageid=" messageID
       There  is no response defined in the Abandon Operation. Upon transmis-
       sion of an Abandon Operation, a client may expect that  the  operation
       identityfied  by  the Message ID in the Abandon Request has been aban-
       doned. In the event that a server receives an  Abandon  Request  on  a
       Search  Operation  in  the  midst  of  transmitting  responses to that
       search, that server should cease transmitting responses to  the  aban-
       doned search immediately.
       8.15  SetCalendar Operation
       This  operation  changes  the current calendar to another calendar, or
       group of calendars.  The success of this operation is  heavily  depen-
       dant on the permission structure allowed for the currently bound user.
       9.  Name Directory Operations
       Names within the SWTP protocol mirror the  RFC822  [3]  mail  counter-
       parts.   The schedule for Bill Spencer at p2software.com is maintained
       as bspencer@p2software.com.  Unlike  mail,  there  are  addresses  for
       resources,  for  example  projector1@p2software.com,  or equivalently,
       calendar addresses can be set up for projects or any activity.   Since
       there  are  often  reasons to not use a persons mail address for their
       calendar address, the calendar address must always be viewed as  sepa-
       rate  from  the  mail  address.   Also, group objects, such as a group
       called "projectors" can have a modifier to select one or  more  avail-
       able  resources  from  that  group,  in  which case it is addressed as
       Locally, SWTP  maintains a directory of 7 different  types  of  names.
       These  are user schedule names, resource schedule names, remote server
       names, group names, local system names,  aliases,  and  remote  names.
       All  SWTP servers with full scheduling capability within an enterprise
       maintain at minimum their own local user, resource, and group schedule
       names,  as well as redundant information about servers on the network.
       Remote names are maintained for convenience only.  These  are  created
       on  a  temporary  basis  when a local scheduling operation occurs, and
       Spencer                                            [Page 16]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       confirmed with the remote SWTP server.  If  the  name  on  the  remote
       server  is  modified,  changes  do  not occur immediately on the local
       server, but any scheduling operation will cause an update of the  name
       information to occur.  In this way the directory information regarding
       remote names is not always up to date, but self-corrects in the appro-
       priate way over time.
       The SWTP server hides many of the ugly attributes of the management of
       these names, however, at a later time this may be supplanted by direct
       connections to an LDAP [1] server.
       9.1  Add/Replace/Delete/List/Forward Name
       These  are  the set of operations which may be performed on a schedule
       name.  The add, replace,  and list operations  are  standard  database
       operations  which  use  the  set  of attributes given in the Appendix.
       These operations are encapsulated in the same type of message  as  the
       calendar operation.
       9.2  Forward
       Forward  allows  a calendar to be moved from one server to another (or
       within the same server) without disruption of events already scheduled
       for  that  calendar.   Unlike  mail, the fact that a calendar has been
       forwarded is automatically passed back to local server,  so  a  remote
       name  reference  will  be updated to the new forwarded name as part of
       the self-correcting nature of the SWTP directory.
       9.3  Delete
       The delete operation under standard database rules can  cause  hideous
       referential  integrity  problems  in  a  wide-area scheduling service.
       Rather than try  to  trace  all  references  to  a  name  within  that
       database,  these  references are allowed to persist.  When referenced,
       these references are indicated as being  UNKNOWN,  and  then  dropped.
       This  allows  the  referential  integrity  of the database to be self-
       correcting over time, without incurring the  overhead  of  maintaining
       exact referential integrity.
       10.  Protocol Element Encodings
       All  variables  and constructs passed to and from the server are indi-
       vidually 'URI-encoded'.  This encoding is described in section 2.2  of
       [2].   In a URI encoded string an escape sequence is a percent charac-
       ter ("%") followed by two hexadecimal digits which form an  OCTET.   A
       Spencer                                            [Page 17]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       newline  (see  the  definition  in  Appendix  C)  is used to delimit a
       name=value pair, and the messageID.  The message starts with the first
       non-newline  character,  and  is  terminated with a newline.  Thus the
       message ends with two sequential  newlines,  one  for  delimiting  the
       final parameter, and the other for delimiting the envelope.
       11.  Security Considerations
       There  are  basic  security  mechanisms  which are required for proper
       operation of SWTP.  These are
         1.  User authentication for session binding purposes. At the present
             time  the protocol only provides for simple authentication using
             a cleartext password.
         2.  Permission levels permitting or denying access to  other  calen-
             dars after binding.  SWTP recognizes 6 different levels of secu-
             rity here.
             Full                A user is granted  full  access  to  another
                                 persons calendar and may modify schedules as
                                 if that user.
             ViewInvite          A user may view another calendar, and invite
                                 that  person to meetings, but may not other-
                                 wise modify that calendar.
             Invite              A user may invite another to  meetings,  and
                                 determine  if  that person is available, but
                                 may not view specific data on that calendar.
             ViewOnly            A  user  may  view another schedule, but not
                                 invite that person to meetings.
             None                A user may not view  another  calendar,  nor
                                 invite them to meetings.
         3.  An  administrative  permission  level.   This  is the user named
             "admin" within the local server's directory.  This user can per-
             form  neccessary  housekeeping  functions  within the server, in
             particular, the maintenance of the directory.
       The SWTP server takes care of handling  these  permission  levels.   A
       request  for  a listing of events from another calendar which you have
       "None" permission will yield no listing.  A  request  for  listing  of
       events  from  another calendar which you have "Invite" permission will
       Spencer                                            [Page 18]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       yield a list of events, but with no details other than date  and  time
       filled in.
       Spencer                                            [Page 19]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       12.  Appendix A. Definition of Scheduling Operations
        Operation                             Description
       add name            Add  a  new directory entry to the list.  Uses the
                           name attributes defined in Appendix  C.   Requires
                           administrator level permission.
       add                 Add  a new event or task entry to the current cal-
                           endar.   Uses  the  event  attributes  defined  in
                           Appendix C.
       bind                Bind  the  named  user into the session.  Requires
                           attributes "user", "password", "timezone".
       bindserver          Bind the named server into the session.   Requires
                           the attributes "name", "password", ...
       confirm             Confirm  attendance  at  an  event.   Requires the
                           attributes  "event_id",  "user",  "calendar",  and
       delete name         Delete  a directory entry from the list.  Uses the
                           name attributes defined in Appendix  C.   Requires
                           administrator level permission.
       delete              Delete an event.  Requires the attribute event_id.
                           Requires full permission to current calendar.
       forward name        Enter a forwarding record  into the current calen-
                           dar's directory to indicate that this named direc-
                           tory entry has moved to a new location.   Requires
                           the  attributes "handle", of the new address.  The
                           new address must already exist.  No existing  cal-
                           endar  data  is  forwarded,  but the local data is
                           automatically deleted.  It  is  assumed  that  the
                           data  has already been forwarded using other means
                           within this protocol.  Requires full permission to
                           the current calendar, and to the forwarding calen-
       Spencer                                            [Page 20]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       freetime            Do a free time  search.   Uses  event  attributes,
                           "workhours", "workdays", "searchmax", and "search-
                           days".  Returns an array of  "date",   "time"  and
                           "projection", which match the required conditions.
                           No more than "searchmax" matches will be returned.
       list name           List users registered on the current server.  Uses
       list                List events on the current calendar or  calendars.
                           Uses "listtype".
       modify name         Modify  the attributes of a directory entry.  Uses
                           the  name  attributes.   Requires   administrative
                           level permission.
       modify              Modify the attributes of an event.  Uses the event
                           attributes.  The "event_id" must be specified.
       projection          Produce a projection of  available  time  for  the
                           current   calendar(s).    Requires   "searchdays",
                           "interval", "date".
       setcalendar         Set the current calendar to be one or more  calen-
                           dars.  Uses "calendar".
       unbind              Terminate a session.
       Spencer                                            [Page 21]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       13.  Appendix B. BNF Description of SWTP
       This  is  a  BNF-like description of the SWTP syntax, using the syntax
       conventions found in RFC1738.   Briefly,  "|"  is  used  to  designate
       alternatives,  and  brackets  []  are used around optional or repeated
       elements, literals are quoted with "", optional elements are  enclosed
       in  [brackets],  and elements may be preceded with <n>* to designate n
       or more repetitions of the following element; n defaults to 0.
       ; swtpsession - A generic view of the connection
            specialrequest |
            *[ swtprequest swtpresponse ]
       ; swtprequest - This is the formulation of the message to the server
            messageID newline
            "operation =" operationname newline ; ignore space around '='
            *[ attributename "=" attributevalue  newline ]
       ; swtpresponse - This is the response of the server.
       ; A "0" response indicates success
       ; A "1" response indicates error
            messageID newline
            1*[ "0" newline |
            "0" data newline |
            "1" errormsg newline ]
       ; These are the operations which can be requested of the server
            "list"  |
            "setcalendar" |
            "add"  |
            "delete" |
            "modify" |
            "confirm" |
            "freetime" |
            "projection" |
            "accesspermission" |
       Spencer                                            [Page 22]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
            "add name" |
            "delete name" |
            "list name" |
            "forward name" |
            "modify name" |
            "bind" |
            "bindserver" |
       ; This describes the data returned by a server request.
       ; It is always in table format.
            *[attributename fieldsep] attributename recordsep
            *[attributevalue fieldsep] attributevalue recordsep
       ; Although the cr-lf pair is the definition, servers should be able to accept
       ; a single '\n' or a single '\r' as a delimeter
       ; This is a list of attributes recognized by the SWTP server.
            "date" |
            "due date" |
            "start date" |
            "repeat" |
            "duration" |
            "time" |
            "subject" |
            "task" |
            "type" |
            "users" |
            "attendees" |
            "delegate to" |
            "send to" |
            "resources" |
       Spencer                                            [Page 23]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
            "location" |
            "who_did_it" |
            "scheduled by" |
            "sent by" |
            "delegated by" |
            "originator" |
            "event_id" |
            "priority" |
            "project" |
            "status" |
            "done_date" |
            "event_status" |
            "r_msg" |
            "r_cmd" |
            "old_who" |
            "last_modified" |
            "scheduler" |
            "task_duration" |
            "task_start_date" |
            "desc_fp" |
            "description" |
            "timezone" |
            "pid" |
            "userId" |
            "name" |
            "handle" |
            "description" |
            "commonName" |
            "owner" |
            "administrator" |
            "mailaddress" |
            "rfc822mailbox" |
            "password" |
            "userPassword" |
            "server" |
            "fqdnServer" |
            "members" |
            "type" |
            "attr" |
            "where" |
            "perm" |
       Spencer                                            [Page 24]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
            "formatted" |
            "attributes" |
            "operation" |
            "sizeLimit" |
            "timeLimit" |
            "searchdays" |
            "searchmax" |
            "workdays" |
            "workhours" |
            eventattributename |
            nameattributename |
       ; The repeat syntax is specified here, because it's too complicated to
       ; put into words.  It relys on the date having been specified.
       ; In the examples , the date is May 15, 1996
            "yearly" |     ; yearly on this May 15
            "yearly every" nth 1*weekday |     ; yearly every 3rd Sun in May
            "monthly" |    ; monthly on the 15th of the month
            "monthly every" nth 1*weekday |    ; monthly, every 3rd Sun
            "On the" nth "month," |  ; Every 3rd month, on the 15th
            "every" 1*weekday | ; weekly on  Sun, Mon
            "every" nth 1*weekday |  ; every 3rd Sun
            "Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat"
            "1st" | "2nd" | "3rd" | "4th" | "5th" | "6th"
       This completes the BNF definition of the protocol with  the  exception
       of  the  definition  of  attributevalue,  and a specification of which
       attributes are appropriate for a given operation.  These can be speci-
       fied  in a BNF format, however a more useful reference are the follow-
       ing tables, which allows a discussion of some of the attributes.  Some
       attributes are very complex in themselves, for example "repeat".
       Spencer                                            [Page 25]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       14.  Appendix C. Attribute Definitions
       This  defines  the  attributes understood by the SWTP server.  In some
       cases, the same attribute may go by multple names.  These  are  listed
       as  a  group  to the left of the description.  The attributevalues are
       always individually URI-encoded.
       14.1  Event Attributes
          Attribute                          Description
       date             The date of the event, the due date of the  task,  or
       due date         the  starting  date  of  a  repeating  event or task.
       start date       Dates should be input in the form  day-month-year  as
                        in  13-Oct-1996,  or  13-10-1996.  The former is pre-
                        ferred as it leads to less confusion with some  other
                        styles  of  date  presentation.   The  year should be
                        specified with its full four  digits.   If  only  two
                        digits  are  present,  it  will automatically be con-
                        verted to a year less than 50  years  away  from  the
                        present  date,  either  in  the  future  or  the past
                        depending upon which is closer.  To specify a date in
                        the year 96 A.D., use 13-Oct-0096.
       repeat           See below for a BNF description of the repeat syntax.
       duration         Durations   are   normally   specified  in  the  form
                        hours:minutes, for example, 2:35 is 2 hours  35  min-
                        utes.   For  long  events, lasting days, use the form
                        days:hours:minutes.  For example 31:2:35 is 31  days,
                        2 hours, 35  minutes.
       time             Time  is  specified  on a 24 hour clock, as in 18:32,
                        which is 6:32PM.  An optional timezone may be  speci-
                        fied, as in 18:32 PDT, or 18:32 EST.  If the timezone
                        is not known, then an offset to UTC may be  specified
                        as  18:32  +0630  or 18:32 -0630.  This gives a 6 and
                        one half hour offset from UTC east or west of the UTC
                        zone  respectively.   Setting  the  timezone here, is
                        identical to setting the timezone field listed below.
       subject          A  short  description  of the event or task, suitable
       task             for identification. Maximum of 128 characters.
       type             This has allowed values "event", or "task", with  the
                        default being "event".
       Spencer                                            [Page 26]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       users            A  comma  separated  list  of  schedules, or users on
       attendees        whose calendars this task or event will appear.   The
       delegate to      format  for  specifying  a  name uses the RFC822 mail
       send to          address syntax.  Names local to  the  current  server
                        may  be specified without using the host server name.
                        Groups may be specified, but the group name  must  be
                        known  within  the context of the current server, and
                        will be resolved to an appropriate list of names.  In
                        a  later  specification, it is expected that a brack-
                        eted set of attributes [ ] will describe confirmation
                        status,  and  resource  pooling  by  appending to the
       resources        For the purposes of  this  protocol,  a  resource  is
                        identical  to  an  attendee.  The distinction is made
                        because client software may wish to handle  conflicts
                        differently for resources, than for users.
       location         The  location  of the event.  This is often not used,
                        as the location is put in the description. Maximum of
                        128 characters.
       originator       The  name  of  the user, or calendar which originated
       who_did_it       this event.
       scheduled by
       event_id         The event_id must be unique across all  SWTP  systems
                        and  all  events. Although the actual format is arbi-
                        trary, the format used  on  the  first  SWTP  systems
                        embeds  a  product identifier, a serial number, and a
                        sequential number into a 32 character field.  Another
                        alternative  is  to embed the servers fully qualified
                        domain name with a sequential number.   The  event_id
                        is created and assigned by the server.
       priority         The priority has values of "hi", "med", and "lo", and
                        is primarily used for ranking tasks.
       project          A field used to categorize tasks or  events.  Maximum
       category         of 32 characters.
       status           The  status  of  a  task.   Has values of "done", and
                        "undone".  done_date T{ The date the  task  was  com-
                        pleted.  This is a date, and not a time.
       Spencer                                            [Page 27]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       event_status     A  flag  indicating  that this is a new event, or has
                        changed recently.  This is useful to client  software
                        in announcing changed events to users.  Has values of
                        "not read", or "attention", or "clear".
       r_msg            Reserved. Later this may be used as a  reminder  mes-
                        sage to be sent to the calendar owner.
       r_cmd            Reserved.   Later this may be used as a reminder com-
                        mand to be executed at the reminder offset.
       old_who          If  a  task  is  re-delegated,  this  points  to  the
       r_offset         Reserved.   Later this may be used as an offset indi-
                        cating the amount  of  time  prior  to  the  event  a
                        reminder needs to be sent.  Measured in minutes.
       last_modified    The  date  and  time (UTC) of when the event was last
                        modified.  Read only.
       scheduler        Indicates whether the originator should  be  included
                        in   the  list  of  attendees  or  not.   Has  values
                        "include" or "exclude".
       task_duration    Reserved. Later this may be  used  to  represent  the
                        number of man-hours required for a given task.
       task_start_date  Reserved.   Later  this  may be used to represent the
                        actual starting date of a task.
       desc_fp          This is  an  identifier  which  is  assigned  by  the
                        server,  and is used as a pointer to the description.
                        In the case of the same description being assigned to
                        multiple  events,  storage  space  can  be  saved  by
                        retrieving this value, and using it  instead  of  the
                        description on subsequent events.
       description      This  field  is  of  arbitrary  length,  and  gives a
                        detailed description of the event.
       timezone         Specifies the timezone for which to  interpret  dates
                        for this event.
       Spencer                                            [Page 28]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       calendar         Specifies  the  calendar this event appears in.  This
                        is single valued.
       extensions       A free field, with a minimum of 256 characters  which
                        can be used to relate an event with some other exter-
                        nal application.  The proper form for information  in
                        this  field  is for example "APP_special_id=234xabc".
                        This indicates that application  APP  is  related  to
                        this  field with special_id "234xabc".  Multiple name
                        value pairs should be separated by "&".
       confirmcookie    This is a read-only field, and is a string of charac-
                        ters  which  uniquely identify this event, the calen-
                        dar, and the list of attendees.  This is used by  the
                        confirm  operation  to allow users who may not other-
                        wise have access to a calendar to perform  a  confirm
                        operation on the indicated event.
       14.2  Name Attributes
         Attribute                            Description
       pid                 An  internal  id  maintained  by the local server.
       userId              This id should be used when modifying names on the
                           local server.
       name                The  name of the calendar resource, calendar user,
       handle              group, alias, or server.  For example, "bill".  If
                           this  is  a  remote user, or remote resource, this
                           should be qualified with  the  appropriate  domain
                           name.   If  this  is a server name, it should be a
                           fully qualified hostname.
       description         A  more  descriptive  name,   like   "William   P.
       commonName          Spencer".  Because this attribute name matches one
                           used in LDAP, users are encouraged to use the full
                           name  of  the  user.  For a resource, a commonName
                           like "Conference Room 316" is appropriate, with  a
                           handle of "conf316".
       owner               Resources  require administrators, as well as some
       administrator       user calendars, and servers.  This is  the  handle
                           of the user who administers this entity.  For most
                           users, this is identical to the users handle.
       Spencer                                            [Page 29]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       mailaddress         The electronic mail address of the user who should
       rfc822mailbox       receive  mail about this calendar.  Generally this
                           should be the owner's mail address.
       password            A password used to identify access to this  calen-
       userPassword        dar  through the "bind" operation.  In the initial
                           release of this specification, this provides  only
                           minimal  security  through the use of a clear text
       server              The server on which the calendar for this user  or
       fqdnServer          resource resides.  If the handle is a fully quali-
                           fied domain name, then this server should coincide
                           with  that  information.  A value of "LocalServer"
                           means that the information resides on  the  local-
       members             A  comma  separated  list  of users, resources, or
                           other groups which make up this  group.   If  this
                           name is an alias, then only one name should appear
       type                The type of entry.  Valid  values  are  "invalid",
                           "user",    "resource",   "group",   "alias",   and
       perm                This is a read-only value, and specifies the  type
                           of  permission  this user and calendar has to this
                           calendar  resource.   Valid  values  are   "None",
                           "Check",  "ViewOnly",  "ViewInvite", "InviteOnly",
                           and "Full" .
       14.3  Other Attributes
        Attribute                             Description
       formatted           Reserved.  Later this  attribute  will  specify  a
                           format  for  presenting  a  event.   As  part of a
                           response from the server, this is will be the for-
                           matted event itself.
       attributes          This  specifies  the  list  of  attributes  to  be
                           returned as a response.
       Spencer                                            [Page 30]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       operation           This specifies the  operation  the  server  should
       sizeLimit           This specifies the maximum number of event records
                           to be returned by a "list"  operation.  "0"  indi-
                           cates no limit.
       timeLimit           This  specifies  the maximum number of seconds the
                           server should work on a response to a "list" oper-
                           ation. "0" indicates forever.
       currentdate         This  is  the  date  and  time as perceived by the
                           client during the bind process.   The  format  for
                           this  date is "weekday day-mon-year hh:mm:ss time-
                           zone", for example "Tuesday 13-OCT-1996 14:03:1996
       calendar            A  comma  separated list of calendars used as part
                           of the setcalendar operation.
       workdays            In a free time search use only these days as  part
                           of       the       search.       For      example,
       workhours           In a free time search use only these hours as part
                           to  the search.  The format is timestart-timestop,
                           for example, "8:00-18:30".  A timezone  specifica-
                           tion is not allowed here.
       interval            The  time  interval  granualarity in minutes for a
                           "projection".   The default is 15 minutes.
       projection          A projection is a string of characters, 1  charac-
                           ter per time "interval", which indicates free time
                           within a period defined  by  "workhours".   A  '0'
                           indicates  that  the  time  is  available, and any
                           other single digit indicates the  number  of  con-
                           flicts  at  that  particular time.  If that number
                           exceeds 9, then a
       Spencer                                            [Page 31]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       15.  Appendix D. Access to a Demonstration Server
       A   prototype   version   of   this   server    is    accessible    at
       www.p2software.com,  on  port  5551.   Both a perl-based API, and a C-
       based API, in source code format are available. Software for utilizing
       Netscape  or  other  browser  as  a client is also avaliable in source
       form.  Please send e-mail  to  bspencer@p2software.com,  and  we  will
       respond  with  the  requirements  for accessing it. Please include the
       keyword "SWTP" in the subject line of your e-mail.
       The ClockWise(R) scheduling data repository is used as the  basis  for
       this server.
       16.  Appendix E. Bibliography
       [1]       Yeong,  W.,  Howes, T., and S. Kille, "Lightweight Directory
                 Access Protocol," RFC  1777,  Performance  Systems  Interna-
                 tional,  University  of  Michigan,  ISODE  Consortium, March
                 1995.  <URL:ftp://ds.internic.net/rfc/rfc1777.txt>
       [2]       Berners-Lee, T., Masinter, L.,  and  M.  McCahill,  Editors,
                 "Uniform  Resource  Locators  (URL)",  RFC 1738, CERN, Xerox
                 Corporation,  University  of   Minnesota,   December   1994.
       [3]       Crocker,  D., "Standard for the Format of ARPA Internet Text
                 Messages",   STD   11,   RFC   822,   UDEL,   August   1982.
       [4]       Horton, M. and R. Adams, "Standard For Interchange of USENET
                 Messages", RFC 1036,  AT&T  Bell  Laboratories,  Center  for
                 Seismic           Studies,           December          1987.
       17.  Appendix F. Authors' Address
       Bill Spencer, Ph.D.
       Phase II Software Corporation
       910 Boston Post Road, #260
       Marlboro, MA  01752
       Spencer                                            [Page 32]

       Internet-Draft    SWTP Scheduling Protocol        June, 1996
       Mark M. Smith
       Phase II Software Corporation
       910 Boston Post Road, #260
       Marlboro, MA  01752
       Spencer                                            [Page 33]