projectal

  1"""
  2A python client for the [Projectal API](https://projectal.com/docs/latest).
  3
  4## Getting started
  5
  6```
  7import projectal
  8import os
  9
 10# Supply your Projectal server URL and account credentials
 11projectal.api_base = https://yourcompany.projectal.com
 12projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
 13projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')
 14
 15# Test communication with server
 16status = projectal.status()
 17
 18# Test account credentials
 19projectal.login()
 20details = projectal.auth_details()
 21```
 22
 23----
 24
 25## Changelog
 26
 27### 4.2.1
 28- Added classes allowing for the management of dynamic enums. The user must have the "List Management"
 29  permission to update enums.
 30
 31  New classes:
 32  - `projectal.CompanyTypes`
 33  - `projectal.SkillLevels`
 34  - `projectal.StaffTypes`
 35  - `projectal.PriorityLevels`
 36  - `projectal.ComplexityLevels`
 37  - `projectal.CurrencyList`
 38
 39  The current enum can be retrieved with get(), and updated with set().
 40  For example, to return the current SkillLevels enum:
 41
 42  ```
 43  projectal.SkillLevels.get()
 44  ```
 45
 46  For each enum the entire list of key value pairs must be provided when calling set(),
 47  any existing values that are omitted from the dictionary will be removed,
 48  and any additional values will be added.
 49
 50  To update the SkillLevels enum with a new value:
 51
 52  ```
 53  new_value_added = {
 54      "Senior": 10,
 55      "Mid": 20,
 56      "Junior": 30,
 57      # new SkillLevel value "Beginner"
 58      "Beginner": 40,
 59  }
 60  projectal.SkillLevels.set(new_value_added)
 61  ```
 62
 63  To change the name of a value, set a new key name for the original value:
 64
 65  ```
 66  updated_value_name = {
 67      # changing "Senior" SkillLevel to "Expert"
 68      "Expert": 10,
 69      "Mid": 20,
 70      "Junior": 30,
 71  }
 72  projectal.SkillLevels.set(updated_value_name)
 73  ```
 74
 75  To remove an existing value, call set on a dictionary with that value removed:
 76
 77  ```
 78  value_removed = {
 79      "Senior": 10,
 80      "Mid": 20,
 81      # "Junior" SkillLevel removed
 82  }
 83  projectal.SkillLevels.set(new_value_added)
 84  ```
 85
 86  Updating the CurrencyList works differently to the other enums, since the
 87  names of values must match the alphabetic currency code and the value must
 88  match the numeric currency code.
 89  This will cause an exception if you try to change the name for any values.
 90
 91  Adding a new currency:
 92
 93  ```
 94  new_currency_added = {
 95    "AED": 784
 96    ...
 97    # rest of the existing currencies
 98    ...
 99    # new currency to add with the alphabetic and numeric code
100    "ZWL": 932,
101  }
102  projectal.CurrencyList.set(new_currency_added)
103  ```
104
105  Removing an existing currency requires you to provide the numeric code for
106  the currency as a negative value.
107
108  ```
109  currency_removed = {
110    # this currency will be removed
111    "AED": -784
112    ...
113    # rest of the existing currencies
114    ...
115  }
116  projectal.CurrencyList.set(currency_removed)
117  ```
118
119### 4.2.0
120Version 4.2.0 accompanies the release of Projectal 4.1.0
121
122- Minimum Projectal version is now 4.1.0.
123
124- Changed order of applying link types when an entity is initialized,
125prevents a type error with reverse linking in certain situations.
126
127- `projectal.Task.reset_duration()` now supports adjustments with multi day calendar exceptions.
128
129- `projectal.Task.reset_duration()` location working days override base exceptions.
130
131- `projectal.TaskTemplate.list()` fixed incorrect query when using inherited method.
132
133
134### 4.1.0
135- DateLimit.Max enum value changed from "9999-12-31" to "3000-01-01". This reflects changes to the Projectal
136backend that defines this as the maximum allowable date value. The front end typically considers this value as
137equivalent with having no end date.
138
139- Updated requirements.txt version for requests package
140
141- Minimum Projectal version is now 4.0.40
142
143### 4.0.3
144- When a dict object is passed to the update class method, it will be converted to the corresponding Entity type.
145  Allows for proper handling of keys that require being treated as links.
146
147### 4.0.2
148- Booking entity is now fetched with project field and either staff or resource field.
149
150- Added missing link methods for 'Booking' entity (Note, File)
151
152- Added missing link methods for 'Activity' entity (Booking, Note, File, Rebate)
153
154- Reduced maximum number of link methods to 100 for a single batch request to prevent timeouts
155under heavy load.
156
157### 4.0.1
158- Minimum Projectal version is now 4.0.0.
159
160### 4.0.0
161
162Version 4.0.0 accompanies the release of Projectal 4.0.
163
164- Added the `Activity` entity, new in Projectal 4.0.
165
166- Added the `Booking` entity, new in Projectal 4.0.
167
168### 3.1.1
169- Link requests generated by 'projectal.Entity.create()' and 'projectal.Entity.update()' are now
170  executed in batches. This is enabled by default with the 'batch_linking=True' parameter and can
171  be disabled to execute each link request individually. It is recommended to leave this parameter
172  enabled as this can greatly reduce the number of network requests.
173
174### 3.1.0
175- Minimum Projectal version is now 3.1.5.
176
177- Added `projectal.Webhook.list_events()`. See API doc for details on how to use.
178
179- Added `deleted_at` parameter to `projectal.Entity.get()`. This value should be a UTC timestamp
180  from a webhook delete event.
181
182- Added `projectal.ldap_sync()` to initiate a user sync with the LDAP/AD service configured in
183  the Projectal server settings.
184
185- Enhanced output of `projectal.Entity.changes()` function when reporting link changes.
186  It no longer dumps the entire before-and-after list with the full content of each linked entity.
187  Now reports three lists: `added`, `updated`, `removed`. Entities within the `updated` list
188  follow the same `old` vs `new` dictionary model for the data attributes within them. E.g:
189
190    ```
191    resourceList: [
192        'added': [],
193        'updated': [
194            {'uuId': '14eb4c31-0f92-49d1-8b4d-507ab939003e', 'resourceLink': {'utilization': {'old': 0.1, 'new': 0.9}}},
195        ],
196        'removed': []
197    ]
198    ```
199  This should result in slimmer logs that are much easier to understand as the changes are
200  clearly indicated.
201
202### 3.0.2
203- Added `projectal.Entity.get_link_definitions()`. Exposes entity link definition dictionary.
204  Consumers can inspect which links an Entity knows about and their internal settings.
205  Link definitions that appear here are the links valid for `links=[]` parameters.
206
207### 3.0.1
208- Fixed fetching project with links=['task'] not being available.
209
210- Improved Permission.list(). Now returns a dict with the permission name as
211  key with Permission objects as the value (instead of list of uuIds).
212
213- Added a way to use the aliasing feature of the API (new in Projectal 3.0).
214Set `projectal.api_alias = 'uuid'` to the UUID of a User object and all
215requests made will be done as that user. Restore this value to None to resume
216normal operation. (Some rules and limitations apply. See API for more details.)
217
218- Added complete support for the Tags entity (including linkers).
219
220### 3.0
221
222Version 3.0 accompanies the release of Projectal 3.0.
223
224**Breaking changes**:
225
226- The `links` parameter on `Entity` functions now consumes a list of entity
227  names instead of a comma-separated string. For example:
228
229    ```
230    # Before:
231    projectal.Staff.get('<uuid>', links='skill,location')  # No longer valid
232    # Now:
233    projectal.Staff.get('<uuid>', links=['skill', 'location'])
234    ```
235
236- The `projectal.enums.SkillLevel` enum has had all values renamed to match the new values
237  used in Projectal (Junior, Mid, Senior). This includes the properties on
238  Skill entities indicating work time for auto-scheduling (now `juniorLevel`,
239  `midLevel`, `seniorLevel`).
240
241**Other changes**:
242
243- Working with entity links has changed in this release. The previous methods
244  are still available and continue to work as before, but there is no need
245  to interact with the `projectal.linkers` methods yourself anymore.
246
247  You can now modify the list of links within an entity and save the entity
248  directly. The library will automatically determine how the links have been
249  modified and issue the correct linker methods on your behalf. E.g.,
250  you can now do:
251
252    ```
253    staff = projectal.Staff.get('<uuid>', links=['skill'])
254    staff['firstName'] = "New name"  # Field update
255    staff['skillList'] = [skill1, skill2, skill3]  # Link update
256    staff.save()  # Both changes are saved
257
258    task = projectal.Task.get('<uuid>', links=['stage'])
259    task['stage'] = stage1  # Uses a single object instead of list
260    task.save()
261    ```
262
263  See `examples/linking.py` for a more complete demonstration of linking
264  capabilities and limitations.
265
266- Linkers (`projectal.linkers`) can now be given a list of Entities (of one
267 type) to link/unlink/relink in bulk. E.g:
268    ```
269    staff.unlink_skill(skill1)  # Before
270    staff.unlink_skill([skill1, skill2, skill3])  # This works now too
271    ```
272
273- Linkers now strip the payload to only the required fields instead of passing
274  on the entire Entity object. This cuts down on network traffic significantly.
275
276- Linkers now also work in reverse. The Projectal server currently only supports
277  linking entities in one direction (e.g., Company to Staff), which often means
278  writing something like:
279    ```
280    staff.link_location(location)
281    company.link_staff(staff)
282    ```
283  The change in direction is not very intuitive and would require you to constantly
284  verify which direction is the one available to you in the documentation.
285
286  Reverse linkers hide this from you and figure out the direction of the relationship
287  for you behind the scenes. So now this is possible, even though the API doesn't
288  strictly support it:
289    ```
290    staff.link_location(location)
291    staff.link_company(company)
292    ```
293    Caveat: the documentation for Staff will not list Company links. You will still
294    have to look up the Company documentation for the link description.
295
296- Requesting entity links with the `links=` parameter will now always ensure the
297  link field (e.g., `taskList`) exists in the result, even if there are no links.
298  The server may not always return a value, but we can use a default value ([] for
299  lists, None for dicts).
300
301- Added a `Permission` entity to correctly type Permissions in responses.
302
303- Added a `Tag` entity, new in Projectal 3.0.
304
305- Added `links` parameter to `Company.get_primary_company()`
306
307- `Department.tree()`: now consumes a `holder` Entity object instead
308  of a uuId.
309
310- `Department.tree()`: added `generic_staff` parameter, new in
311  Projectal 3.0.
312
313- Don't break on trailing slash in Projectal URL
314
315- When creating tasks, populate the `projectRef` and `parent` fields in the
316  returned Task object.
317
318- Added convenience functions for matching on fields where you only want
319  one result (e.g match_one()) which return the first match found.
320
321- Update the entity `history()` method for Projectal 3.0. Some new parameters
322  allow you to restrict the history to a particular range or to get only the
323  changes for a webhook timestamp.
324
325- Entity objects can call `.history()` on themselves.
326
327- The library now keeps a reference to the User account that is currently logged
328  in and using the API: `projectal.api_auth_details`.
329
330**Known issues**:
331- You cannot save changes to Notes or Calendars via their holding entity. You
332  must save the changes on the Note or Calendar directly. To illustrate:
333  ```
334  staff = projectal.Staff.get(<uuid>, links=['calendar'])
335  calendar = staff['calendarList'][0]
336  calendar['name'] = 'Calendar 2'
337
338  # Cannot do this - will not pick up the changes
339  staff.save()
340
341  # You must do this for now
342  calendar.save()
343  ```
344  This will be resolved in a future release.
345
346- When creating Notes, the `created` and `modified` values may differ by
347  1ms in the object you have a reference to compared to what is actually
348  stored in the database.
349
350- Duration calculation is not precise yet (mentioned in 2.1.0)
351
352### 2.1.0
353**Breaking changes**:
354- Getting location calendar is now done on an instance instead of class. So
355  `projectal.Location.calendar(uuid)` is now simply `location.calendar()`
356- The `CompanyType.Master` enum has been replaced with `CompanyType.Primary`.
357  This was a leftover reference to the Master Company which was renamed in
358  Projectal several versions ago.
359
360**Other changes**:
361- Date conversion functions return None when given None or empty string
362- Added `Task.reset_duration()` as a basic duration calculator for tasks.
363  This is a work-in-progress and will be gradually improved. The duration
364  calculator takes into consideration the location to remove non-work
365  days from the estimate of working duration. It currently does not work
366  for the time component or `isWorking=True` exceptions.
367- Change detection in `Entity.changes()` now excludes cases where the
368  server has no value and the new value is None. Saving this change has
369  no effect and would always detect a change until a non-None value is
370  set, which is noisy and generates more network activity.
371
372### 2.0.3
373- Better support for calendars.
374  - Distinguish between calendar containers ("Calendar") and the
375    calendar items within them ("CalendarItem").
376  - Allow CalendarItems to be saved directly. E.G item.save()
377- Fix 'holder' parameter in contact/staff/location/task_template not
378  permitting object type. Now consumes uuId or object to match rest of
379  the library.
380- `Entity.changes()` has been extended with an `old=True` flag. When
381  this flag is true, the set of changes will now return both the original
382  and the new values. E.g.
383```
384task.changes()
385# {'name': 'current'}
386task.changes(old=True)
387# {'name': {'old': 'original', 'new': 'current'}}
388```
389- Fixed entity link cache causing errors when deleting a link from an entity
390  which has not been fetched with links (deleting from empty list).
391
392### 2.0.2
393- Fixed updating Webhook entities
394
395### 2.0.1
396- Fixed application ID not being used correctly.
397
398### 2.0.0
399- Version 2.0 accompanies the release of Projectal 2.0. There are no major changes
400  since the previous release.
401- Expose `Entity.changes()` function. It returns a list of fields on an entity that
402  have changed since fetching it. These are the changes that will be sent over to the
403  server when an update request is made.
404- Added missing 'packaging' dependency to requirements.
405
406### 1.2.0
407
408**Breaking changes**:
409
410- Renamed `request_timestamp` to `response_timestamp` to better reflect its purpose.
411- Automatic timestamp conversion into dates (introduced in `1.1.0`) has been reverted.
412  All date fields returned from the server remain as UTC timestamps.
413
414  The reason is that date fields on tasks contain a time component and converting them
415  into date strings was erasing the time, resulting in a value that does not match
416  the database.
417
418  Note: the server supports setting date fields using a date string like `2022-04-05`.
419  You may use this if you prefer but the server will always return a timestamp.
420
421  Note: we provide utility functions for easily converting dates from/to
422  timestamps expected by the Projectal server. See:
423  `projectal.date_from_timestamp()`,`projectal.timestamp_from_date()`, and
424  `projectal.timestamp_from_datetime()`.
425
426**Other changes**:
427- Implement request chunking - for methods that consume a list of entities, we now
428  automatically batch them up into multiple requests to prevent timeouts on really
429  large request. Values are configurable through
430  `projectal.chunk_size_read` and `projectal.chunk_size_write`.
431  Default values: Read: 1000 items. Write: 200 items.
432- Added profile get/set functions on entities for easier use. Now you only need to supply
433  the key and the data. E.g:
434
435```
436key = 'hr_connector'
437data = {'staff_source': 'company_z'}
438task.profile_set(key, data)
439```
440
441- Entity link methods now automatically update the entity's cached list of links. E.g:
442  a task fetched with staff links will have `task['staffList'] = [Staff1,Staff2]`.
443  Before, doing a `task.link_staff(staff)` did not modify the list to reflect the
444  addition. Now, it will turn into `[Staff1,Staff2,Staff3]`. The same applies for update
445  and delete.
446
447  This allows you to modify links and continue working with that object without having
448  to fetch it again to obtain the most recent link data. Be aware that if you acquire
449  the object without requesting the link data as well
450  (e.g: `projectal.Task.get(id, links='STAFF')`),
451  these lists will not accurately reflect what's in the database, only the changes made
452  while the object is held.
453
454- Support new `applicationId` property on login. Set with: `projectal.api_application_id`.
455  The application ID is sent back to you in webhooks so you know which application was
456  the source of the event (and you can choose to filter them accordingly).
457- Added `Entity.set_readonly()` to allow setting values on entities that will not
458  be sent over to the server when updating/saving the entity.
459
460  The main use case for this is to populate cached entities which you have just created
461  with values you already know about. This is mainly a workaround for the limitation of
462  the server not sending the full object back after creating it, resulting in the client
463  needing to fetch the object in full again if it needs some of the fields set by the
464  server after creation.
465
466  Additionally, some read-only fields will generate an error on the server if
467  included in the update request. This method lets you set these values on newly
468  created objects without triggering this error.
469
470  A common example is setting the `projectRef` of a task you just created.
471
472
473### 1.1.1
474- Add support for 'profiles' API. Profiles are a type of key-value storage that target
475  any entity. Not currently documented.
476- Fix handling error message parsing in ProjectalException for batch create operation
477- Add `Task.update_order()` to set task order
478- Return empty list when GETing empty list instead of failing (no request to server)
479- Expose the timestamp returned by requests that modify the database. Use
480  `projectal.request_timestamp` to get the value of the most recent request (None
481  if no timestamp in response)
482
483### 1.1.0
484- Minimum Projectal version is now 1.9.4.
485
486**Breaking changes**:
487- Entity `list()` now returns a list of UUIDs instead of full objects. You may provide
488  an `expand` parameter to restore the previous behavior: `Entity.list(expand=True)`.
489  This change is made for performance reasons where you may have thousands of tasks
490  and getting them all may time out. For those cases, we suggest writing a query to filter
491  down to only the tasks and fields you need.
492- `Company.get_master_company()` has been renamed to `Company.get_primary_company()`
493  to match the server.
494- The following date fields are converted into date strings upon fetch:
495  `startTime`, `closeTime`, `scheduleStart`, `scheduleFinish`.
496  These fields are added or updated using date strings (like `2022-03-02`), but the
497  server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This
498  change ensures they are always date strings for consistency.
499
500**Other changes**:
501- When updating an entity, only the fields that have changed are sent to the server. When
502  updating a list of entities, unmodified entities are not sent to the server at all. This
503  dramatically reduces the payload size and should speed things up.
504- When fetching entities, entity links are now typed as well. E.g. `project['rebateList']`
505  contains a list of `Rebate` instead of `dict`.
506- Added `date_from_timestamp()` and `timestamp_from_date()` functions to help with
507  converting to/from dates and Projectal timestamps.
508- Entity history now uses `desc` by default (index 0 is newest)
509- Added `Project.tasks()` to list all task UUIDs within a project.
510
511### 1.0.3
512- Fix another case of automatic JWT refresh not working
513
514### 1.0.2
515- Entity instances can `save()` or `delete()` on themselves
516- Fix broken `dict` methods (`get()` and `update()`) when called from Entity instances
517- Fix automatic JWT refresh only working in some cases
518
519### 1.0.1
520- Added `list()` function for all entities
521- Added search functions for all entities (match-, search, query)
522- Added `Company.get_master_company()`
523- Fixed adding template tasks
524
525"""
526import logging
527import os
528
529from projectal.entities import *
530from projectal.dynamic_enums import *
531from .api import *
532from . import profile
533
534api_base = os.getenv("PROJECTAL_URL")
535api_username = os.getenv("PROJECTAL_USERNAME")
536api_password = os.getenv("PROJECTAL_PASSWORD")
537api_application_id = None
538api_auth_details = None
539api_alias = None
540cookies = None
541chunk_size_read = 1000
542chunk_size_write = 200
543
544# Records the timestamp generated by the last request (database
545# event time). These are reported on add or updates; if there is
546# no timestamp in the response, this is set to None.
547response_timestamp = None
548
549
550# The minimum version number of the Projectal instance that this
551# API client targets. Lower versions are not supported and will
552# raise an exception.
553MIN_PROJECTAL_VERSION = "4.0.40"
554
555__verify = True
556
557logging.getLogger("projectal-api-client").addHandler(logging.NullHandler())