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