| 1 |
.. _imap-developer-thoughts-caldavflow: |
| 2 |
|
| 3 |
.. Note: This document was converted from the original by Nic Bernstein |
| 4 |
(Onlight). Any formatting mistakes are my fault and not the |
| 5 |
original author's. Converted via the pandoc tool from HTML. |
| 6 |
|
| 7 |
Cyrus CalDAV Scheduling Flowchart |
| 8 |
================================= |
| 9 |
|
| 10 |
caldav\_put() - create/modify via HTTP PUT on a resource or POST (add-member) on a calendar |
| 11 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 12 |
|
| 13 |
#. Check if the new resource is a scheduling resource (contains |
| 14 |
ORGANIZER property). If not, skip to step 4. |
| 15 |
#. Check for (and load) any existing resource. |
| 16 |
#. Check if the authenticated user matches ORGANIZER: |
| 17 |
|
| 18 |
- If yes: |
| 19 |
|
| 20 |
- If only voter (VPOLL) responses changed, goto |
| 21 |
`sched\_pollstatus() <#sched_pollstatus>`__. |
| 22 |
- Otherwise, goto `sched\_request() <#sched_request>`__. |
| 23 |
|
| 24 |
- Otherwise, goto `sched\_reply() <#sched_reply>`__. |
| 25 |
|
| 26 |
#. Store the new/modified resource. |
| 27 |
|
| 28 |
caldav\_delete\_sched() - remove via HTTP DELETE on a resource |
| 29 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 30 |
|
| 31 |
#. Check if the existing resource is a scheduling resource (has |
| 32 |
Schedule-Tag). If not, we are done. |
| 33 |
#. Load the existing resource. |
| 34 |
#. Check if the authenticated user matches ORGANIZER. If yes, goto |
| 35 |
`sched\_request() <#sched_request>`__, otherwise goto |
| 36 |
`sched\_reply() <#sched_reply>`__. |
| 37 |
|
| 38 |
caldav\_post() - busytime query via HTTP POST on Scheduling Outbox |
| 39 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 40 |
|
| 41 |
#. Check the ACL on the owner's Scheduling Outbox. If the authenticated |
| 42 |
user doesn't have the DACL\_SCHEDFB right, fail. |
| 43 |
#. `sched\_busytime\_query() <#sched_busytime_query>`__. |
| 44 |
|
| 45 |
-------------- |
| 46 |
|
| 47 |
sched\_pollstatus - perform a voter response update |
| 48 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 49 |
|
| 50 |
#. |
| 51 |
|
| 52 |
-------------- |
| 53 |
|
| 54 |
sched\_request() - perform an organizer request / attendee status update |
| 55 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 56 |
|
| 57 |
Check the ACL on the owner's Scheduling Outbox. If the authenticated |
| 58 |
user doesn't have the DACL\_INVITE right, fail. |
| 59 |
|
| 60 |
If the request includes a resource, then set METHOD:REQUEST, otherwise |
| 61 |
set METHOD:CANCEL. |
| 62 |
|
| 63 |
Create an iTIP message template, copying over any CALSCALE property and |
| 64 |
VTIMEZONE components. |
| 65 |
|
| 66 |
If not an attendee status update and the existing resource is a |
| 67 |
scheduling resource: Foreach component in the existing resource, add it |
| 68 |
and its SEQUENCE to our hash table keyed by RECURRENCE-ID (for |
| 69 |
comparison against new/modified resource). |
| 70 |
|
| 71 |
Create a hash table of attendees. This will hold attendee-specific iTIP |
| 72 |
messages. |
| 73 |
|
| 74 |
Foreach component in the new/modified resource: |
| 75 |
|
| 76 |
a. Lookup (by RECURRENCE-ID) and remove the component from the hash |
| 77 |
table of existing components. |
| 78 |
b. If the component exists compare all of DTSTART, DTEND, DURATION, |
| 79 |
RRULE, RDATE, EXDATE to those of the new component. |
| 80 |
c. If the component is new or changed, then |
| 81 |
`process\_attendees() <#process_attendees>`__. |
| 82 |
|
| 83 |
Foreach remaining component in the hash table of existing components do |
| 84 |
`sched\_cancel() <#sched_cancel>`__. |
| 85 |
|
| 86 |
Foreach iTIP message in our hash table of ATTENDEES, |
| 87 |
`sched\_deliver() <#sched_deliver>`__ the iTIP message. |
| 88 |
|
| 89 |
Foreach component in the new/modified resource update the |
| 90 |
SCHEDULE-STATUS of each ATTENDEE. |
| 91 |
|
| 92 |
process\_attendees() - create a suitable iTIP request message for each attendee |
| 93 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 94 |
|
| 95 |
Foreach ATTENDEE in the component, remove the SCHEDULE-STATUS parameter, |
| 96 |
and set PROPSTAT=NEEDS-ACTION if required. |
| 97 |
|
| 98 |
Make a copy of the component and |
| 99 |
`clean\_component() <#clean_component>`__. |
| 100 |
|
| 101 |
Foreach ATTENDEE in the cleaned component: |
| 102 |
|
| 103 |
a. Check the CalDAV Scheduling parameters. If SCHEDULE-AGENT != SERVER, |
| 104 |
skip to the next attendee. |
| 105 |
b. Lookup attendee in our hash table. |
| 106 |
c. If it doesn't exist, create a clone of our iTIP template and insert |
| 107 |
it into our hash table of attendees. |
| 108 |
d. Add the component to the attendee's iTIP message. |
| 109 |
e. Add the component “number” to our mask of new components appearing in |
| 110 |
the attendee's iTIP message. |
| 111 |
|
| 112 |
If the component is not the "master", foreach attendee do |
| 113 |
`sched\_exclude() <#sched_exclude>`__. |
| 114 |
|
| 115 |
sched\_exclude() - exclude an attendee from a recurrence instance |
| 116 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 117 |
|
| 118 |
#. If the component did not appear in the attendee's iTIP message, add |
| 119 |
an EXDATE property (based on the RECURRENCE-ID of the component) to |
| 120 |
the master component of the attendee's iTIP message. |
| 121 |
|
| 122 |
sched\_cancel() - cancel an organizer event/task |
| 123 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 124 |
|
| 125 |
#. Set STATUS:CANCELLED on the component. |
| 126 |
#. `process\_attendees() <#process_attendees>`__. |
| 127 |
|
| 128 |
-------------- |
| 129 |
|
| 130 |
sched\_reply() - perform an attendee reply |
| 131 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 132 |
|
| 133 |
Check the CalDAV Scheduling parameters on ORGANIZER. If SCHEDULE-AGENT |
| 134 |
!= SERVER, we are done. |
| 135 |
|
| 136 |
Check the ACL on the owner's Scheduling Outbox. If the authenticated |
| 137 |
user doesn't have the DACL\_REPLY right, fail. |
| 138 |
|
| 139 |
Create a new iTIP (METHOD:REPLY) message, copying over any CALSCALE |
| 140 |
property and VTIMEZONE components. |
| 141 |
|
| 142 |
Foreach component in the existing resource: |
| 143 |
|
| 144 |
a. `trim\_attendees() <#trim_attendees>`__. |
| 145 |
b. Add the trimmed component and the attendee's PARTSTAT to our hash |
| 146 |
table keyed by RECURRENCE-ID (for comparison against new/modified |
| 147 |
resource). |
| 148 |
|
| 149 |
Foreach component in the new/modified resource: |
| 150 |
|
| 151 |
`trim\_attendees() <#trim_attendees>`__. |
| 152 |
|
| 153 |
Lookup (by RECURRENCE-ID) and remove the component from the hash table |
| 154 |
of existing components. |
| 155 |
|
| 156 |
If the component exists: |
| 157 |
|
| 158 |
i. If component is VPOLL, add voter responses to REPLY via |
| 159 |
`sched\_vpoll\_reply(). <#sched_vpoll_reply>`__ |
| 160 |
ii. Otherwise, compare the PARTSTAT of the ATTENDEE to that of the new |
| 161 |
component. |
| 162 |
|
| 163 |
If the component is new or the PARTSTAT has changed: |
| 164 |
|
| 165 |
i. `clean\_component() <#clean_component>`__. |
| 166 |
ii. Add the component to our iTIP message. |
| 167 |
iii. Add the component “number” to our mask of new components appearing |
| 168 |
in our iTIP message. |
| 169 |
|
| 170 |
Foreach remaining component in the hash table of existing components do |
| 171 |
`sched\_decline() <#sched_decline>`__. |
| 172 |
|
| 173 |
`sched\_deliver() <#sched_deliver>`__ our iTIP message. |
| 174 |
|
| 175 |
Foreach component in the new/modified resource that appeared in our iTIP |
| 176 |
message, update the SCHEDULE-STATUS of the ORGANIZER. |
| 177 |
|
| 178 |
trim\_attendees() - remove all attendees other than the one replying |
| 179 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 180 |
|
| 181 |
#. Clone the component and remove all ATTENDEE properties other than the |
| 182 |
one corresponding to the owner of the calendar. |
| 183 |
#. Return the ATTENDEE property of owner, his/her PARTSTAT parameter, |
| 184 |
and the RECURRENCE-ID of the component. |
| 185 |
|
| 186 |
sched\_vpoll\_reply() - add voter responses to VPOLL reply |
| 187 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 188 |
|
| 189 |
#. |
| 190 |
|
| 191 |
sched\_decline() - decline a recurrence instance for an attendee |
| 192 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 193 |
|
| 194 |
#. Set PARTSTAT of ATTENDEE to DECLINED. |
| 195 |
#. `clean\_component() <#clean_component>`__. |
| 196 |
#. Add the component to our iTIP message. |
| 197 |
|
| 198 |
-------------- |
| 199 |
|
| 200 |
clean\_component() - sanitize a component for use in an iTIP message |
| 201 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 202 |
|
| 203 |
#. Update DTSTAMP. |
| 204 |
#. Remove any VALARM components. |
| 205 |
#. For a reply/decline only, remove scheduling parameters from |
| 206 |
ORGANIZER. |
| 207 |
|
| 208 |
sched\_deliver() - deliver an iTIP message to a recipient |
| 209 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 210 |
|
| 211 |
#. Lookup the recipient. |
| 212 |
#. If local to our server goto |
| 213 |
`sched\_deliver\_local() <#sched_deliver_local>`__, otherwise goto |
| 214 |
`sched\_deliver\_remote() <#sched_deliver_remote>`__. |
| 215 |
|
| 216 |
-------------- |
| 217 |
|
| 218 |
sched\_deliver\_local() - deliver an iTIP message to a local user |
| 219 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 220 |
|
| 221 |
Check the ACL on the owner's Scheduling Inbox. If the sender doesn't |
| 222 |
have the proper right (DACL\_INVITE for request/cancel, DACL\_REPLY for |
| 223 |
reply), fail. |
| 224 |
|
| 225 |
Search the recipient's calendars for a resource having the specified |
| 226 |
UID. |
| 227 |
|
| 228 |
If the resource doesn't exist: |
| 229 |
|
| 230 |
a. If the iTIP method is REPLY, fail (we are done). |
| 231 |
b. If the iTIP method is CANCEL, ignore it (we are done). |
| 232 |
c. Otherwise, create a new (empty) attendee object and target the |
| 233 |
recipient's Default calendar. |
| 234 |
|
| 235 |
Otherwise, load the existing resource. |
| 236 |
|
| 237 |
Update the new/existing resource: |
| 238 |
|
| 239 |
a. If the iTIP method is CANCEL, set STATUS:CANCELLED on all existing |
| 240 |
components. |
| 241 |
b. If the iTIP method is REPLY, do |
| 242 |
`deliver\_merge\_reply() <#deliver_merge_reply>`__. |
| 243 |
c. If the iTIP method is REQUEST, do |
| 244 |
`deliver\_merge\_request() <#deliver_merge_request>`__. |
| 245 |
d. If the iTIP method is POLLSTATUS, do |
| 246 |
`deliver\_merge\_pollstatus() <#deliver_merge_pollstatus>`__. |
| 247 |
|
| 248 |
Store the new/updated resource in the recipient's target calendar. |
| 249 |
|
| 250 |
Record the delivery status (SCHEDULE-STATUS). |
| 251 |
|
| 252 |
If the iTIP message is something other than just a PARTSTAT update from |
| 253 |
an attendee, store the iTIP message as a new resource in the recipient's |
| 254 |
Inbox. |
| 255 |
|
| 256 |
If the iTIP method is REPLY, send an update other attendees via |
| 257 |
`sched\_pollstatus() <#sched_pollstatus>`__ (VPOLL only) or |
| 258 |
`sched\_request() <#sched_request>`__. |
| 259 |
|
| 260 |
deliver\_merge\_reply() - update an organizer resource with an attendee reply |
| 261 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 262 |
|
| 263 |
Foreach component in the existing resource, add it to our hash table |
| 264 |
keyed by RECURRENCE-ID (for comparison against iTIP message). |
| 265 |
|
| 266 |
Foreach component in the iTIP message: |
| 267 |
|
| 268 |
Lookup (by RECURRENCE-ID) the component from the hash table of existing |
| 269 |
components. |
| 270 |
|
| 271 |
If the component doesn't exist (new recurrence overridden by ATTENDEE) |
| 272 |
create a new recurring component: |
| 273 |
|
| 274 |
i. Clone the existing master component. |
| 275 |
ii. Remove the RRULE property. |
| 276 |
iii. Add the RECURRENCE-ID from the iTIP message. |
| 277 |
iv. Replace the DTSTART, DTEND, SEQUENCE properties with those from the |
| 278 |
iTIP message. |
| 279 |
v. Add the new component to our existing resource. |
| 280 |
|
| 281 |
Get the sending ATTENDEE from the iTIP message. |
| 282 |
|
| 283 |
Find the matching ATTENDEE in the existing component. |
| 284 |
|
| 285 |
If not found (ATTENDEE added themselves to this recurrence), add new |
| 286 |
ATTENDEE to the component. |
| 287 |
|
| 288 |
Set the ATTENDEE PARTSTAT, RSVP, and SCHEDULE-STATUS parameters in the |
| 289 |
existing component. |
| 290 |
|
| 291 |
If the component is VPOLL, update the voter responses in the existing |
| 292 |
component via |
| 293 |
`deliver\_merge\_vpoll\_reply() <#deliver_merge_vpoll_reply>`__. |
| 294 |
|
| 295 |
Return the sending ATTENDEE. |
| 296 |
|
| 297 |
deliver\_merge\_vpoll\_reply() - update an organizer resource with voter responses |
| 298 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 299 |
|
| 300 |
#. Foreach sub-component in the existing resource, replace any voter |
| 301 |
response(s) with those from the reply. |
| 302 |
|
| 303 |
deliver\_merge\_request() - create/update an attendee resource with an organizer request |
| 304 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 305 |
|
| 306 |
Foreach VTIMEZONE component in the existing resource, add it to our hash |
| 307 |
table keyed by TZID (for comparison against iTIP message). |
| 308 |
|
| 309 |
Foreach VTIMEZONE component in the iTIP message: |
| 310 |
|
| 311 |
a. Lookup (by TZID) the VTIMEZONE component from the hash table of |
| 312 |
existing components. |
| 313 |
b. If the component exists, remove it from the existing object. |
| 314 |
c. Add the VTIMEZONE from the iTIP message to our existing object. |
| 315 |
|
| 316 |
Foreach component in the existing resource, add it to our hash table |
| 317 |
keyed by RECURRENCE-ID (for comparison against iTIP message). |
| 318 |
|
| 319 |
Foreach component in the iTIP message: |
| 320 |
|
| 321 |
Clone a new component from the iTIP component. |
| 322 |
|
| 323 |
Lookup (by RECURRENCE-ID) the component from the hash table of existing |
| 324 |
components. |
| 325 |
|
| 326 |
If the component exists: |
| 327 |
|
| 328 |
i. Compare the SEQUENCE of the new component to the existing component |
| 329 |
to see if it has changed. |
| 330 |
ii. Copy any COMPLETED, PERCENT-COMPLETE, or TRANSP properties from the |
| 331 |
existing component to the new component. |
| 332 |
iii. Copy any ORGANIZER SCHEDULE-STATUS parameter from the existing |
| 333 |
component to the new component. |
| 334 |
iv. Remove the existing component from the existing object. |
| 335 |
|
| 336 |
Add the new component to the existing object. |
| 337 |
|
| 338 |
deliver\_merge\_pollstatus() - update voter responses on a voter resource |
| 339 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 340 |
|
| 341 |
Foreach sub-component in the existing resource, add it to our hash table |
| 342 |
keyed by POLL-ITEM-ID (for comparison against iTIP message). The |
| 343 |
sub-component entry includes a hash table of VOTERs. |
| 344 |
|
| 345 |
Foreach sub-component in the iTIP message: |
| 346 |
|
| 347 |
a. Lookup (by POLL-ITEM-ID) the sub-component from the hash table of |
| 348 |
existing sub-components. |
| 349 |
b. If the component exists, foreach VOTER in the sub-component in the |
| 350 |
iTIP message: |
| 351 |
|
| 352 |
i. Lookup VOTER in the hash table of existing sub-component. |
| 353 |
ii. Add/update VOTER response. |
| 354 |
|
| 355 |
-------------- |
| 356 |
|
| 357 |
sched\_deliver\_remote() - deliver an iTIP message to a remote user |
| 358 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 359 |
|
| 360 |
#. If the recipient is local to our Murder, goto |
| 361 |
`isched\_send() <#isched_send>`__, otherwise goto |
| 362 |
`imip\_send() <#imip_send>`__. |
| 363 |
#. Retrieve status of iTIP message delivery. |
| 364 |
|
| 365 |
isched\_send() - deliver an iTIP message to a remote user via iSchedule (HTTP) |
| 366 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 367 |
|
| 368 |
imip\_send() - deliver an iTIP message to a remote user via iMIP (SMTP) |
| 369 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 370 |
|
| 371 |
sched\_busytime\_query() - perform a busytime query |
| 372 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 373 |
|
| 374 |
busytime\_query\_local() - perform a busytime query on a local user |
| 375 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 376 |
|
| 377 |
busytime\_query\_remote() - perform a busytime query on a remote user |
| 378 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |