RFC: Format proposal for time tracking data

Tue Jul 1 17:03:20 CEST 2008

Hi!

I'd like to present a draft for an extension of the Kolab format. The
purpose is to store time tracking data on the Kolab server.

(Note: When responding to this mail, please keep it to the
       kolab-format at kolab.org list as long as it concerns the new data
       types presented here. I'm just cross posting this as there
       might be some people on the developers list interested in a
       time tracking tool, too).

The following data types are suggested:

The mimetype for time tracking data is
"application/x-vnd.kolab.timetrack". This is the specification of the
body contents:

        <?xml version="1.0" encoding="UTF-8"?>
        <timetrack version="1.0">
          <!-- Common fields -->
          <uid>(string, no default)</uid>
          <body>(string, default empty)</body>
          <categories>(string, default empty)</categories>
          <creation-date>(datetime, no default)</creation-date>
          <last-modification-date>(datetime, no default)</last-modification-date>
          <sensitivity>(string, default public)</sensitivity>
          {<inline-attachment>(string, no default)</inline-attachment>}
          {<link-attachment>(string, no default)</link-attachment>}
          <product-id>(string, default empty)</product-id>

          <!-- Time tracking specific fields -->
          <client>(string, no default, not empty)</client>
          <employee>(string, no default, not empty)</employee>
          <type>(string, no default, not empty)</type>
          <hours>(string, no default, not empty)</hours>
          <rate>(string, no default, not empty)</rate>
          <costobject>(string, no default, not empty)</costobject>
          <billable>(number, default 0)</billable>
          <submitted>(number, default 0)</submitted>
          <exported>(number, default 0)</exported>
          <date>(number, no default)</date>
          <description>(string, default empty)</description>
          <note>(string, default empty)</note>
        </timetrack>

Description of the specific fields:

  - client: A cross reference to the client in a Kolab
    addressbook. The reference uses the UID of the address
    element. The application handling the time tracking data needs to
    be configured so that it knows how to cross reference the address
    book.

  - employee: The mail address of the employee that generated the time
    tracking data.

  - type: The UID of the job type. The job type has to be stored in
    the same IMAP folder as the time tracking data.

  - hours: A floating point number stored as string. It holds the
    amount of time spent on the item represented by this time track
    entry.

  - rate: The rate at which the time will be billed. This is fetched
    from the job type for this entry but is written into the time
    track entry for convenience. This is a floating point number
    stored as a string.

  - costobject: UID of a cost object on the server. This could be a
    task for example. The application handling the time tracking data
    needs to know how to cross reference cost objects on the server.

  - billable: Is this object billable (1) or not (0)?

  - submitted: Did the employee already submit the entry for review or
    invoice generation (1) or not (0)?

  - exported: Has the entry already been exported (1) or not (0)?
    E.g. into an invoice?

  - date: The day the time was spent.

  - description: A (required) description of the task.

  - note: Any additional notes.

In addition it will be necessary to represent different job types. The
mimetype for job type data is "application/x-vnd.kolab.jobtype". This
is the specification of the body contents:

        <?xml version="1.0" encoding="UTF-8"?>
        <jobtype version="1.0">
          <!-- Common fields -->
          <uid>(string, no default)</uid>
          <body>(string, default empty)</body>
          <categories>(string, default empty)</categories>
          <creation-date>(datetime, no default)</creation-date>
          <last-modification-date>(datetime, no default)</last-modification-date>
          <sensitivity>(string, default public)</sensitivity>
          {<inline-attachment>(string, no default)</inline-attachment>}
          {<link-attachment>(string, no default)</link-attachment>}
          <product-id>(string, default empty)</product-id>

          <!-- Job type specific fields -->
          <name>(string, default empty)</note>
          <billable>(number, default 0)</billable>
          <enabled>(number, default 0)</submitted>
          <rate>(string, no default, not empty)</rate>
        </jobtype>

Description of the specific fields:

  - name: The name of the job type

  - billable: Can this job type be billed (1) or not (0)?

  - enabled: Is this job type currently available (1) or not (0)?

  - rate: At which rate will this job type be billed (floating point
    number stored as a string)?

Please take this only as a very early draft only meant for getting
some comments and ideas.

While the suggestion is only proposing a theoretical data format it
is of course driven by an existing client application.

Horde released "Hermes" (http://horde.org/hermes/) yesterday. This is
a small time tracking application that interfaces nicely with the
other Horde applications (addressbooks and tasks). I already wrote a
Kolab driver for this app now but I'll keep this private as long as
there is no common format we can agree on.

I hope there are some other devs that would like to use time tracking
on the Kolab server, too.

Cheers,

Gunnar

-- 
______ http://kdab.com _______________ http://kolab-konsortium.com _

p at rdus Kolab work is funded in part by KDAB and the Kolab Konsortium

____ http://www.pardus.de _________________ http://gunnarwrobel.de _
E-mail : p at rdus.de                                 Dr. Gunnar Wrobel
Tel.   : +49 700 6245 0000                          Bundesstrasse 29
Fax    : +49 721 1513 52322                          D-20146 Hamburg
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   >> Mail at ease - Rent a kolab groupware server at p at rdus <<                 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~