projectal.entities.staff

  1from datetime import datetime
  2
  3import projectal
  4from projectal.entity import Entity
  5from projectal.linkers import *
  6
  7
  8class Staff(Entity, LocationLinker, ResourceLinker, SkillLinker, FileLinker,
  9            CompanyLinker, DepartmentLinker, TaskLinker, TaskTemplateLinker,
 10            NoteLinker, CalendarLinker, TagLinker):
 11    """
 12    Implementation of the [Staff](https://projectal.com/docs/latest/#tag/Staff) API.
 13    """
 14    _path = 'staff'
 15    _name = 'staff'
 16    _links = [LocationLinker, ResourceLinker, SkillLinker, FileLinker, NoteLinker,
 17              CalendarLinker, TagLinker]
 18    _links_reverse = [CompanyLinker, DepartmentLinker, TaskLinker, TaskTemplateLinker]
 19
 20    @classmethod
 21    def calendar(cls, uuId, begin=None, until=None):
 22        """
 23        Returns the calendar of the staff with `uuId`.
 24
 25        `begin`: Start date in `yyyy-MM-dd`.
 26
 27        `until`: End date in `yyyy-MM-dd`.
 28
 29
 30        Optionally specify a date range. If no range specified, the
 31        minimum and maximum dates are used (see projectal.enums.DateLimit).
 32        """
 33        if begin:
 34            begin = datetime.strptime(begin, '%Y-%m-%d').date()
 35        if until:
 36            until = datetime.strptime(until, '%Y-%m-%d').date()
 37
 38        url = '/api/staff/{}/calendar?'.format(uuId)
 39        params = []
 40        params.append('begin={}'.format(begin)) if begin else None
 41        params.append('until={}'.format(until)) if until else None
 42        url += '&'.join(params)
 43
 44        cals = api.get(url)
 45        cals = [projectal.Calendar(c) for c in cals]
 46        return cals
 47
 48    @classmethod
 49    def calendar_availability(cls, uuId, begin=None, until=None):
 50        """
 51        Returns the availability (in hours) of the staff in `uuId`
 52        for each day within the specified date range.
 53
 54        `begin`: Start date in `yyyy-MM-dd`.
 55
 56        `until`: End date in `yyyy-MM-dd`.
 57
 58        If no range specified, the minimum and maximum dates are
 59        used (see projectal.enums.DateLimit).
 60        """
 61        if begin:
 62            begin = datetime.strptime(begin, '%Y-%m-%d').date()
 63        if until:
 64            until = datetime.strptime(until, '%Y-%m-%d').date()
 65
 66        url = '/api/staff/{}/calendar/availability?'.format(uuId)
 67        params = []
 68        params.append('begin={}'.format(begin)) if begin else None
 69        params.append('until={}'.format(until)) if until else None
 70        url += '&'.join(params)
 71
 72        return api.get(url)
 73
 74    @classmethod
 75    def usage(cls, begin, until, holder=None, start=None, limit=None, span=None,
 76              ksort=None, order=None, staff=None):
 77        """
 78        Returns the staff-to-task allocations for all staff within the `holder`.
 79
 80        See [Usage API](https://projectal.com/docs/latest/#tag/Staff/paths/~1api~1staff~1usage/post)
 81        for full details.
 82        """
 83        url = '/api/staff/usage?begin={}&until={}'.format(begin, until)
 84        params = []
 85        params.append('holder={}'.format(holder)) if holder else None
 86        params.append('start={}'.format(start)) if start else None
 87        params.append('limit={}'.format(limit)) if limit else None
 88        params.append('span={}'.format(span)) if span else None
 89        params.append('ksort={}'.format(ksort)) if ksort else None
 90        params.append('order={}'.format(order)) if order else None
 91        if len(params) > 0:
 92            url += '&' + '&'.join(params)
 93        payload = staff if staff and not holder else None
 94        response = api.post(url, payload)
 95        # Do some extra checks for empty list case
 96        if 'status' in response:
 97            # We didn't have a 'jobCase' key and returned the outer dict.
 98            return []
 99        return response
100
101    @classmethod
102    def auto_assign(cls, type="Recommend", over_allocate_staff=False,
103                    include_assigned_task=False, include_started_task=False,
104                    skills=None, tasks=None, staffs=None):
105        """
106        Automatically assign a set of staff (real or generic) to a set of tasks
107        using various skill and allocation criteria.
108
109        See [Staff Assign API](https://projectal.com/docs/latest/#tag/Staff-Assign/paths/~1api~1allocation~1staff/post)
110        for full details.
111        """
112        url = '/api/allocation/staff'
113        payload = {
114            "type": type,
115            "overAllocateStaff": over_allocate_staff,
116            "includeAssignedTask": include_assigned_task,
117            "includeStartedTask": include_started_task,
118            "skillMatchList": skills if skills else [],
119            "staffList": staffs if staffs else [],
120            "taskList": tasks if tasks else []
121        }
122        return api.post(url, payload)