projectal.entities.staff

  1from datetime import datetime
  2
  3import projectal
  4from projectal.entity import Entity
  5from projectal.linkers import *
  6from projectal.errors import UsageException
  7from projectal.enums import DateLimit
  8
  9
 10class Staff(
 11    Entity,
 12    LocationLinker,
 13    ResourceLinker,
 14    SkillLinker,
 15    FileLinker,
 16    CompanyLinker,
 17    DepartmentLinker,
 18    TaskLinker,
 19    TaskTemplateLinker,
 20    NoteLinker,
 21    CalendarLinker,
 22    TagLinker,
 23    ContractLinker,
 24):
 25    """
 26    Implementation of the [Staff](https://projectal.com/docs/latest/#tag/Staff) API.
 27    """
 28
 29    _path = "staff"
 30    _name = "staff"
 31    _links = [
 32        LocationLinker,
 33        ResourceLinker,
 34        SkillLinker,
 35        FileLinker,
 36        NoteLinker,
 37        CalendarLinker,
 38        TagLinker,
 39        ContractLinker,
 40    ]
 41    _links_reverse = [CompanyLinker, DepartmentLinker, TaskLinker, TaskTemplateLinker]
 42
 43    @classmethod
 44    def calendar(cls, uuId, begin=None, until=None):
 45        """
 46        Returns the calendar of the staff with `uuId`.
 47
 48        `begin`: Start date in `yyyy-MM-dd`.
 49
 50        `until`: End date in `yyyy-MM-dd`.
 51
 52
 53        Optionally specify a date range. If no range specified, the
 54        minimum and maximum dates are used (see projectal.enums.DateLimit).
 55        """
 56        if begin:
 57            begin = datetime.strptime(begin, "%Y-%m-%d").date()
 58        if until:
 59            until = datetime.strptime(until, "%Y-%m-%d").date()
 60
 61        url = "/api/staff/{}/calendar?".format(uuId)
 62        params = []
 63        params.append("begin={}".format(begin)) if begin else None
 64        params.append("until={}".format(until)) if until else None
 65        url += "&".join(params)
 66
 67        cals = api.get(url)
 68        cals = [projectal.Calendar(c) for c in cals]
 69        return cals
 70
 71    @classmethod
 72    def calendar_availability(cls, uuId, begin=None, until=None):
 73        """
 74        Returns the availability (in hours) of the staff in `uuId`
 75        for each day within the specified date range.
 76
 77        `begin`: Start date in `yyyy-MM-dd`.
 78
 79        `until`: End date in `yyyy-MM-dd`.
 80
 81        If no range specified, the minimum and maximum dates are
 82        used (see projectal.enums.DateLimit).
 83        """
 84        if begin:
 85            begin = datetime.strptime(begin, "%Y-%m-%d").date()
 86        if until:
 87            until = datetime.strptime(until, "%Y-%m-%d").date()
 88
 89        url = "/api/staff/{}/calendar/availability?".format(uuId)
 90        params = []
 91        params.append("begin={}".format(begin)) if begin else None
 92        params.append("until={}".format(until)) if until else None
 93        url += "&".join(params)
 94
 95        return api.get(url)
 96
 97    @classmethod
 98    def usage(
 99        cls,
100        begin,
101        until,
102        holder=None,
103        start=None,
104        limit=None,
105        span=None,
106        ksort=None,
107        order=None,
108        staff=None,
109    ):
110        """
111        Returns the staff-to-task allocations for all staff within the `holder`.
112
113        See [Usage API](https://projectal.com/docs/latest/#tag/Staff/paths/~1api~1staff~1usage/post)
114        for full details.
115        """
116        url = "/api/staff/usage?begin={}&until={}".format(begin, until)
117        params = []
118        params.append("holder={}".format(holder)) if holder else None
119        params.append("start={}".format(start)) if start else None
120        params.append("limit={}".format(limit)) if limit else None
121        params.append("span={}".format(span)) if span else None
122        params.append("ksort={}".format(ksort)) if ksort else None
123        params.append("order={}".format(order)) if order else None
124        if len(params) > 0:
125            url += "&" + "&".join(params)
126        payload = staff if staff and not holder else None
127        response = api.post(url, payload)
128        # Do some extra checks for empty list case
129        if "status" in response:
130            # We didn't have a 'jobCase' key and returned the outer dict.
131            return []
132        return response
133
134    @classmethod
135    def auto_assign(
136        cls,
137        type="Recommend",
138        over_allocate_staff=False,
139        include_assigned_task=False,
140        include_started_task=False,
141        skills=None,
142        tasks=None,
143        staffs=None,
144    ):
145        """
146        Automatically assign a set of staff (real or generic) to a set of tasks
147        using various skill and allocation criteria.
148
149        See [Staff Assign API](https://projectal.com/docs/latest/#tag/Staff-Assign/paths/~1api~1allocation~1staff/post)
150        for full details.
151        """
152        url = "/api/allocation/staff"
153        payload = {
154            "type": type,
155            "overAllocateStaff": over_allocate_staff,
156            "includeAssignedTask": include_assigned_task,
157            "includeStartedTask": include_started_task,
158            "skillMatchList": skills if skills else [],
159            "staffList": staffs if staffs else [],
160            "taskList": tasks if tasks else [],
161        }
162        return api.post(url, payload)
163
164    @classmethod
165    def create_contract(
166        cls,
167        UUID,
168        payload={},
169        end_current_contract=False,
170        start_new_contract=False,
171    ):
172        """
173        Creates a new Contract for a staff, with updated fields from the payload
174
175        end_current: Sets the end date of the current contract to today's date
176        start_new_date: Sets the start date of the new contract to today's date
177
178        See [Staff Clone API](https://projectal.com/docs/latest#tag/Staff/paths/~1api~1staff~1clone/post)
179        for full details.
180        """
181
182        url = "/api/staff/clone?reference={}&as_contract=true".format(UUID)
183        date_today = datetime.today().strftime("%Y-%m-%d")
184
185        current_staff = None
186        if end_current_contract:
187            # Check if setting end date to today is
188            # invalid for current Staff Contract
189            current_staff = cls.get(UUID)
190            if projectal.timestamp_from_date(
191                current_staff.get("startDate")
192            ) > projectal.timestamp_from_date(date_today):
193                raise UsageException(
194                    f"Cannot set endDate before startDate for current contract: {date_today}"
195                )
196
197        if start_new_contract:
198            payload["startDate"] = date_today
199            payload["endDate"] = DateLimit.Max
200
201        response = api.post(url, payload)
202
203        if end_current_contract and current_staff:
204            current_staff["endDate"] = date_today
205            current_staff.save()
206
207        return response["jobClue"]["uuId"]