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