Chandler Wiki : Chandler Server End User Manual (via Mowser)

Product | Planning | Teams | Developers | Notes
r25 - 23 Jul 2008 - 11:39:02 - RandyLetnessYou are here: OSAF > Projects Web > CosmoHome > ChandlerServerEndUserManual
---+ !!Chandler Server End User Manual
---
%TOC%
---


This manual describes Cosmo 1.0
This document does not address the installation or configuration of the server, all administrative issues are documented at Developers.ServerBundleAdministrator.

These instructions assume that your administrator has %RED%installed Cosmo on =localhost= and is not using SSL, so that the base URL for Cosmo is =http://localhost:8080/chandler/= (this is the default configuration of the Chandler server bundle).%ENDCOLOR% Check with your administrator if you have any questions about the URL for Cosmo.

---++ User Accounts

In order to share content to Cosmo, you must create a *user account* identified uniquely by a username and an email address. Doing so creates an *home collection* where you can store data. You can access this home collection via WebDAV (you can mount it on your desktop in Windows, OS X and Linux or use a command line program like =cadaver=) and CalDAV (calendar clients such as Chandler, Sunbird, and Evolution). You can also browse your home collection with Cosmo's web-based *Account Browser*.

---+++ Sign Up for an Account

   1 Access the Cosmo web console in a web browser at =http://localhost:8080/chandler/=.
   1 Find the paragraph that begins _Don't have an account?_ and click the link that says _SIGN UP!_
   1 You should now see the _Create New Account_ form. Fill out the entire form, as all of the fields are required.
      * Usernames may contain just about any character, including spaces and punctuation marks. The only exceptions are forward slash ('/'), control characters and whitespace characters other than space (' '). Usernames may be at least 3 characters and at most 32 characters long. You cannot choose a username that has already been taken by another account on this server.
      * First name and last name may contain any character. Each may be up to 128 characters long.
      * Email address must be a valid RFC 822 email address that can actually receive mail (it should not bounce mail). It may be up to 128 characters long. You cannot use an email address that is already associated with another account on this server.
      * Password and and confirm password must (obviously) match. The password may contain must be between 5 and 16 characters long and may contain any character.
   1 Click the _Submit_ button.
   1 That's it! The resulting page displays your account details.

---++ Account Management

You can view and manage your account information by clicking the _Settings_ link at the top right-hand side of the page.  This pulls up the =Settings= dialog.  The first tab shows account settings. 

To change your first name, last name or email address simply edit those values in the text boxes where they appear and click _Save_. 

To change the password, enter your new password in the "Password" and "Confirm Password" fields and click the _Save_ button.

If you are updating fields other than your password, you need not enter anything in the password fields.

<img src="%ATTACHURLPATH%/accountsettings.jpg" alt="accountsettings.jpg"/>

---++ Web Interface

There is now a web interface to your collections integrated into Cosmo, and it resembles the interface in Chandler Desktop.  The web interface consists of two views of your collection data: =List View= and =Calendar View=.

---+++ List View Components
List view is the default view, and can be selected by clicking on the <img src="%ATTACHURLPATH%/listviewbutton.jpg" alt="listviewbutton.jpg"/> image.

---++++ Collection list
The left pane shows all collections.  The selected collection is highlighted in gray.  Collections can be administered (added/removed/updated) from this area.

collection list:<br/>
<img src="%ATTACHURLPATH%/collections.jpg" alt="collections.jpg"/>

To add a collection, click on the '+' image.  To remove a collection, select the collection to be removed and click on the '-' image.

after clicking on the down arrow next to a collection you get the collection details:<br/>
<img src="%ATTACHURLPATH%/collectiondetails.jpg" alt="collectiondetails.jpg" width='168' height='391' />

To change the collection name, click on the collection name at the top of the collection details view and the name will change to a text box where the text can be changed.

The "Subscribe with:" buttons will show information(when clicked) on how to use other clients to subscribe to the selected collection.

