projectal

A python client for the Projectal API.

Getting started

import projectal
import os

# Supply your Projectal server URL and account credentials
projectal.api_base = https://yourcompany.projectal.com
projectal.api_username = os.environ.get('PROJECTAL_USERNAME')
projectal.api_password = os.environ.get('PROJECTAL_PASSWORD')

# Test communication with server
status = projectal.status()

# Test account credentials
projectal.login()
details = projectal.auth_details()

Changelog

4.0.2

  • Booking entity is now fetched with project field and either staff or resource field.

  • Added missing link methods for 'Booking' entity (Note, File)

  • Added missing link methods for 'Activity' entity (Booking, Note, File, Rebate)

  • Reduced maximum number of link methods to 100 for a single batch request to prevent timeouts under heavy load.

4.0.1

  • Minimum Projectal version is now 4.0.0.

4.0.0

Version 4.0.0 accompanies the release of Projectal 4.0.

  • Added the Activity entity, new in Projectal 4.0.

  • Added the Booking entity, new in Projectal 4.0.

3.1.1

  • Link requests generated by 'projectal.Entity.create()' and 'projectal.Entity.update()' are now executed in batches. This is enabled by default with the 'batch_linking=True' parameter and can be disabled to execute each link request individually. It is recommended to leave this parameter enabled as this can greatly reduce the number of network requests.

3.1.0

  • Minimum Projectal version is now 3.1.5.

  • Added projectal.Webhook.list_events(). See API doc for details on how to use.

  • Added deleted_at parameter to projectal.Entity.get(). This value should be a UTC timestamp from a webhook delete event.

  • Added projectal.ldap_sync() to initiate a user sync with the LDAP/AD service configured in the Projectal server settings.

  • Enhanced output of projectal.Entity.changes() function when reporting link changes. It no longer dumps the entire before-and-after list with the full content of each linked entity. Now reports three lists: added, updated, removed. Entities within the updated list follow the same old vs new dictionary model for the data attributes within them. E.g:

    resourceList: [
        'added': [],
        'updated': [
            {'uuId': '14eb4c31-0f92-49d1-8b4d-507ab939003e', 'resourceLink': {'utilization': {'old': 0.1, 'new': 0.9}}},
        ],
        'removed': []
    ]
    

    This should result in slimmer logs that are much easier to understand as the changes are clearly indicated.

3.0.2

  • Added projectal.Entity.get_link_definitions(). Exposes entity link definition dictionary. Consumers can inspect which links an Entity knows about and their internal settings. Link definitions that appear here are the links valid for links=[] parameters.

3.0.1

  • Fixed fetching project with links=['task'] not being available.

  • Improved Permission.list(). Now returns a dict with the permission name as key with Permission objects as the value (instead of list of uuIds).

  • Added a way to use the aliasing feature of the API (new in Projectal 3.0). Set projectal.api_alias = 'uuid' to the UUID of a User object and all requests made will be done as that user. Restore this value to None to resume normal operation. (Some rules and limitations apply. See API for more details.)

  • Added complete support for the Tags entity (including linkers).

3.0

Version 3.0 accompanies the release of Projectal 3.0.

Breaking changes:

  • The links parameter on Entity functions now consumes a list of entity names instead of a comma-separated string. For example:

    # Before:
    projectal.Staff.get('<uuid>', links='skill,location')  # No longer valid
    # Now:
    projectal.Staff.get('<uuid>', links=['skill', 'location'])
    
  • The projectal.enums.SkillLevel enum has had all values renamed to match the new values used in Projectal (Junior, Mid, Senior). This includes the properties on Skill entities indicating work time for auto-scheduling (now juniorLevel, midLevel, seniorLevel).

