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 <n>* 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. <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.
<URL:ftp://ds.internic.net/rfc/rfc1738.txt>
[3] Crocker, D., "Standard for the Format of ARPA Internet Text
Messages", STD 11, RFC 822, UDEL, August 1982.
<URL:ftp://ds.internic.net/rfc/rfc1822.txt>
[4] Horton, M. and R. Adams, "Standard For Interchange of USENET
Messages", RFC 1036, AT&T Bell Laboratories, Center for
Seismic Studies, December 1987.
<URL:ftp://ds.internic.net/rfc/rfc1036.txt>
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]