The "Invite" button will generate bookmarkable urls to the collection that can be sent to others to access the collection.

The "Download" button will open a url that generates an icalendar representation of the currently selected collection.

The "Done" button closes the detail view and returns to the collection list.

---++++ List View
The center pane shows a list of items for the currently selected collection.  This list resembles the dashboard list in Chandler Desktop and organizes items by triage status (NOW/DONE/LATER) and date (if one is present on the item).  This is the only view where non-event items (items that have not been added to the calendar, such as notes) will show up.  Click on an item to select it (the currently selected item will be highlighted in blue).  The list can also be sorted by clicking on the various column headers.
   
list view:<br/>
<img src="%ATTACHURLPATH%/listview.jpg" alt="listview.jpg"/>

---++++ Detail View
The right pane shows a detail view of the currently selected item in the list.  This is where details on the item such as title, description and triage status can be updated, as well as actions such as adding the item to the calendar can be performed.

detail view:<br/>
<img src="%ATTACHURLPATH%/detailview.jpg" alt="detailview.jpg"/>


---++++ Quick Entry
Above the list view is a single text box where new notes can be created.  A new note is created by typing in a title and pressing [Enter].  This new note will appear in the NOW list of items in the list view.  The item can then be updated using the detail view.

---+++ Calendar View Components
In addition to a list view, the webui provides a calendar view which shows items that have been added to the calendar.  This view can be selected by clicking on the <img src="%ATTACHURLPATH%/calendarimage.jpg" alt="calendarimage.jpg"/> image.

---++++ Calendar Canvas

<img src="%ATTACHURLPATH%/calendarview.jpg" alt="calendarview.jpg"/>

The center pane of the screen is occupied by the calendar canvas which has within it one vertical pane for every day of the week. 

The canvas is also divided horizontally into two sections - the timed and un-timed sections. The un-timed section is where events without definite start times appear (like all-day events for example) and the timed section is where events with definite start times appear.  The un-timed section has no scrollbar and is placed at the top of the canvas. The timed section is below the un-timed section and has a scrollbar on the right as well as times indications on the left. 

Calendar events appear as blue rectangles, placed on the canvas on the day and time that they appear, and for timed events taking up as much vertical space as the duration of the event. 

The start time of the event in the context of that event's timezone appears in the event block as well as the title of the event.

Use the <img src="%ATTACHURLPATH%/arrows.jpg" alt="arrows.jpg"/> buttons to navigate forward and back a week.

---++++ Detail View 

The detail view appears to the right of the canvas and provides a more detailed look at the currently selected event, as well as manipulation of events.  This is the same detail view that appears in the list view.

---++++ Mini-cal
The mini-cal, found at the left of the calendar canvas, displays miniature representations of the current and next two months and allows quick navigation to other dates.

---++++ Collection List
The collection list is above the mini-cal.  The collection list allows you to select a collection to work with.  The check boxes next to each collection name allow collections to be overlayed, showing multiple collections on the canvas at the same time.  The currently selected collection (highlighted in gray) is the collection that new events will be added to when the canvas is double-clicked. 

---+++ Manipulating Events

On the calendar canvas you drag events to different times, or change their start or end time by dragging the beginning or end of the event blocks. You can also delete an event by selecting it (by clicking on it) and pressing the delete key on the keyboard. To create an event on the canvas double click on an empty part of the canvas where you want the event to appear.

To edit an event in the detail view you must first select it by clicking on the event in the canvas. After selecting the event you may change any information you like in the event detail fields and click _Save_ to persist these changes. You can also click _Remove_ to permanently remove an event from the collection.

---+++ Navigation

There are several ways to navigate the calendar. You can click the left or right arrows above the un-timed section of the calendar canvas which will take you forward or backward a week. You can also click on any day in the mini-cal to be brought to the week which contains that day. Clicking the right or left arrow buttons at the top of the mini-cal will bring the mini-cal itself a month forward or backward. To jump quickly to a specific date, type the date into the text box above the mini-cal labeled "Go to" and click _Go_.

