projectal.entities.staff

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