idnits 2.17.1 draft-spencer-swtp-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** There are 390 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 588 instances of too long lines in the document, the longest one being 12 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 13 has weird spacing: '...), its areas...' == Line 14 has weird spacing: '... its worki...' == Line 18 has weird spacing: '... and may ...' == Line 19 has weird spacing: '...afts as refer...' == Line 22 has weird spacing: '... To learn...' == (385 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (24 June 1996) is 10167 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '3' on line 1289 looks like a reference -- Missing reference section? '1' on line 1279 looks like a reference -- Missing reference section? '4' on line 1293 looks like a reference -- Missing reference section? '2' on line 1284 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 8 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft Bill Spencer, Ph.D. 3 Scheduling Protocol Mark M. Smith 4 draft-spencer-swtp-00.txt Phase2 Software Corporation 5 Expires in 6 months 24 June 1996 7 Scheduling Wide-area Transport Protocol 8 SWTP 10 1. Status of this Document 12 This document is an Internet-Draft. Internet-Drafts are working docu- 13 ments of the Internet Engineering Task Force (IETF), its areas, and 14 its working groups. Note that other groups may also distribute work- 15 ing documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference mate- 20 rial or to cite them other than as "work in progress." 22 To learn the current status of any Internet-Draft, please check the 23 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 24 Directories on ds.internic.net (US East Coast), nic.nordu.net 25 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 27 2. Abstract 29 This document describes the Scheduling Wide-area Transport Protocol 30 (SWTP), a protocol designed to allow calendar and scheduling informa- 31 tion repositories to be accessed in a uniform and consistent manner 32 across the network. 34 CONTENTS 36 1. Status of this Document .............................. 1 38 2. Abstract ............................................. 1 40 3. Overview ............................................. 4 42 4. History and Motivation for this Protocol ............. 4 43 4.1 Enterprise-wide Scheduling ...................... 4 45 5. Protocol Overview ................................... 5 46 5.1 Synchronous Requests ............................ 5 47 5.2 Connecting via SWTP ............................. 5 49 6. Transport Services ................................... 6 50 6.1 Transmission Control Protocol (TCP) ............. 6 52 7. Protocol Definitions ................................. 6 53 7.1 Character strings ............................... 6 54 7.2 Dates ........................................... 6 55 7.3 Request Message ................................. 7 56 7.4 Response Message ................................ 9 57 7.5 Error Messages .................................. 9 59 8. Operations .......................................... 10 60 8.1 Bind Operation ................................. 10 61 8.2 Bindserver Operation ........................... 12 62 8.3 Unbind Operation ............................... 12 63 8.4 Id Operation ................................... 13 64 8.5 List Operation ................................. 13 65 8.6 Add Operation .................................. 14 66 8.7 Replace Operation .............................. 14 67 8.8 Delete Operation ............................... 15 68 8.9 Compare Operation .............................. 15 69 8.10 FreeTimeSearch Operation ....................... 15 70 8.11 Projection Operation ........................... 15 71 8.12 Confirmation Operation ......................... 15 72 8.13 AccessPermission Operation ..................... 15 73 8.14 Abandon Operation .............................. 15 74 8.15 SetCalendar Operation .......................... 16 76 9. Name Directory Operations ........................... 16 78 i 79 9.1 Add/Replace/Delete/List/Forward Name ........... 17 80 9.2 Forward ........................................ 17 81 9.3 Delete ......................................... 17 83 10. Protocol Element Encodings .......................... 17 85 11. Security Considerations ............................. 18 87 12. Appendix A. Definition of Scheduling Operations ..... 20 89 13. Appendix B. BNF Description of SWTP ................. 22 91 14. Appendix C. Attribute Definitions ................... 26 92 14.1 Event Attributes ............................... 26 93 14.2 Name Attributes ................................ 29 94 14.3 Other Attributes ............................... 30 96 15. Appendix D. Access to a Demonstration Server ........ 32 98 16. Appendix E. Bibliography ............................ 32 100 17. Appendix F. Authors' Address ........................ 32 102 ii 103 3. Overview 105 The practical implications of widespread adoption of a scheduling pro- 106 tocol is to allow easy dissemination of calendar information like 107 sports schedules, entertainment schedules, etc., and to allow users to 108 invite other users to meetings, or to reserve resources like meeting 109 rooms, or other mundane scheduling tasks by passing simple messages 110 across the Internet. An important aspect of any scheduling service is 111 that it interface consistently with existing directory services. This 112 protocol is designed to work with RFC822 [3] compliant addresses like 113 bspencer@p2software.com and in the future, can be compliant with 114 directory access protocols such as LDAP [1]. 116 The protocol is designed to be simple, and "lightweight". A scheduling 117 agent (or client software) does not need to know a great deal about 118 the network to use this protocol. All data elements are encoded as 119 ordinary strings, and are managed in manner similar to other internet 120 protocols. 122 Some care has been taken here to define scheduling operations which 123 are common to most commercial group scheduling software packages. In 124 this way, gateways to this protocol can be quickly built, and users of 125 competing scheduling packages could communicate with each other. 127 4. History and Motivation for this Protocol 129 4.1 Enterprise-wide Scheduling 131 In the past, most group scheduling has confined itself to just that, 132 groups. Within a business, engineering formed a group, marketing 133 formed a group, or a building defined a group. If people used group 134 schedulers at all, each group would have its own scheduler, and ran 135 that scheduler on its own preferred platform. There was little commu- 136 nication between scheduling software located in different locations. 138 To extend this model to the larger enterprise, people will continue to 139 work and schedule in groups, however those groups must be connected. 140 Individual groups may have their own scheduling server, however, it 141 must appear to an individual scheduling within one logical group, that 142 scheduling an individual in another group, is exactly the same as 143 scheduling one in the local group. 145 We also must allow a wide variety of personal scheduling software to 146 communicate with with other scheduling software across the enterprise. 147 People are very attached to the interface presented by their personal 148 scheduler, even though the basic attributes of an event can be handled 149 by almost any scheduler. 151 This is possible using the internet, and its resources. Scaling to 152 the enterprise level is done using a collection of servers communicat- 153 ing via this protocol, instead of the massive mainframe, or high-end 154 database software approach. Third party scheduling software can 155 interoperate with this protocol or through an intermediate HTTP 156 server. 158 5. Protocol Overview 160 The model for this protocol is that of a client performing protocol 161 operations against a server. The client transmits a data set includ- 162 ing an operation, and a response format definition. Upon completion 163 of the request, the server returns a response containing any results 164 or errors to the client. In preparing the response, the server itself 165 may act as a client to other SWTP servers on the network. There is 166 not the need for the client to prepare multiple requests to other 167 servers on the network, nor is there the need for the client to expect 168 that the server will refer the client to another server on the net- 169 work. Instead, the server will initiate the contact, and pass 170 through the results from the other server in the appropriate manner to 171 the client. 173 5.1 Synchronous Requests 175 Certain of the protocol requests require synchronicity. The client 176 must observe this when requesting add/delete/modify, particularly of 177 the same record. The server will process the requests in the order 178 they are received, with the sole exception being the abort or unbind 179 requests which will cause all pending requests to be removed, and back 180 out of the current request as much as is possible. 182 Generally, multiple servers may be operating on the same data reposi- 183 tory. This eliminates the need for one server to manage multiple ses- 184 sions. 186 5.2 Connecting via SWTP 188 SWTP is connection oriented. To utilize SWTP, the client must put the 189 server through a binding process, followed by a sequence of requested 190 operations, then an unbind operation. In theory, there could be many 191 clients maintaining open sessions to the SWTP server(s) for long 192 periods of time. In practice, most scheduling operations do not 193 require remaining in an open session for a long period of time. It is 194 usually more of a retrieve and display operation. When building a 195 client, or gateway to the SWTP server, the developer is encouraged to 196 take advantage of the long periods of wait time between user opera- 197 tions to break the connection and re-establish it again. This can be 198 especially useful for users utilizing expensive phone-line connec- 199 tions. 201 6. Transport Services 203 This protocol is designed to run over connection-oriented, reliable 204 transports, with all 8 bits in an octet being significant in the data 205 stream. Specifications for two underlying services are defined here, 206 though others are also possible. 208 6.1 Transmission Control Protocol (TCP) 210 Server implementations running over the TCP should provide a protocol 211 listener on port 5551. (Note: This is an unregistered user level port, 212 and may change in later revisions of the document.) 214 7. Protocol Definitions 216 7.1 Character strings 218 Legal characters in the strings are encoded as 8 bit bytes, limited to 219 the International IA5 character set. 221 7.2 Dates 223 Understanding when a event occurs requires three parameters: 225 1. The date using an unambiguous format (eg. 16-Oct-1996). (Note: 226 multiple formats are accepted, see the appendix for a full list. 227 ) 229 2. The time formatted by a 24 hour clock (eg. 14:23). 231 3. The timezone. This is always specified at the beginning of the 232 session during the "bind" operation. Generally, the client is 233 expected to specify its own timezone. Timezones should be gen- 234 erally specified in a manner understood by the UNIX tzset sub- 235 routine, or using the +/-hhmm offset described in RFC1036 [4]. 237 Communication between the client and the server will occur using the 238 timezone specified by the client during the binding process. This 239 need not be UTC, or GMT! The reason for this is that when scheduling 240 many events, we must not only keep track of the universal time when 241 the event occurs, but the day interval which surrounds it as well. 243 Note that 9:00PM in New York on 16-Oct-1996 is the same time as 2:00AM 244 on 17-Oct-1997 in London, so a date of 16-Oct-1996 is not the same 245 world over. Also note that an event occuring every Tuesday in New 246 York, may occur every Wednesday when viewed from London. Thus the 247 definition of the day of the week is very dependent on the timezone, 248 and it is insufficient to just give times in UTC based units when cou- 249 pled with a repeating parameter. 251 A more complicated example is an event which occurs on the first Wed 252 of January every year may on some years occur on Tueday of the previ- 253 ous month in the previous year when viewed from a different timezone. 254 To keep all this straight, and to allow for timezone definition 255 changes in the future, it is beneficial to be able to perform the 256 extra computations in the server rather than communicate in UTC, which 257 is the natural tendency for network communications. 259 The protocol also allows the specification of the timezone for commu- 260 nication of dates between the client and server for individual opera- 261 tions. Thus, an event scheduled in New York in EST, involving a meet- 262 ing in San Francisco, can be specified as occuring at 2:00 PM PST. 264 7.3 Request Message 266 For the purposes of protocol exchanges, all protocol request opera- 267 tions are encapsulated in a common format, as follows: 269 ; swtprequest - This is the formulation of the message to the server 270 swtprequest: 271 messageID newline 272 "operation =" operationname newline 273 *[ attributename "=" attributevalue newline ] 274 newline 276 messageID: 277 1*[digits] 279 (A full description of the protocol may be found in Appendix C. This 280 uses the modified BNF form found in RFC1738 [2]. ) Note that all nor- 281 mal request messages consist of a set of name-value pairs, terminated 282 by a blank line. All values are URI encoded (see description below). 283 The sequence of possible name-value pairs is defined in an appendix. 285 Depending on the value of the variable with name "operation", only 286 certain name-value pairs have meaning in the context of a given mes- 287 sage. The 4 basic database operations are "add", "delete", "replace", 288 and "list", which may be modified by "name" to gather or update infor- 289 mation in the calendar directory service. For example the sequence 290 item 292 operation=add name 294 defines that this request is to add a named calendar to the calendar 295 data repository. There are an additional set of calendar operation 296 modifiers which combined cause special operations, for example, 298 listtype="search 'other'" 299 operation=list 301 will cause a listing of all events that contain the word "other" in 302 them within the domain restricted by the other name=value pairs. 304 The format for the request message is the same for all SWTP messages 305 except the "id" function described below. The function of the SWTP 306 message is to provide an envelope containing common fields required in 307 all protocol exchanges. The only common field is the message ID, which 308 is required to have a value different from the values of any other 309 requests outstanding in the SWTP session of which this message is a 310 part. The message ID "0" is treated as special. A server receiving a 311 message ID 0 will stop processing the current operation, and perform 312 ID 0 before continuing. Generally use of this number is restricted to 313 the passing of the "abort", or "unbind" messages which will 314 discontinue any processing in an orderly fashion. 316 7.4 Response Message 318 The message ID value must be echoed in all SWTP message envelopes 319 encapsulting responses corresponding to the request contained in the 320 SWTP message in which the message ID value was originally used. 322 ; swtpresponse - This is the response of the server. 323 ; A "0" response indicates success 324 ; A "1" response indicates error 325 swtpresponse: 326 messageID newline 327 1*[ "0" newline | 328 "0" data newline | 329 "1" errormsg newline ] 330 newline 332 In the event of a success, a resultcode of 0 is returned, and optional 333 set of data. If a sequence of non-zero error responses is returned, 334 there will be no "0" response. 336 The data returned is a table of information representing a list of 337 events, tasks, or calendar names. The first line is an ordered set 338 of attribute field names. All subsequent lines contain corresponding 339 data in that same order. 341 7.5 Error Messages 343 In the event of an error, the response SWTPmessage will have a non- 344 zero response code, and an error message. The error messages are for- 345 matted with a numeric entry, followed by an English translation of the 346 result code. For example the result message: 348 1 349 1 0023 Invalid user name: bill 351 says that this is a response to message #1. There is an error, with 352 error code 0023, which in English says that the user "bill" is not a 353 valid user name. The presence of the error codes allow non-English 354 clients to translate the error codes to an appropriate language. 356 8. Operations 358 This is the list of operations which the server may perform. Each 359 operation is specified within a message by the variable name "opera- 360 tion". For example, the name=value pair of 362 operation=bind 364 specifies the "bind" operation. 366 8.1 Bind Operation 368 The function of the Bind Operation is to initiate a protocol session 369 between a client and a server, and to allow the authentication of the 370 client to the server. The Bind Operation must be the first operation 371 request received by a server from a client in a protocol session. The 372 Bind Request is defined as follows: 374 1 375 operation=bind 376 user=UserName 377 password=Password 378 version=SWTPversion 379 timezone=Timezone 380 [currentdate=date] 381 [locale=Locale] 383 Parameters of the Bind Request are: 385 version A version number indicating the version of the 386 protocol to be used in this protocol session. 387 Note that this is set by the client. The version 388 defined by this protocol definition is 2. 390 user The name of an allowed user of this SWTP server. 391 This request will not be forwarded to other 392 servers, so if this name is not known here, it 393 fails. 395 password Initially we only do simple authentication. The 396 password is unencrypted and easily viewable. 397 Later versions are expected to have an authentica- 398 tion attribute, which could be set to kerberos for 399 example. Then the password could be more complex. 401 timezone This indicates the timezone that the conversation 402 between the server and client will be conducted 403 in. This may only be set once, at the beginning 404 of the session. All dates and times will be con- 405 verted by the server to this timezone. All dates 406 and times sent by the client will be interpreted 407 in this timezone. Allowed values are those of the 408 tzset call in UNIX, or a numerical offset relative 409 to UTC (formerly GMT) in minutes (see [4]). Note 410 that repeating events which cross the Daylight 411 savings time barrier prefer the use the tzset UNIX 412 format to be treated correctly in all other time- 413 zones. The interpretation of an individual time 414 may be overridden by appending a time zone speci- 415 fication. 417 currentdate This is an optional field. This is the date and 418 time as viewed by the client in the given time- 419 zone. This time formatted as specified in RFC1036 420 [4]. There are several other date formats commonly 421 recognized on the Internet, and it is recommended 422 that the server recognize these as well. These 423 are also mentioned in [4]. The server uses this 424 to validate its understanding of the time and 425 timezone reference of the client. If the times 426 agree within 15 minutes of each other, then the 427 server will continue with the binding process, 428 otherwise an error will be printed, giving the 429 server's understanding of the current time in the 430 given timezone. The client could make adjustments 431 and attempt a re-connect, or the client could 432 choose to ignore the error, and attempt a re- 433 connect without specifying this optional field. 435 locale This is an optional field. This specifies the 436 locale of the client. The primary effect here is 437 on the format of dates. In version 2 of the SWTP 438 server, only the standard American date formats 439 and English weekday names are guaranteed to be 440 understood correctly. 442 Upon receipt of a Bind Request, the SWTP server will authenticate the 443 requesting client, and set up a protocol session with that client. The 444 server will then return a response to the client indicating the status 445 of the session setup request. Note that the bind operation is always 446 the first request, and usually is given the messageID of 1. 448 8.2 Bindserver Operation 450 This operation is to facilitate server to server communication. 452 operation=bindserver 453 name=Name 454 password=Password 455 version=SWTPversion 456 timezone=Timezone 457 currentdate=date 459 For the purposes of allowing unknown servers to connect as a client to 460 a given server, the name "anonymous" using the permissions granted to 461 anonymous by the local administrator are used. It is expected that 462 the anonymous name will use a password of the e-mail address obtained 463 by the "id" operation. Known servers are known by "Name" located at 464 DomainName, and are given a Password. This allows known servers to 465 have a higher level of access permission than the anonymous name would 466 allow. Servers may maintain their own set of Name and Passwords for 467 accessing different servers through the network. Authenticated peers 468 should have the "Full" permission level to allow complete transparent 469 inter-server scheduling. 471 8.3 Unbind Operation 473 The function of the Unbind Operation is to terminate a protocol ses- 474 sion. The Unbind Operation is defined as follows: 476 0 477 operation=unbind 479 Upon receipt of the unbind request, the SWTP server will terminate the 480 session. The use of messageID 0 is not required here. The use of 481 messageID 0 will terminate all processing of all current operations if 482 necessary. 484 There is no response required from this request. 486 8.4 Id Operation 488 This request may be performed on any server, without first authenti- 489 cating, or binding to the server. The operation simply consists of 490 "id" followed by two newline's. The server will respond with the 491 date, time and timezone of the server, the fully qualified domainname, 492 a serial number and product name, and optionally, an e-mail address 493 which can be used to report problems. The response message is termi- 494 nated by two newline's. 496 8.5 List Operation 498 The List operation outputs information about events on the current 499 calendar. Rather than outputing all information, the desired list of 500 attributes may be specified to minimize the response size. 502 ListRequest: 503 messageID newline 504 "operation = list" newline 505 [ "attributes = " 1*attributename newline ] 506 [ "listtype" = SearchCriteria newline ] 507 [ "sizeLimit =" digits newline ] 508 [ "timeLimit =" digits newline ] 509 newline 511 SearchCriteria: 512 daterange | 513 searchpattern | 514 taskonly | 515 eventonly | 516 undonetasks | 517 category 519 Parameters of the List Request are: 521 sizeLimit A sizelimit that restricts the maximum number of 522 entries to be returned as a result of the list. A 523 value of 0 in this field indicates that no size- 524 limit restrictions are in effect for the list. 526 timelimit A timelimit that restricts th maximum time (in 527 seconds) allowed for a list. A value of 0 in this 528 field indicates that no timelimit restrictions are 529 in effect for the list. 531 listtype A filter that defines the conditions that must be 532 fulfilled in order for a given entry to be listed. 534 attributes A list of the attributes from each entry found as 535 a result of the list operation to be returned. An 536 empty list signifies that all attributes from each 537 entry found in the list operation are to be 538 returned. Attributes which the user/calendar does 539 not have permission to see will be returned as 540 empty fields. Several special attributes are 541 defined for the purposes of being confirmcookie -- 542 a magic number indicating that this event can be 543 confirmed by a sending the server an unbound 544 cookie message in the form of an HTTP message. 546 8.6 Add Operation 548 The add operation adds an event to the calendar database. There are 549 three major complicating factors. The first is a conflict check, con- 550 firming that no attendees have a conflict at the indicated time. The 551 second is resource pooling, allowing the server to select at random 552 one or more resources from a pool of resources that may be available 553 at the indicated time. And third is setting up a methodology for 554 another user confirming that they can attend an event. 556 The conflict check returns an error if the flag "ignoreconflicts" has 557 not been set and there are timing conflicts between resources or 558 users. Users of the FreeTimeSearch operation should still check for 559 this error, even if a time has previously been found to be free. 561 The add operation also allows the definition of "non-standard" 562 attributes. These attributes allow developers to define links to 563 other databases through unique id fields, or whatever they need. 564 There is a set of standard attributes and reserved attribute names 565 defined in a separate document. 567 8.7 Replace Operation 569 This takes the new attributes, replaces them in an existing event, 570 then replaces that event in the database. The same conditions of the 571 "Add" operation apply here. 573 8.8 Delete Operation 575 This deletes the existing event. If the user is not the originator of 576 the event, it is only deleted within their schedule. A deleted event 577 serves to indicate that a person will not attend a given event. If 578 the event is updated by the originator, and the users name has not 579 been removed from the original list, the user will again be scheduled 580 for the event. 582 8.9 Compare Operation 584 Find an event in the current schedule matching the attributes set. 585 The list operation is generally better at finding events than this. 587 8.10 FreeTimeSearch Operation 589 This operation searches for the next n freetimes for the indicated 590 event within a specified timerange. 592 8.11 Projection Operation 594 This operation displays a projection of the busy times for a calendar 595 or calendars during a time interval. 597 8.12 Confirmation Operation 599 This operation confirms a persons attendance at an event. This is an 600 isolated operation, which is performed without a "bind". A magic 601 cookie value is used to bind to the server, perform the confirmation 602 then automatically unbind. Only an acknowledgement that the operation 603 has been performed is given. 605 8.13 AccessPermission Operation 607 This operation sets/resets the permissions other users have to the 608 current calendar. Note that this is an attribute of the calendar, not 609 of the user. Thus, it is a calendar operation, not a Name Directory 610 operation. 612 8.14 Abandon Operation 614 The function of the Abandon Operation is to allow a client to request 615 that the server abandon an outstanding operation. The Abandon Request 616 is defined as follows: 618 abandon: 619 messageID newline 620 "operation=abandon" newline 621 "messageid=" messageID 622 newline 624 There is no response defined in the Abandon Operation. Upon transmis- 625 sion of an Abandon Operation, a client may expect that the operation 626 identityfied by the Message ID in the Abandon Request has been aban- 627 doned. In the event that a server receives an Abandon Request on a 628 Search Operation in the midst of transmitting responses to that 629 search, that server should cease transmitting responses to the aban- 630 doned search immediately. 632 8.15 SetCalendar Operation 634 This operation changes the current calendar to another calendar, or 635 group of calendars. The success of this operation is heavily depen- 636 dant on the permission structure allowed for the currently bound user. 638 9. Name Directory Operations 640 Names within the SWTP protocol mirror the RFC822 [3] mail counter- 641 parts. The schedule for Bill Spencer at p2software.com is maintained 642 as bspencer@p2software.com. Unlike mail, there are addresses for 643 resources, for example projector1@p2software.com, or equivalently, 644 calendar addresses can be set up for projects or any activity. Since 645 there are often reasons to not use a persons mail address for their 646 calendar address, the calendar address must always be viewed as sepa- 647 rate from the mail address. Also, group objects, such as a group 648 called "projectors" can have a modifier to select one or more avail- 649 able resources from that group, in which case it is addressed as 650 1*projectors@p2software.com. 652 Locally, SWTP maintains a directory of 7 different types of names. 653 These are user schedule names, resource schedule names, remote server 654 names, group names, local system names, aliases, and remote names. 655 All SWTP servers with full scheduling capability within an enterprise 656 maintain at minimum their own local user, resource, and group schedule 657 names, as well as redundant information about servers on the network. 658 Remote names are maintained for convenience only. These are created 659 on a temporary basis when a local scheduling operation occurs, and 660 confirmed with the remote SWTP server. If the name on the remote 661 server is modified, changes do not occur immediately on the local 662 server, but any scheduling operation will cause an update of the name 663 information to occur. In this way the directory information regarding 664 remote names is not always up to date, but self-corrects in the appro- 665 priate way over time. 667 The SWTP server hides many of the ugly attributes of the management of 668 these names, however, at a later time this may be supplanted by direct 669 connections to an LDAP [1] server. 671 9.1 Add/Replace/Delete/List/Forward Name 673 These are the set of operations which may be performed on a schedule 674 name. The add, replace, and list operations are standard database 675 operations which use the set of attributes given in the Appendix. 676 These operations are encapsulated in the same type of message as the 677 calendar operation. 679 9.2 Forward 681 Forward allows a calendar to be moved from one server to another (or 682 within the same server) without disruption of events already scheduled 683 for that calendar. Unlike mail, the fact that a calendar has been 684 forwarded is automatically passed back to local server, so a remote 685 name reference will be updated to the new forwarded name as part of 686 the self-correcting nature of the SWTP directory. 688 9.3 Delete 690 The delete operation under standard database rules can cause hideous 691 referential integrity problems in a wide-area scheduling service. 692 Rather than try to trace all references to a name within that 693 database, these references are allowed to persist. When referenced, 694 these references are indicated as being UNKNOWN, and then dropped. 695 This allows the referential integrity of the database to be self- 696 correcting over time, without incurring the overhead of maintaining 697 exact referential integrity. 699 10. Protocol Element Encodings 701 All variables and constructs passed to and from the server are indi- 702 vidually 'URI-encoded'. This encoding is described in section 2.2 of 703 [2]. In a URI encoded string an escape sequence is a percent charac- 704 ter ("%") followed by two hexadecimal digits which form an OCTET. A 705 newline (see the definition in Appendix C) is used to delimit a 706 name=value pair, and the messageID. The message starts with the first 707 non-newline character, and is terminated with a newline. Thus the 708 message ends with two sequential newlines, one for delimiting the 709 final parameter, and the other for delimiting the envelope. 711 11. Security Considerations 713 There are basic security mechanisms which are required for proper 714 operation of SWTP. These are 716 1. User authentication for session binding purposes. At the present 717 time the protocol only provides for simple authentication using 718 a cleartext password. 720 2. Permission levels permitting or denying access to other calen- 721 dars after binding. SWTP recognizes 6 different levels of secu- 722 rity here. 724 Full A user is granted full access to another 725 persons calendar and may modify schedules as 726 if that user. 728 ViewInvite A user may view another calendar, and invite 729 that person to meetings, but may not other- 730 wise modify that calendar. 732 Invite A user may invite another to meetings, and 733 determine if that person is available, but 734 may not view specific data on that calendar. 736 ViewOnly A user may view another schedule, but not 737 invite that person to meetings. 739 None A user may not view another calendar, nor 740 invite them to meetings. 742 3. An administrative permission level. This is the user named 743 "admin" within the local server's directory. This user can per- 744 form neccessary housekeeping functions within the server, in 745 particular, the maintenance of the directory. 746 The SWTP server takes care of handling these permission levels. A 747 request for a listing of events from another calendar which you have 748 "None" permission will yield no listing. A request for listing of 749 events from another calendar which you have "Invite" permission will 750 yield a list of events, but with no details other than date and time 751 filled in. 753 12. Appendix A. Definition of Scheduling Operations 755 Operation Description 756 ----------------------------------------------------------------------- 757 add name Add a new directory entry to the list. Uses the 758 name attributes defined in Appendix C. Requires 759 administrator level permission. 761 add Add a new event or task entry to the current cal- 762 endar. Uses the event attributes defined in 763 Appendix C. 765 bind Bind the named user into the session. Requires 766 attributes "user", "password", "timezone". 768 bindserver Bind the named server into the session. Requires 769 the attributes "name", "password", ... 771 confirm Confirm attendance at an event. Requires the 772 attributes "event_id", "user", "calendar", and 773 "confirmcookie". 775 delete name Delete a directory entry from the list. Uses the 776 name attributes defined in Appendix C. Requires 777 administrator level permission. 779 delete Delete an event. Requires the attribute event_id. 780 Requires full permission to current calendar. 782 forward name Enter a forwarding record into the current calen- 783 dar's directory to indicate that this named direc- 784 tory entry has moved to a new location. Requires 785 the attributes "handle", of the new address. The 786 new address must already exist. No existing cal- 787 endar data is forwarded, but the local data is 788 automatically deleted. It is assumed that the 789 data has already been forwarded using other means 790 within this protocol. Requires full permission to 791 the current calendar, and to the forwarding calen- 792 dar. 794 freetime Do a free time search. Uses event attributes, 795 "workhours", "workdays", "searchmax", and "search- 796 days". Returns an array of "date", "time" and 797 "projection", which match the required conditions. 798 No more than "searchmax" matches will be returned. 800 list name List users registered on the current server. Uses 801 "listtype". 803 list List events on the current calendar or calendars. 804 Uses "listtype". 806 modify name Modify the attributes of a directory entry. Uses 807 the name attributes. Requires administrative 808 level permission. 810 modify Modify the attributes of an event. Uses the event 811 attributes. The "event_id" must be specified. 813 projection Produce a projection of available time for the 814 current calendar(s). Requires "searchdays", 815 "interval", "date". 817 setcalendar Set the current calendar to be one or more calen- 818 dars. Uses "calendar". 820 unbind Terminate a session. 822 13. Appendix B. BNF Description of SWTP 824 This is a BNF-like description of the SWTP syntax, using the syntax 825 conventions found in RFC1738. Briefly, "|" is used to designate 826 alternatives, and brackets [] are used around optional or repeated 827 elements, literals are quoted with "", optional elements are enclosed 828 in [brackets], and elements may be preceded with * to designate n 829 or more repetitions of the following element; n defaults to 0. 831 ; swtpsession - A generic view of the connection 832 swtpsession: 833 specialrequest | 834 *[ swtprequest swtpresponse ] 836 ; swtprequest - This is the formulation of the message to the server 837 swtprequest: 838 messageID newline 839 "operation =" operationname newline ; ignore space around '=' 840 *[ attributename "=" attributevalue newline ] 841 newline 843 messageID: 844 1*[digits] 846 ; swtpresponse - This is the response of the server. 847 ; A "0" response indicates success 848 ; A "1" response indicates error 849 swtpresponse: 850 messageID newline 851 1*[ "0" newline | 852 "0" data newline | 853 "1" errormsg newline ] 854 newline 856 ; These are the operations which can be requested of the server 857 operationname: 858 "list" | 859 "setcalendar" | 860 "add" | 861 "delete" | 862 "modify" | 863 "confirm" | 864 "freetime" | 865 "projection" | 866 "accesspermission" | 867 "add name" | 868 "delete name" | 869 "list name" | 870 "forward name" | 871 "modify name" | 872 "bind" | 873 "bindserver" | 874 "unbind" 876 ; This describes the data returned by a server request. 877 ; It is always in table format. 878 data: 879 headerrow 880 *[datarows] 882 headerrow: 883 *[attributename fieldsep] attributename recordsep 884 datarow: 885 *[attributevalue fieldsep] attributevalue recordsep 887 recordsep: 888 "\r\n" 889 fieldsep: 890 "&" 892 ; Although the cr-lf pair is the definition, servers should be able to accept 893 ; a single '\n' or a single '\r' as a delimeter 894 newline: 895 "\r\n" 897 ; This is a list of attributes recognized by the SWTP server. 898 eventattributename: 899 "date" | 900 "due date" | 901 "start date" | 902 "repeat" | 903 "duration" | 904 "time" | 905 "subject" | 906 "task" | 907 "type" | 908 "users" | 909 "attendees" | 910 "delegate to" | 911 "send to" | 912 "resources" | 913 "location" | 914 "who_did_it" | 915 "scheduled by" | 916 "sent by" | 917 "delegated by" | 918 "originator" | 919 "event_id" | 920 "priority" | 921 "project" | 922 "status" | 923 "done_date" | 924 "event_status" | 925 "r_msg" | 926 "r_cmd" | 927 "old_who" | 928 "last_modified" | 929 "scheduler" | 930 "task_duration" | 931 "task_start_date" | 932 "desc_fp" | 933 "description" | 934 "timezone" | 935 "calendar" 937 nameattributename: 938 "pid" | 939 "userId" | 940 "name" | 941 "handle" | 942 "description" | 943 "commonName" | 944 "owner" | 945 "administrator" | 946 "mailaddress" | 947 "rfc822mailbox" | 948 "password" | 949 "userPassword" | 950 "server" | 951 "fqdnServer" | 952 "members" | 953 "type" | 954 "attr" | 955 "where" | 956 "perm" | 957 "dbname" 959 otherattributename: 960 "formatted" | 961 "attributes" | 962 "operation" | 963 "sizeLimit" | 964 "timeLimit" | 965 "searchdays" | 966 "searchmax" | 967 "workdays" | 968 "workhours" | 969 "interval" 971 attributename: 972 eventattributename | 973 nameattributename | 974 otherattributename 976 ; The repeat syntax is specified here, because it's too complicated to 977 ; put into words. It relys on the date having been specified. 978 ; In the examples , the date is May 15, 1996 979 repeat: 980 "yearly" | ; yearly on this May 15 981 "yearly every" nth 1*weekday | ; yearly every 3rd Sun in May 982 "monthly" | ; monthly on the 15th of the month 983 "monthly every" nth 1*weekday | ; monthly, every 3rd Sun 984 "On the" nth "month," | ; Every 3rd month, on the 15th 985 "every" 1*weekday | ; weekly on Sun, Mon 986 "every" nth 1*weekday | ; every 3rd Sun 988 weekday: 989 "Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" 991 nth: 992 "1st" | "2nd" | "3rd" | "4th" | "5th" | "6th" 994 This completes the BNF definition of the protocol with the exception 995 of the definition of attributevalue, and a specification of which 996 attributes are appropriate for a given operation. These can be speci- 997 fied in a BNF format, however a more useful reference are the follow- 998 ing tables, which allows a discussion of some of the attributes. Some 999 attributes are very complex in themselves, for example "repeat". 1001 14. Appendix C. Attribute Definitions 1003 This defines the attributes understood by the SWTP server. In some 1004 cases, the same attribute may go by multple names. These are listed 1005 as a group to the left of the description. The attributevalues are 1006 always individually URI-encoded. 1008 14.1 Event Attributes 1010 Attribute Description 1011 ----------------------------------------------------------------------- 1012 date The date of the event, the due date of the task, or 1013 due date the starting date of a repeating event or task. 1014 start date Dates should be input in the form day-month-year as 1015 in 13-Oct-1996, or 13-10-1996. The former is pre- 1016 ferred as it leads to less confusion with some other 1017 styles of date presentation. The year should be 1018 specified with its full four digits. If only two 1019 digits are present, it will automatically be con- 1020 verted to a year less than 50 years away from the 1021 present date, either in the future or the past 1022 depending upon which is closer. To specify a date in 1023 the year 96 A.D., use 13-Oct-0096. 1025 repeat See below for a BNF description of the repeat syntax. 1026 duration Durations are normally specified in the form 1027 hours:minutes, for example, 2:35 is 2 hours 35 min- 1028 utes. For long events, lasting days, use the form 1029 days:hours:minutes. For example 31:2:35 is 31 days, 1030 2 hours, 35 minutes. 1032 time Time is specified on a 24 hour clock, as in 18:32, 1033 which is 6:32PM. An optional timezone may be speci- 1034 fied, as in 18:32 PDT, or 18:32 EST. If the timezone 1035 is not known, then an offset to UTC may be specified 1036 as 18:32 +0630 or 18:32 -0630. This gives a 6 and 1037 one half hour offset from UTC east or west of the UTC 1038 zone respectively. Setting the timezone here, is 1039 identical to setting the timezone field listed below. 1041 subject A short description of the event or task, suitable 1042 task for identification. Maximum of 128 characters. 1044 type This has allowed values "event", or "task", with the 1045 default being "event". 1047 users A comma separated list of schedules, or users on 1048 attendees whose calendars this task or event will appear. The 1049 delegate to format for specifying a name uses the RFC822 mail 1050 send to address syntax. Names local to the current server 1051 may be specified without using the host server name. 1052 Groups may be specified, but the group name must be 1053 known within the context of the current server, and 1054 will be resolved to an appropriate list of names. In 1055 a later specification, it is expected that a brack- 1056 eted set of attributes [ ] will describe confirmation 1057 status, and resource pooling by appending to the 1058 name. 1060 resources For the purposes of this protocol, a resource is 1061 identical to an attendee. The distinction is made 1062 because client software may wish to handle conflicts 1063 differently for resources, than for users. 1065 location The location of the event. This is often not used, 1066 as the location is put in the description. Maximum of 1067 128 characters. 1069 originator The name of the user, or calendar which originated 1070 who_did_it this event. 1071 scheduled by 1073 event_id The event_id must be unique across all SWTP systems 1074 and all events. Although the actual format is arbi- 1075 trary, the format used on the first SWTP systems 1076 embeds a product identifier, a serial number, and a 1077 sequential number into a 32 character field. Another 1078 alternative is to embed the servers fully qualified 1079 domain name with a sequential number. The event_id 1080 is created and assigned by the server. 1082 priority The priority has values of "hi", "med", and "lo", and 1083 is primarily used for ranking tasks. 1085 project A field used to categorize tasks or events. Maximum 1086 category of 32 characters. 1088 status The status of a task. Has values of "done", and 1089 "undone". done_date T{ The date the task was com- 1090 pleted. This is a date, and not a time. 1092 event_status A flag indicating that this is a new event, or has 1093 changed recently. This is useful to client software 1094 in announcing changed events to users. Has values of 1095 "not read", or "attention", or "clear". 1097 r_msg Reserved. Later this may be used as a reminder mes- 1098 sage to be sent to the calendar owner. 1100 r_cmd Reserved. Later this may be used as a reminder com- 1101 mand to be executed at the reminder offset. 1103 old_who If a task is re-delegated, this points to the 1104 assignee. 1106 r_offset Reserved. Later this may be used as an offset indi- 1107 cating the amount of time prior to the event a 1108 reminder needs to be sent. Measured in minutes. 1110 last_modified The date and time (UTC) of when the event was last 1111 modified. Read only. 1113 scheduler Indicates whether the originator should be included 1114 in the list of attendees or not. Has values 1115 "include" or "exclude". 1117 task_duration Reserved. Later this may be used to represent the 1118 number of man-hours required for a given task. 1120 task_start_date Reserved. Later this may be used to represent the 1121 actual starting date of a task. 1123 desc_fp This is an identifier which is assigned by the 1124 server, and is used as a pointer to the description. 1125 In the case of the same description being assigned to 1126 multiple events, storage space can be saved by 1127 retrieving this value, and using it instead of the 1128 description on subsequent events. 1130 description This field is of arbitrary length, and gives a 1131 detailed description of the event. 1133 timezone Specifies the timezone for which to interpret dates 1134 for this event. 1136 calendar Specifies the calendar this event appears in. This 1137 is single valued. 1139 extensions A free field, with a minimum of 256 characters which 1140 can be used to relate an event with some other exter- 1141 nal application. The proper form for information in 1142 this field is for example "APP_special_id=234xabc". 1143 This indicates that application APP is related to 1144 this field with special_id "234xabc". Multiple name 1145 value pairs should be separated by "&". 1147 confirmcookie This is a read-only field, and is a string of charac- 1148 ters which uniquely identify this event, the calen- 1149 dar, and the list of attendees. This is used by the 1150 confirm operation to allow users who may not other- 1151 wise have access to a calendar to perform a confirm 1152 operation on the indicated event. 1154 14.2 Name Attributes 1156 Attribute Description 1157 ----------------------------------------------------------------------- 1158 pid An internal id maintained by the local server. 1159 userId This id should be used when modifying names on the 1160 local server. 1161 name The name of the calendar resource, calendar user, 1162 handle group, alias, or server. For example, "bill". If 1163 this is a remote user, or remote resource, this 1164 should be qualified with the appropriate domain 1165 name. If this is a server name, it should be a 1166 fully qualified hostname. 1168 description A more descriptive name, like "William P. 1169 commonName Spencer". Because this attribute name matches one 1170 used in LDAP, users are encouraged to use the full 1171 name of the user. For a resource, a commonName 1172 like "Conference Room 316" is appropriate, with a 1173 handle of "conf316". 1175 owner Resources require administrators, as well as some 1176 administrator user calendars, and servers. This is the handle 1177 of the user who administers this entity. For most 1178 users, this is identical to the users handle. 1180 mailaddress The electronic mail address of the user who should 1181 rfc822mailbox receive mail about this calendar. Generally this 1182 should be the owner's mail address. 1184 password A password used to identify access to this calen- 1185 userPassword dar through the "bind" operation. In the initial 1186 release of this specification, this provides only 1187 minimal security through the use of a clear text 1188 passwarod. 1190 server The server on which the calendar for this user or 1191 fqdnServer resource resides. If the handle is a fully quali- 1192 fied domain name, then this server should coincide 1193 with that information. A value of "LocalServer" 1194 means that the information resides on the local- 1195 host. 1197 members A comma separated list of users, resources, or 1198 other groups which make up this group. If this 1199 name is an alias, then only one name should appear 1200 here. 1202 type The type of entry. Valid values are "invalid", 1203 "user", "resource", "group", "alias", and 1204 "server". 1206 perm This is a read-only value, and specifies the type 1207 of permission this user and calendar has to this 1208 calendar resource. Valid values are "None", 1209 "Check", "ViewOnly", "ViewInvite", "InviteOnly", 1210 and "Full" . 1212 14.3 Other Attributes 1214 Attribute Description 1215 ----------------------------------------------------------------------- 1216 formatted Reserved. Later this attribute will specify a 1217 format for presenting a event. As part of a 1218 response from the server, this is will be the for- 1219 matted event itself. 1221 attributes This specifies the list of attributes to be 1222 returned as a response. 1224 operation This specifies the operation the server should 1225 perform. 1227 sizeLimit This specifies the maximum number of event records 1228 to be returned by a "list" operation. "0" indi- 1229 cates no limit. 1231 timeLimit This specifies the maximum number of seconds the 1232 server should work on a response to a "list" oper- 1233 ation. "0" indicates forever. 1235 currentdate This is the date and time as perceived by the 1236 client during the bind process. The format for 1237 this date is "weekday day-mon-year hh:mm:ss time- 1238 zone", for example "Tuesday 13-OCT-1996 14:03:1996 1239 EST" 1241 calendar A comma separated list of calendars used as part 1242 of the setcalendar operation. 1244 workdays In a free time search use only these days as part 1245 of the search. For example, 1246 "Mon,Tue,Wed,Thu,Fri". 1248 workhours In a free time search use only these hours as part 1249 to the search. The format is timestart-timestop, 1250 for example, "8:00-18:30". A timezone specifica- 1251 tion is not allowed here. 1253 interval The time interval granualarity in minutes for a 1254 "projection". The default is 15 minutes. 1256 projection A projection is a string of characters, 1 charac- 1257 ter per time "interval", which indicates free time 1258 within a period defined by "workhours". A '0' 1259 indicates that the time is available, and any 1260 other single digit indicates the number of con- 1261 flicts at that particular time. If that number 1262 exceeds 9, then a 1264 15. Appendix D. Access to a Demonstration Server 1266 A prototype version of this server is accessible at 1267 www.p2software.com, on port 5551. Both a perl-based API, and a C- 1268 based API, in source code format are available. Software for utilizing 1269 Netscape or other browser as a client is also avaliable in source 1270 form. Please send e-mail to bspencer@p2software.com, and we will 1271 respond with the requirements for accessing it. Please include the 1272 keyword "SWTP" in the subject line of your e-mail. 1274 The ClockWise(R) scheduling data repository is used as the basis for 1275 this server. 1277 16. Appendix E. Bibliography 1279 [1] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory 1280 Access Protocol," RFC 1777, Performance Systems Interna- 1281 tional, University of Michigan, ISODE Consortium, March 1282 1995. 1284 [2] Berners-Lee, T., Masinter, L., and M. McCahill, Editors, 1285 "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox 1286 Corporation, University of Minnesota, December 1994. 1287 1289 [3] Crocker, D., "Standard for the Format of ARPA Internet Text 1290 Messages", STD 11, RFC 822, UDEL, August 1982. 1291 1293 [4] Horton, M. and R. Adams, "Standard For Interchange of USENET 1294 Messages", RFC 1036, AT&T Bell Laboratories, Center for 1295 Seismic Studies, December 1987. 1296 1298 17. Appendix F. Authors' Address 1300 Bill Spencer, Ph.D. 1301 Phase II Software Corporation 1302 910 Boston Post Road, #260 1303 Marlboro, MA 01752 1304 bspencer@p2software.com 1305 Mark M. Smith 1306 Phase II Software Corporation 1307 910 Boston Post Road, #260 1308 Marlboro, MA 01752 1309 msmith@p2software.com