diff --git a/src/applications/calendar/application/PhabricatorCalendarApplication.php b/src/applications/calendar/application/PhabricatorCalendarApplication.php index 1e1a125cde..8caf8c27ec 100644 --- a/src/applications/calendar/application/PhabricatorCalendarApplication.php +++ b/src/applications/calendar/application/PhabricatorCalendarApplication.php @@ -104,6 +104,16 @@ final class PhabricatorCalendarApplication extends PhabricatorApplication { 'name' => pht('Calendar User Guide'), 'href' => PhabricatorEnv::getDoclink('Calendar User Guide'), ), + array( + 'name' => pht('Importing Events'), + 'href' => PhabricatorEnv::getDoclink( + 'Calendar User Guide: Importing Events'), + ), + array( + 'name' => pht('Exporting Events'), + 'href' => PhabricatorEnv::getDoclink( + 'Calendar User Guide: Exporting Events'), + ), ); } diff --git a/src/docs/user/userguide/calendar.diviner b/src/docs/user/userguide/calendar.diviner index e6f9bd4b2c..3aefa84e17 100644 --- a/src/docs/user/userguide/calendar.diviner +++ b/src/docs/user/userguide/calendar.diviner @@ -9,75 +9,11 @@ Overview IMPORTANT: Calendar is a prototype application. See @{article:User Guide: Prototype Applications}. -The Calendar application is a tool that allows users to schedule group events -and share personal plans. -There are several kinds of events you can create: +Next Steps +========== -- Regular events such as a one-time meeting or a personal appointment. -- All day events such as a company-wide holiday or a vacation. -- Recurring events, which can be regular or all day, such as a weekly 1-1 or - a birthday. +Continue by: - -Editing Events -============== - -All fields of basic and all day events can be edited after the event has been -created. - -Every instance of a recurring event has an index that maintains its place in -the sequence order. Before an instance of a recurring event is edited, it is -considered a ghost event, or a placeholder. This means that there is no -database entry for that instance. Rather, when querying for events, if a -recurring series of events overlaps with the query range, instance -placeholders of that recurring event are generated and are displayed for -that range. If a placeholder instance of a recurring event is edited, a real -entry in the database is created and all changes are saved. When that -instance falls within a query range, the real instance event replaces the -old placeholder instance. - -To prevent disordering of the recurring sequence of events, parent recurring -events do not allow editing of date-related fields like recurrence frequency -and recurrence start and end dates. If all instances of the recurring event -need to be rescheduled, users are encouraged to cancel a recurring event and -create a new recurring event with the revised date and time. - - -Cancelling Events -================= - -Cancelling basic events will hide that event from most of the builtin Calendar -queries, unless the query specifies to display cancelled events. - -There are two ways to cancel an instance of a recurring event. - -- Cancel an instance of a recurring event. -- Cancel the entire series of a recurring event. - -Cancelling a placeholder instance of a recurring event will create a real -cancelled event that will replace the placeholder instance. Consequently, -the cancellation status of that instance of the recurring event will -persist if the parent event is cancelled and subsequently reinstated. - -When an entire series of a recurring event is cancelled, all the placeholder -and real instances are also cancelled. An entire series can similarly be -reinstated, but it is currently not possible to reinstate an instance of a -cancelled recurring event series. To reinstate that instance, the entire -series must be reinstated. If an instance of a recurring event has been -cancelled, then the entire recurring event series is also cancelled, -reinstating the series will not reinstate the previously cancelled instances -of that event. - - -Commenting On Recurring Events -============================== - -If a placeholder instance of a recurring event has not been converted to a -real instance of the series as a result of editing or cancelling, commenting on -that placeholder instance does not currently save a draft for that instance -only. The draft is saved for the recurring event parent, so the parent -recurring event and all placeholder instances will show that draft. When a -comment is actually added to a placeholder instance, the instance is converted -to a recurrence exception, and the comment will only appear on that instance -of the recurring event. + - importing events with @{article:Calendar User Guide: Importing Events}; or + - exporting events with @{article:Calendar User Guide: Exporting Events}. diff --git a/src/docs/user/userguide/calendar_imports.diviner b/src/docs/user/userguide/calendar_imports.diviner new file mode 100644 index 0000000000..a4163e9bcd --- /dev/null +++ b/src/docs/user/userguide/calendar_imports.diviner @@ -0,0 +1,132 @@ +@title Calendar User Guide: Importing Events +@group userguide + +Importing events from other calendars. + +Overview +======== + +IMPORTANT: Calendar is a prototype application. See +@{article:User Guide: Prototype Applications}. + +You can import events into Phabricator to other calendar applications or from +`.ics` files. This document will guide you through how to importe event data +into Phabricator. + +When you import events from another application, they can not be edited in +Phabricator. Importing events allows you to share events or keep track of +events from different sources, but does not let you edit events from other +applications in Phabricator. + + +Import Policies +=============== + +When you import events, you select a visibility policy for the import. By +default, imported events are only visible to you (the user importing them). + +To share imported events with other users, make the import **Visible To** +a wider set of users, like "All Users". + + +Importing `.ics` Files +====================== + +`.ics` files contain information about events, usually either about a single +event or an entire event calendar. + +If you have an event or calendar in `.ics` format, you can import it into +Phabricator in two ways: + + - Navigate to {nav Calendar > Imports > Import Events > Import .ics File}. + - Drag and drop the file onto a Calendar. + +This will create a copy of the event in Phabricator. + +If you want to update an imported event later, just repeat this process. The +event will be updated with the latest information. + +Many applications send `.ics` files as email attachments. You can import these +into Phabricator. + + +.ics Files: Google Calendar +=========================== + +In **Google Calendar**, you can generate a `.ics` file for a calendar by +clicking the dropdown menu next to the calendar and selecting +{nav Calendar Settings > Export Calendar > Export this calendar}. + + +.ics Files: Calendar.app +======================== + +In **Calendar.app**, you can generate an `.ics` file for a calendar by +selecting the calendar, then selecting {nav File > Export > Export...} and +saving the calendar as a `.ics` file. + +You can also convert an individual event into an `.ics` file by dragging it +from the calendar to your desktop (or any other folder). + +When you import an event using an `.ics` file, Phabricator can not +automatically keep the event up to date. You'll need to repeat the process if +there are changes to the event or calendar later, so Phabricator can learn +about the updates. + + +Importing .ics URIs +===================== + +If you have a calendar in another application that supports publishing a +`.ics` URI, you can subscribe to it in Phabricator. This will import the entire +calendar, and can be configured to automatically keep it up to date and in sync +with the external calendar. + +First, find the subscription URI for the calendar you want to import (see +below for some guidance on popular calendar applications). Then, browse to +{nav Calendar > Imports > Import Events > Import .ics URI}. + +When you import a URI, you can choose to enable automatic updates. If you do, +Phabricator will periodically update the events it imports from this source. +You can stop this later by turning off the automatic updates or disabling +the import. + +{icon lock} **Privacy Note**: When you import via URI, the URI often contains +sensitive information (like a username, password, or secret key) which allows +anyone who knows it to access private details about events. Anyone who can edit +the import will also be able to view and edit the URI, so make sure you don't +grant edit access to users who should not have access to the event details. + + +.ics URIs: Google Calendar +========================== + +In **Google Calendar**, you can get the subscription URI for a calendar +by selecting {nav Calendar Settings} from the dropdown next to the calendar, +then copying the URL from the {nav ICAL} link under **Private Address**. This +URI provides access to all event details, including private information. + +You may need to adjust the sharing and visibility settings for the calendar +before this option is available. + +Alternatively, you can use the URI from the {nav ICAL} link under +**Calendar Address** to access a more limited set of event details. You can +configure which details are available by configuring how the calendar is +shared. + + +.ics URIs: Calendar.app +======================= + +**Calendar.app** does not support subscriptions via `.ics` URIs. + +You can export a calendar as an `.ics` file by following the steps above, but +Phabricator can not automatically keep events imported in this way up to date. + + +Next Steps +========== + +Continue by: + + - returning to the @{article:Calendar User Guide}.