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 SWTP 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. CONTENTS 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 i 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 ii 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 protocols. 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 server. 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- sions. 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- tions. 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 swtprequest: messageID newline "operation =" operationname newline *[ attributename "=" attributevalue newline ] newline messageID: 1*[digits] (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 item 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'" operation=list 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 swtpresponse: messageID newline 1*[ "0" newline | "0" data newline | "1" errormsg newline ] 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 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 operation=bind 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: 1 operation=bind user=UserName password=Password version=SWTPversion timezone=Timezone [currentdate=date] [locale=Locale] 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 fails. 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- fication. 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. operation=bindserver name=Name password=Password version=SWTPversion timezone=Timezone currentdate=date 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: 0 operation=unbind 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 necessary. 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. ListRequest: messageID newline "operation = list" newline [ "attributes = " 1*attributename newline ] [ "listtype" = SearchCriteria newline ] [ "sizeLimit =" digits newline ] [ "timeLimit =" digits newline ] newline SearchCriteria: daterange | searchpattern | taskonly | eventonly | undonetasks | category 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 operation. 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 abandon: messageID newline "operation=abandon" newline "messageid=" messageID newline 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 1*projectors@p2software.com. 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 "confirmcookie". 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- dar. 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 "listtype". 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 * to designate n or more repetitions of the following element; n defaults to 0. ; swtpsession - A generic view of the connection swtpsession: specialrequest | *[ swtprequest swtpresponse ] ; swtprequest - This is the formulation of the message to the server swtprequest: messageID newline "operation =" operationname newline ; ignore space around '=' *[ attributename "=" attributevalue newline ] newline messageID: 1*[digits] ; swtpresponse - This is the response of the server. ; A "0" response indicates success ; A "1" response indicates error swtpresponse: messageID newline 1*[ "0" newline | "0" data newline | "1" errormsg newline ] newline ; These are the operations which can be requested of the server operationname: "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" | "unbind" ; This describes the data returned by a server request. ; It is always in table format. data: headerrow *[datarows] headerrow: *[attributename fieldsep] attributename recordsep datarow: *[attributevalue fieldsep] attributevalue recordsep recordsep: "\r\n" fieldsep: "&" ; Although the cr-lf pair is the definition, servers should be able to accept ; a single '\n' or a single '\r' as a delimeter newline: "\r\n" ; This is a list of attributes recognized by the SWTP server. eventattributename: "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" | "calendar" nameattributename: "pid" | "userId" | "name" | "handle" | "description" | "commonName" | "owner" | "administrator" | "mailaddress" | "rfc822mailbox" | "password" | "userPassword" | "server" | "fqdnServer" | "members" | "type" | "attr" | "where" | "perm" | "dbname" Spencer [Page 24] Internet-Draft SWTP Scheduling Protocol June, 1996 otherattributename: "formatted" | "attributes" | "operation" | "sizeLimit" | "timeLimit" | "searchdays" | "searchmax" | "workdays" | "workhours" | "interval" attributename: eventattributename | nameattributename | otherattributename ; 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 repeat: "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 weekday: "Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" nth: "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 name. 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 assignee. 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 passwarod. 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- host. 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 here. type The type of entry. Valid values are "invalid", "user", "resource", "group", "alias", and "server". 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 perform. 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 EST" 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, "Mon,Tue,Wed,Thu,Fri". 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. [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 bspencer@p2software.com 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 msmith@p2software.com Spencer [Page 33]