Other changes:

  • Working with entity links has changed in this release. The previous methods are still available and continue to work as before, but there is no need to interact with the projectal.linkers methods yourself anymore.

    You can now modify the list of links within an entity and save the entity directly. The library will automatically determine how the links have been modified and issue the correct linker methods on your behalf. E.g., you can now do:

    staff = projectal.Staff.get('<uuid>', links=['skill'])
    staff['firstName'] = "New name"  # Field update
    staff['skillList'] = [skill1, skill2, skill3]  # Link update
    staff.save()  # Both changes are saved
    
    task = projectal.Task.get('<uuid>', links=['stage'])
    task['stage'] = stage1  # Uses a single object instead of list
    task.save()
    

    See examples/linking.py for a more complete demonstration of linking capabilities and limitations.

  • Linkers (projectal.linkers) can now be given a list of Entities (of one type) to link/unlink/relink in bulk. E.g:

    staff.unlink_skill(skill1)  # Before
    staff.unlink_skill([skill1, skill2, skill3])  # This works now too
    
  • Linkers now strip the payload to only the required fields instead of passing on the entire Entity object. This cuts down on network traffic significantly.

  • Linkers now also work in reverse. The Projectal server currently only supports linking entities in one direction (e.g., Company to Staff), which often means writing something like:

    staff.link_location(location)
    company.link_staff(staff)
    

    The change in direction is not very intuitive and would require you to constantly verify which direction is the one available to you in the documentation.

    Reverse linkers hide this from you and figure out the direction of the relationship for you behind the scenes. So now this is possible, even though the API doesn't strictly support it:

    staff.link_location(location)
    staff.link_company(company)
    

    Caveat: the documentation for Staff will not list Company links. You will still have to look up the Company documentation for the link description.

  • Requesting entity links with the links= parameter will now always ensure the link field (e.g., taskList) exists in the result, even if there are no links. The server may not always return a value, but we can use a default value ([] for lists, None for dicts).

  • Added a Permission entity to correctly type Permissions in responses.

  • Added a Tag entity, new in Projectal 3.0.

  • Added links parameter to Company.get_primary_company()

  • Department.tree(): now consumes a holder Entity object instead of a uuId.

  • Department.tree(): added generic_staff parameter, new in Projectal 3.0.

  • Don't break on trailing slash in Projectal URL

  • When creating tasks, populate the projectRef and parent fields in the returned Task object.

  • Added convenience functions for matching on fields where you only want one result (e.g match_one()) which return the first match found.

  • Update the entity history() method for Projectal 3.0. Some new parameters allow you to restrict the history to a particular range or to get only the changes for a webhook timestamp.

  • Entity objects can call .history() on themselves.

  • The library now keeps a reference to the User account that is currently logged in and using the API: projectal.api_auth_details.

Known issues:

  • You cannot save changes to Notes or Calendars via their holding entity. You must save the changes on the Note or Calendar directly. To illustrate:
    staff = projectal.Staff.get(<uuid>, links=['calendar'])
    calendar = staff['calendarList'][0]
    calendar['name'] = 'Calendar 2'
    
    # Cannot do this - will not pick up the changes
    staff.save()
    
    # You must do this for now
    calendar.save()
    
    This will be resolved in a future release.
  • When creating Notes, the created and modified values may differ by 1ms in the object you have a reference to compared to what is actually stored in the database.

  • Duration calculation is not precise yet (mentioned in 2.1.0)

2.1.0

Breaking changes:

  • Getting location calendar is now done on an instance instead of class. So projectal.Location.calendar(uuid) is now simply location.calendar()
  • The CompanyType.Master enum has been replaced with CompanyType.Primary. This was a leftover reference to the Master Company which was renamed in Projectal several versions ago.

Other changes:

  • Date conversion functions return None when given None or empty string
  • Added Task.reset_duration() as a basic duration calculator for tasks. This is a work-in-progress and will be gradually improved. The duration calculator takes into consideration the location to remove non-work days from the estimate of working duration. It currently does not work for the time component or isWorking=True exceptions.
  • Change detection in Entity.changes() now excludes cases where the server has no value and the new value is None. Saving this change has no effect and would always detect a change until a non-None value is set, which is noisy and generates more network activity.

2.0.3

  • Better support for calendars.
    • Distinguish between calendar containers ("Calendar") and the calendar items within them ("CalendarItem").
    • Allow CalendarItems to be saved directly. E.G item.save()
  • Fix 'holder' parameter in contact/staff/location/task_template not permitting object type. Now consumes uuId or object to match rest of the library.
  • Entity.changes() has been extended with an old=True flag. When this flag is true, the set of changes will now return both the original and the new values. E.g.
task.changes()
# {'name': 'current'}
task.changes(old=True)
# {'name': {'old': 'original', 'new': 'current'}}
  • Fixed entity link cache causing errors when deleting a link from an entity which has not been fetched with links (deleting from empty list).

2.0.2

  • Fixed updating Webhook entities

2.0.1

  • Fixed application ID not being used correctly.

2.0.0

  • Version 2.0 accompanies the release of Projectal 2.0. There are no major changes since the previous release.
  • Expose Entity.changes() function. It returns a list of fields on an entity that have changed since fetching it. These are the changes that will be sent over to the server when an update request is made.
  • Added missing 'packaging' dependency to requirements.

