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