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, при обновлении таймшита будут обновлены автоматически, т.е. можно убрать из массивов некоторые объекты, добавить новые, обновить существующие и сервер сам обновит коллекции в БД оптимальным способом.