1.2.0

Breaking changes:

  • Renamed request_timestamp to response_timestamp to better reflect its purpose.
  • Automatic timestamp conversion into dates (introduced in 1.1.0) has been reverted. All date fields returned from the server remain as UTC timestamps.

    The reason is that date fields on tasks contain a time component and converting them into date strings was erasing the time, resulting in a value that does not match the database.

    Note: the server supports setting date fields using a date string like 2022-04-05. You may use this if you prefer but the server will always return a timestamp.

    Note: we provide utility functions for easily converting dates from/to timestamps expected by the Projectal server. See: projectal.date_from_timestamp(),projectal.timestamp_from_date(), and projectal.timestamp_from_datetime().

Other changes:

  • Implement request chunking - for methods that consume a list of entities, we now automatically batch them up into multiple requests to prevent timeouts on really large request. Values are configurable through projectal.chunk_size_read and projectal.chunk_size_write. Default values: Read: 1000 items. Write: 200 items.
  • Added profile get/set functions on entities for easier use. Now you only need to supply the key and the data. E.g:
key = 'hr_connector'
data = {'staff_source': 'company_z'}
task.profile_set(key, data)
  • Entity link methods now automatically update the entity's cached list of links. E.g: a task fetched with staff links will have task['staffList'] = [Staff1,Staff2]. Before, doing a task.link_staff(staff) did not modify the list to reflect the addition. Now, it will turn into [Staff1,Staff2,Staff3]. The same applies for update and delete.

    This allows you to modify links and continue working with that object without having to fetch it again to obtain the most recent link data. Be aware that if you acquire the object without requesting the link data as well (e.g: projectal.Task.get(id, links='STAFF')), these lists will not accurately reflect what's in the database, only the changes made while the object is held.

  • Support new applicationId property on login. Set with: projectal.api_application_id. The application ID is sent back to you in webhooks so you know which application was the source of the event (and you can choose to filter them accordingly).

  • Added Entity.set_readonly() to allow setting values on entities that will not be sent over to the server when updating/saving the entity.

    The main use case for this is to populate cached entities which you have just created with values you already know about. This is mainly a workaround for the limitation of the server not sending the full object back after creating it, resulting in the client needing to fetch the object in full again if it needs some of the fields set by the server after creation.

    Additionally, some read-only fields will generate an error on the server if included in the update request. This method lets you set these values on newly created objects without triggering this error.

    A common example is setting the projectRef of a task you just created.

1.1.1

  • Add support for 'profiles' API. Profiles are a type of key-value storage that target any entity. Not currently documented.
  • Fix handling error message parsing in ProjectalException for batch create operation
  • Add Task.update_order() to set task order
  • Return empty list when GETing empty list instead of failing (no request to server)
  • Expose the timestamp returned by requests that modify the database. Use projectal.request_timestamp to get the value of the most recent request (None if no timestamp in response)

1.1.0

  • Minimum Projectal version is now 1.9.4.

Breaking changes:

  • Entity list() now returns a list of UUIDs instead of full objects. You may provide an expand parameter to restore the previous behavior: Entity.list(expand=True). This change is made for performance reasons where you may have thousands of tasks and getting them all may time out. For those cases, we suggest writing a query to filter down to only the tasks and fields you need.
  • Company.get_master_company() has been renamed to Company.get_primary_company() to match the server.
  • The following date fields are converted into date strings upon fetch: startTime, closeTime, scheduleStart, scheduleFinish. These fields are added or updated using date strings (like 2022-03-02), but the server returns timestamps (e.g: 1646006400000) upon fetch, which is confusing. This change ensures they are always date strings for consistency.

Other changes:

  • When updating an entity, only the fields that have changed are sent to the server. When updating a list of entities, unmodified entities are not sent to the server at all. This dramatically reduces the payload size and should speed things up.
  • When fetching entities, entity links are now typed as well. E.g. project['rebateList'] contains a list of Rebate instead of dict.
  • Added date_from_timestamp() and timestamp_from_date() functions to help with converting to/from dates and Projectal timestamps.
  • Entity history now uses desc by default (index 0 is newest)
  • Added Project.tasks() to list all task UUIDs within a project.

1.0.3

  • Fix another case of automatic JWT refresh not working

1.0.2

  • Entity instances can save() or delete() on themselves
  • Fix broken dict methods (get() and update()) when called from Entity instances
  • Fix automatic JWT refresh only working in some cases

1.0.1

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