API: Пример работы с таймшитом
Создание таймшита
Таймшиты создаются автоматически при выполнении ряда запросов.
Получение Id таймшита на дату для пользователя:
[GET] https://api.workpoint.app/odata/TimeSheets/WP.GetIdForPeriod(date=2021-03-22,userId=fdcc3910-8fe0-400b-9805-51efd6ca504d) Response: { "value": "cd935d85-09ec-48fc-8103-7c0baa3afebc" }
Функция WP.GetIdForPeriod в коллекции TimeSheets принимает два параметра: date и userId. Если на указанную дату таймшит еще не создан, то он создается (на период в соответствии с настройками периодов таймшитов). Возвращается Id таймшита.
Получение Id следующего/предыдущего таймшита:
[GET] https://api.workpoint.app/odata/TimeSheets(cd935d85-09ec-48fc-8103-7c0baa3afebc)/WP.GetNextTimeSheetId Response: { "value": "362acda4-dfd9-4429-9290-78a97f0e7e0f" }
Функция WP.GetNextTimeSheetId и WP.GetPreviousTimeSheetId в сущности TimeSheet не требует параметров. Если следующий/предыдущий таймшит еще не создан, то он создается (на период в соответствии с настройками периодов таймшитов). Возвращается Id таймшита.
Получение таймшита
Получить таймшит или коллекцию таймшитов можно стандартными OData запросами.
Обратите внимание на вложенный expand — в данном примере сразу запрашивается коллекция строк и «ячеек» строк. Так же сразу можно «раскрыть» любые связанные сущности, например получить имя или код проекта по строкам:
[GET] https://api.workpoint.app/odata/TimeSheets(97b5c8bc-c411-4518-8927-953fe3e7a79c)?$expand=TimeSheetLines($expand=TimeAllocations) Response: { "rowVersion": "AAAAAAAADMQ=", // Версия "id": "97b5c8bc-c411-4518-8927-953fe3e7a79c", // ИД "created": "2021-02-22T08:55:46.6233881+03:00", // Дата создания "isActive": true, // Системный признак "dueDate": "2021-03-02", // Срок отправки "dateFrom": "2021-02-22", // Начало периода "dateTo": "2021-02-28", // Окончание периода "approvalStatusId": "0aefb600-42fb-4aa5-991c-d70dc7ac7b27", // ИД статуса согласования "submitted": null, // Дата отправки на согласования "approved": null, // Дата согласования "userId": "fdcc3910-8fe0-400b-9805-51efd6ca504d", // ИД пользователя "departmentId": "9468cd5c-ea04-4adb-a1d7-94b6b910ab2e", // ИД подразделения (в которое на момент создания ТШ входил пользователь) "approvalInstanceId": null, // ИД текущего процесса согласования "templateId": "e590d1c1-50e8-467b-a9b5-787cca869446", // ИД шаблона таймшита "name": "Иван Агафонов 22.02.2021-28.02.2021", // Наименование для отображения в списках "billableDuration": 3.00000, // Сумма оплачиваемых часов в таймшите "nonBillableDuration": 24.00000, // Сумма неоплачиваемых часов в таймшите "editAllowed": true, // Признак разрешения на редактирования (пользователем, который выполнил запрос) "deleteAllowed": true, // Признак разрешения на удаление "submitAllowed": true, // Признак разрешения на отправку на согласование "forceSubmitAllowed": true, // Признак разрешения на принудительную отправку на согласование (минуя правила) "reopenAllowed": false, // Признак разрешения на переоткрытие "executeAllowed": false, // Признак разрешения на согласование/отклонение "forceExecuteAllowed": false, // Признак разрешения на принудительное согласование/отклонение "schedule": [ // Коллекция дней с часами по расписанию для автора пользователя { "date": "2021-02-22", "duration": 8.00 }, *** ], "timeSheetLines": [ // Коллекция строк таймшита { "id": "172ab42a-bacd-459a-bfea-56056c8f9272", "created": "2021-02-22T09:13:55.3098618+03:00", "isActive": true, "rowVersion": "AAAAAAAADMU=", "date": null, "activityId": null, // ИД вида работ "billingRateId": null, // ИД тарифа "projectId": "6ce1f7e7-b88c-4106-8833-d4ac30d6ba15", // ИД проекта "projectTaskId": "87ddeadc-2793-4b79-a5aa-6774cd6e6e81", // ИД задачи "orderNumber": 0, // Порядковый номер // + CUSTOM FIELDS "timeAllocations": [ // Коллекция "ячеек" строки { "id": "0164f849-611e-4f10-a813-b4a39172aecd", "created": "2021-02-22T09:14:00.9419888+03:00", "isActive": true "date": "2021-02-22", // Дата ячейки "duration": 3.00000, // Длительность работ в часах "comments": "", // Текстовый комментарий "invoiceLineId": null, // ИД линии счета "timeOffRequestId": null, // ИД заявки на отсутствие // + CUSTOM FIELDS } ] } ] }
Обновление таймшита
Для обновления таймшита рекомендуется создавать отдельный объект, а не модифицировать полученный (поскольку требуется передавать только сохраняемые поля).
[PUT] https://api.workpoint.app/odata/TimeSheets(97b5c8bc-c411-4518-8927-953fe3e7a79c) Body: { "id": "97b5c8bc-c411-4518-8927-953fe3e7a79c", // ИД существующего ТШ "name": "Иван Агафонов 22.02.2021-28.02.2021", // Произвольная срока "rowVersion": "AAAAAAAADMI=", // Актуальная версия "timeSheetLines": [ // Массив строк таймшита { "id": "172ab42a-bacd-459a-bfea-56056c8f9272", "timeAllocations": [ // Массив ячеек по строке { "id": "0164f849-611e-4f10-a813-b4a39172aecd", "duration": 3.25, // Длительность в часах "comments": "", // Текстовый кооменатрий "date": "2021-02-22" // Дата } ], "projectId": "6ce1f7e7-b88c-4106-8833-d4ac30d6ba15", // ИД проекта "activityId": "8c0d731b-fc11-4ac1-ba23-566f8b33f848", // ИД Вида работ "projectTaskId": "87ddeadc-2793-4b79-a5aa-6774cd6e6e81", // ИД задачи проекта "orderNumber": 0 // Порядковый номер строки } ] }<br>
Объект TimeSheet:
- id — идентификатор (GUID).
- name — строка.
- rowVersion — актуальная версия таймшита. Если будет отличаться от сохраненной — будет исключение, после обновления автоматически генерируется новая версия.
- timeSheetLines — массив строк, в примере одна строка.
Объект TimeSheetLine:
- id — идентификатор (GUID).
- projectId, projectTaskId, activityId — идентификаторы выбранных аналитик (проекта, задачи и вида работ). Обратите внимание, что передается не объект (project, activity...), а id объекта (projectId, activityId...).
- orderNumber: порядковый номер строки. Нумерация должна быть от 0 и должна быть строго последовательной. Это проверяется сервером и если нумерация нарушена — будет исключение.
- timeAllocations — коллекция «ячеек» строки.
Объект TimeAllocation:
- id — идентификатор (GUID).
- date — дата ячейки.
- comments — текстовый комментарий
- duration — длительность работ в часах.
Cвязанныt коллекциb, в данном случае timeSheetLines и timeAllocations, при обновлении таймшита будут обновлены автоматически, т.е. можно убрать из массивов некоторые объекты, добавить новые, обновить существующие и сервер сам обновит коллекции в БД оптимальным способом.