1 #!/usr/bin/python2.5

     2 #

     3 # Copyright 2009 the Melange authors.

     4 #

     5 # Licensed under the Apache License, Version 2.0 (the "License");

     6 # you may not use this file except in compliance with the License.

     7 # You may obtain a copy of the License at

     8 #

     9 #   http://www.apache.org/licenses/LICENSE-2.0

    10 #

    11 # Unless required by applicable law or agreed to in writing, software

    12 # distributed under the License is distributed on an "AS IS" BASIS,

    13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    14 # See the License for the specific language governing permissions and

    15 # limitations under the License.

    16 

    17 """This module contains the GHOP Task Model.

    18 """

    19 

    20 __authors__ = [

    21   '"Madhusudan.C.S" <madhusudancs@gmail.com>',

    22   '"Lennard de Rijk" <ljvderijk@gmail.com>',

    23 ]

    24 

    25 

    26 from google.appengine.ext import db

    27 

    28 from django.utils.translation import ugettext

    29 

    30 import soc.models.linkable

    31 import soc.models.organization

    32 import soc.models.program

    33 import soc.models.role

    34 import soc.models.student

    35 import soc.models.user

    36 

    37 

    38 class Task(soc.models.linkable.Linkable):

    39   """Model for a task used in GHOP workflow.

    40 

    41   The scope property of Linkable will be set to the Organization to which

    42   this task belongs to. A link_id will be generated automatically and will

    43   have no specific meaning other than identification.

    44   """

    45 

    46   #: Required field indicating the "title" of the task

    47   title = db.StringProperty(required=True,

    48                             verbose_name=ugettext('Title'))

    49   title.help_text = ugettext('Title of the task')

    50 

    51   #: Required field containing the description of the task

    52   description = db.TextProperty(required=True, 

    53                                 verbose_name=ugettext('Description'))

    54   description.help_text = ugettext('Complete description of the task')

    55 

    56   #: field indicating the difficulty level of the task. This is not

    57   #: mandatory so the it can be assigned at any later stage. 

    58   #: The options are configured by a Program Admin.

    59   difficulty = db.StringProperty(required=False,

    60                                  verbose_name=ugettext('Difficulty'))

    61   difficulty.help_text = ugettext('Difficulty Level of the task')

    62 

    63   #: Required field which contains the type of the task. These types are

    64   #: configured by a Program Admin.

    65   type = db.StringListProperty(required=True, 

    66                                verbose_name=ugettext('Task Type'))

    67   type.help_text = ugettext('Type of the task')

    68 

    69   #: A field which contains time allowed for completing the task (in hours)

    70   #: from the moment that this task has been assigned to a Student

    71   time_to_complete = db.IntegerProperty(required=True,

    72                                         verbose_name=('Time to Complete'))

    73   time_to_complete.help_text = ugettext(

    74       'Time allowed to complete the task, in hours, once it is claimed')

    75 

    76   #: List of Mentors assigned to this task. A Mentor who creates this

    77   #: task is assigned as the Mentor by default. An Org Admin will have

    78   #: to assign a Mentor upon task creation.

    79   mentors = db.ListProperty(item_type=db.Key, default=[])

    80 

    81   #: User profile to whom this task has been claimed by. This field

    82   #: is mandatory for claimed tasks

    83   user = db.ReferenceProperty(reference_class=soc.models.user.User,

    84                               required=False,

    85                               collection_name='assigned_tasks')

    86 

    87   #: Student profile to whom this task is currently assigned to. If the user

    88   #: has registered as a Student than this field will be filled in. This field

    89   #: is mandatory for all Tasks in the closed state.

    90   student = db.ReferenceProperty(reference_class=soc.models.student.Student,

    91                                  required=False,

    92                                  collection_name='assigned_tasks')

    93 

    94   #: Program in which this Task has been created

    95   program = db.ReferenceProperty(reference_class=soc.models.program.Program,

    96                                  required=True,

    97                                  collection_name='tasks')

    98 

    99   #: Required property which holds the state, the Task is currently in.

   100   #: This is a hidden field not shown on forms. Handled by logic internally.

   101   #: The state can be one of the following:

   102   #: unapproved: If Task is created by a Mentor, this is the automatically

   103   #:   assigned state.

   104   #: unpublished: This Task is not published yet.

   105   #: open: This Task is open and ready to be claimed.

   106   #: reopened: This Task has been claimed but never finished and has been

   107   #:   reopened.

   108   #: claim_requested: A Student has requested to claim this task.

   109   #: claimed: This Task has been claimed and someone is working on it.

   110   #: action_needed: Work on this Task must be submitted for review within 

   111   #:   24 hours.

   112   #: closed: Work on this Task has been completed to the org's content.

   113   #: awaiting_registration: Student has completed work on this task, but

   114   #:   needs to complete Student registration before this task is closed.

   115   #: needs_work: This work on this Tasks needs a bit more brushing up. This

   116   #:   state is followed by a Mentor review.

   117   #: needs_review: Student has submitted work for this task and it should

   118   #:   be reviewed by a Mentor.

   119   status = db.StringProperty(

   120       required=True, verbose_name=ugettext('Status'),

   121       choices=['unapproved', 'unpublished', 'open', 'reopened', 

   122                'claim_requested', 'claimed', 'action_needed', 

   123                'closed', 'awaiting_registration', 'needs_work',

   124                'needs_review'],

   125       default='unapproved')

   126 

   127   #: A field which indicates if the task was ever in the Reopened state.

   128   #: True indicates that its state was Reopened once, false indicated that it

   129   #: has never been in the Reopened state.

   130   was_reopened = db.BooleanProperty(default=False,

   131                                     verbose_name=ugettext('Has been reopened'))

   132 

   133   #: This field is set to the next deadline that will have consequences for

   134   #: this Task. For instance this will store a DateTime property which will

   135   #: tell when this Task should be completed.

   136   deadline = db.DateTimeProperty(required=False,

   137                                  verbose_name=ugettext('Deadline'))

   138 

   139   #: Required field containing the Mentor/Org Admin who created this task

   140   created_by = db.ReferenceProperty(reference_class=soc.models.role.Role,

   141                                     required=True,

   142                                     collection_name='created_tasks',

   143                                     verbose_name=ugettext('Created by'))

   144 

   145   #: Date when the proposal was created

   146   created_on = db.DateTimeProperty(required=True, auto_now_add=True,

   147                                    verbose_name=ugettext('Created on'))

   148 

   149   #: Required field containing the Mentor/Org Admin who last edited this

   150   #: task. It changes only when Mentor/Org Admin changes title, description,

   151   #: difficulty, type, time_to_complete.

   152   modified_by = db.ReferenceProperty(reference_class=soc.models.role.Role,

   153                                    required=True,

   154                                    collection_name='edited_tasks',

   155                                    verbose_name=ugettext('Modified by'))

   156 

   157   #: Date when the proposal was last modified, should be set manually on edit

   158   modified_on = db.DateTimeProperty(required=True, auto_now_add=True,

   159                                     verbose_name=ugettext('Modified on'))

   160 

   161   #: A field which holds the entire history of this task in JSON. The

   162   #: structure of this JSON string is as follows:

   163   #: {

   164   #:    timestamp1: {

   165   #:                   "user": User reference

   166   #:                   "student": Student reference

   167   #:                   ...

   168   #:                   "state": "Unapproved"

   169   #:                   ...

   170   #:                   "edited_by": Role reference

   171   #:                   

   172   #:               }

   173   #:    timestamp2: {

   174   #:                   "state": "Unpublished"

   175   #:               }

   176   #: }

   177   #: First dictionary item holds the values for all the properties in this

   178   #: model. The subsequent items hold the properties that changed at the

   179   #: timestamp given by the key.

   180   #: Reference properties will be stored by calling str() on their Key.

   181   history = db.TextProperty(required=True, default='')