---+++ Recurring Events

Certain events repeat themselves periodically (Birthdays, meetings, etc.) and so it is convenient to specify this to the system rather manually entering in each occurrence of an event. To specify that an event recurs, change the "Occurs" field to a value other than "Once" and the event will now appear at that frequency. You may optionally enter the date on which you want the event to stop repeating by entering a value for the "ending" field.

If you attempt to modify an instance of a recurring event you will be prompted with a dialog box with a number of the following choices:

   * Cancel - This cancels the change you were about to make and reverts to the previous state of the event.

   * All Events - Choosing this option will make your changes persist to all instances of the event.

   * All Future Events - If you choose this the changes will only affect the current event and all future instances.

   * Only This Event - The change(s) you made apply only to the current event. 

---++ Publishing and Subscribing to Calendars

Cosmo supports two kinds of calendars:

   * Native Calendar collections, which is the internal format, and allows Cosmo to support multiple protocols for read and read/write access including the Desktop sync protocol - Morse Code, CalDAV, the cosmo feed service (atompub based), and webcal (read-only).
   * "webcal", in which an entire calendar is stored on the server in a single resource (file). This is the format popularized by iCal and supported by just about every calendar client, but it is too limited to allow effective read-write subscriptions; usually only the person who published the calendar can update it.
     
Cosmo has the ability to make a native calendar collection masquerade as a webcal resource, so that clients which only support webcal can still subscribe (read-only) to CalDAV calendars. Cosmo does not allow webcal clients to update subscribed native calendars.

---+++ Supported Clients

These clients have been tested with Cosmo 1.0.

   * [[CosmoWithChandler][OSAF Chandler 0.7]]
   * [[CosmoWithiCal][Apple iCal 2.0, 3.0]]
   * [[CosmoWithLightning][Mozilla Lightning 0.8]]
   * [[CosmoWithSunbird][Mozilla Sunbird 0.8]]
   * [[CosmoWithEvolution][Evolution 2.22]]

---++ Controlling Access to Your Calendars

Once you have published a calendar to Cosmo, only you and Cosmo administrators have access to it. In order to allow others to view and potentially edit your calendars, you must explicitly grant them access.

Note that everything in this section applies equally to any resource inside your home collection, including files you might upload using WebDAV.

---+++ Tickets

#ControlAccessTickets
The only type of access control currently implemented by Cosmo is based on *tickets*. These are like airline tickets that prove you are able to board a plane. Unlike airline tickets, though, Cosmo does not force you to provide ID that proves you are a specific person. Anybody in the world can use a ticket to access a Cosmo resource. This means you can create one ticket and give it to many different people to grant them access to your calendar.

Tickets are uniquely identified with random strings like "0fc3bd0a5f2", called *keys*. Each ticket is associated with a set of privileges; Cosmo supports _read-only_, _read-write_ and _free-busy_ tickets. Tickets can also have expiration dates, or "timeouts", although they don't have to. Setting a ticket to expire after a certain amount of time is a good way to provide limited, time-based access to a resource.

Tickets can be inherited from their ancestor collections. Imagine that you published three calendars into your home collection and then created a single read-only ticket on the home collection itself. Once you've given your friend the ticket, he can look at any of those calendars (along with anything else in your home collection). If you instead had created the ticket on one of the calendars, then your friend could only look at that calendar, but the other calendars would remain private.

---++++ Granting a Ticket
Tickets can be granted in a couple of ways. The first way is to use the =Invite= link in the collection details pane.

   1 Log into Cosmo.
   1 In the =Collections= list, click on the down arrow next to the collection you wish to share.
   1 Click on the =Invite= button.
   1 This will generate a view-only and view and edit url, each having an associated ticket.

