projectal API documentation

# 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 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

View Source

      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())

api_base = None
api_username = None
api_password = None
api_application_id = None
api_auth_details = None
api_alias = None
cookies = None
chunk_size_read = 1000
chunk_size_write = 200
response_timestamp = None
MIN_PROJECTAL_VERSION = '5.3.0'