projectal.entities.staff

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