You can also use the account browser built into Cosmo to grant tickets on your calendars or
on non-calendar resources. The following instructions assume that you have previously published a webcal calendar named =Home.ics= into your home collection.

   1 Log into Cosmo.
   1 Click the _Account Browser_ link.   See the section on [[#ActivatingtheAccountBrowser][Activating the Account Browser]] if you have not previously turned on the Account Browser.
   1 You are now looking at a page that shows lots of things about your home collection, including basic attributes like when it was created as well as lists of its member resources, tickets, and properties.
   1 Find =Home.ics= in the contents list and click its _Browse_ link. (You may notice that Cosmo thinks the calendar is a "File" rather than a "Calendar". This is because it's a webcal calendar, which Cosmo treats for almost all purposes like a regular file, because it's a legacy format).
   1 You now see a similar page to the previous one, but this time for =Home.ics=. Several more attributes about the resource are displayed, including its size and creation and modification times.
   1 The first row of the _Tickets_ section is where you create a new ticket.
   1 Optionally enter a number of seconds in the _Timeout_ box. If you don't enter anything, the ticket will never expire.
   1 Select the _Read_ radio button unless you want the ticket to be _Read/Write_, which is the default selection.
   1 Click _Grant Ticket_.
   1 You are still the =Home.ics= page again, but your new ticket appears in the _Tickets_ section.

---++++ Revoking a Ticket

If a ticket has served its purpose but hasn't yet expired (or never will), you can remove it using the account browser.

   1 Follow the instructions above to navigate to the =Home.ics= page.
   1 Locate the ticket in the _Tickets_ section and click its _Revoke_ link.
   1 The =Home.ics= page refreshes, but the ticket has been removed from the _Tickets_ section.

---++++ Constructing a Ticket-Bearing Calendar URL

#ConstructingTicketICSURL
Once you have published a calendar and granted a ticket on it, you can share the calendar with a friend (let's call him Bobby). You need to tell Bobby the URL of the calendar you published, and you have make sure that the URL contains the ticket you granted.

Notice that the _Tickets_ section of each account browser page in the web console includes WebDAV/CalDAV and Atom feed links for each ticket. You can right-click these links to copy the URLs and paste them into other applications, for instance to send Bobby an email.

You can also construct ticket-bearing URLs manually. Assume a calendar published at =http://localhost:8080/chandler/home/bcm/Home.ics= To embed the ticket into this calendar URL, simply add =?ticket=&lt;ticket-id&gt;= where =&lt;ticket-id&gt;= is replaced with the id of a ticket that you granted on =Home.ics=. You can find the id by looking in the account browser as described above. Now the calendar URL is =http://localhost:8080/chandler/home/bcm/Home.ics?ticket=0fc3bd0a5f2=.

---++ Account Browser

The Account Browser allows you to view the contents of your collection and perform simple maintenance tasks on collections and items. Access the Account Browser by clicking the _Account Browser_ link at the top right-hand side of the page. After clicking this link you will be browsing the root of your account. 

<img src="%ATTACHURLPATH%/accountbrowser.jpg" alt="accountbrowser.jpg"/>

---+++ Activating the Account Browser

#ActivatingtheAccountBrowser
Cosmo provides a file system like browser for viewing your account.  This feature is turned off by default.  To activate the account browser:

   1 Click on the settings link in the upper right hand corner.
   1 Click on the Advanced Tab (in the middle) in the settings dialog
   1 Check the box marked "Show Account Browser Link"
   1 Click the save button (lower right of the dialog)

<img src="%ATTACHURLPATH%/settings.jpg" alt="settings.jpg"/>

A link labelled *Account Browser* will appear in the upper right portion of the Cosmo UI, between the Settings and Help links.  When you click on this link, the Account Browser will open in a new window.

---+++ Top Section

Under the Chandler Serverlogo you will see some information about what you are browsing like the UID and the creation date. There are also some links which are different depending on what type of item you are browsing:

---++++ Collections

When browsing collections there is a _subscribe to feed_ link which you can copy and paste into your Atom reader so you can be notified of changes to that collection.

<img src="%ATTACHURLPATH%/browsecollection.jpg" alt="browsecollection.jpg"/>

---++++ Calendar Collections

If you are browsing a calendar collection  you are provided with a link to download the entire contents of the calendar collection in a single iCalendar file - just right-click the _download as iCalendar_ link and choose "save as..." to download this file, or "copy link" to copy the link into your clipboard for pasting into clients that support the webcal format like iCal.

You can also view the contents of calendar collections (events) in a simple HTML view by clicking _view as HTML_. This page shows the event description, location and start and end dates. The event data is encoded in the hCalendar microformat so that browsers (or browser plugins) that understand hCal can easily pull the structured event information from the page and do interesting things with it.

---++++ Calendar Items

You can click the _download as iCalendar_ link to download a single calendar item, like an event, as an iCalendar file. 

---++++ Other items

You can download any other item that you are browsing with the _download_ link.

---+++ Contents Section

For all types of collections there is a _Contents_ section which lists all the contents of your collection. You can browse any item in your collection including other collections by clicking _browse_. You can remove any item in your collection by click _remove_. _WARNING_ - There is no warning when removing an item - clicking _remove_ immediately and irrevocably removes (i.e. deletes) the item.

---+++ Tickets Section

The _Tickets_ section lists tickets that have been granted on the currently browsed item.

For more information on tickets, including how to create them, refer to [[#ControlAccessTickets][tickets section]] of "Controlling access to your Calendar".

---+++ Properties Section

The properties section lists any WebDAV properties that have been set on an item.

---++ Returning To Calendar and Dashboard view

You can return to the calendar and dashboard view by clicking the _Calendar and Dashboard_ link at the top right-hand side of the page. 

---+++ Bookmarkable URLs

#BookmarkableUrl

You can give other people a URL which allow them to access your calendar on Cosmo. These URLs are constructed from tickets, so be sure that you have read the section on [[#ControlAccessTickets][Tickets]] before proceeding. 

Bookmarkable URLs have the permissions of the tickets that they are created from. So if you use a read-only ticket to create a bookmarkable URL, the people who you give the URL to will have read-only access to your calendar. If you create a bookmarkable URL using a read-write ticket, then people will be able to both read and modify your calendar.  

---++++ Constructing a Bookmarkable URL from a Chandler Ticket URL

#ConstructBookmarkableUrl 

To construct a bookmarkable URL without using Chandler, or if you are using an earlier version of Chandler, you first need to make sure that you have created the right kind of ticket (read-only or read-write) for the calendar that you want to share.  If you haven't done that already, follow the directions in the 
[[#ControlAccessTickets][Tickets]] section to grant the appropriate tickets.  Once you have the right tickets, it's actually pretty easy.

In the Account Browser, go to the _Tickets_ section for the calendar that you want to share.  Look at the line for the ticket that you want to use to make a bookmarkable url.  In the sharing links section there are three links, labelled [dav], [feed], and [pim].   The URL for the [pim] link is the bookmarkable URL, and you can get the URL by copying that link using your browser.  You can then send that URL to people who you want to share you calendar with.


---++ Contributors

   * [[Main.BrianMoseley][Brian Moseley]]
   * [[Main.BradLauster][Brad Lauster]]
   * [[Main.BobbyRullo][Bobby Rullo]]
   * [[Main.MikeT][Mike Taylor]]
   * [[Main.MimiYin][Mimi Yin]]
   * Christopher Tengi
   * [[Main.TravisVachon][Travis Vachon]]
   * [[Main.TedLeung][Ted Leung]]
   * [[Main.PriscillaChung][Priscilla Chung]]
   * [[Main.RandyLetness][Randy Letness]]
chandlerproject.org
VISION
TOUR
Download Desktop
Get a Hub Account
Get Chandler Server FAQ
Get Started Blog
Mailing Lists
Chat on IRC
Report a Bug
Get Involved
OSAF Community
About OSAF

Projects Wiki Changes
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.
You are viewing a mobilized version of this site...
View original page here