API для структуры проекта

Обновлено: 06.10.2026

НазначениеНазначение

Для работы с иерархической структурой работ (ИСР) проекта используется сущность ProjectTask и набор OData ProjectTasks. Это элементы плана проекта: работы, группы работ и вехи.

Для собственных интеграций рекомендуется использовать обычные операции OData: читать структуру, добавлять задачи, обновлять их описательные свойства и удалять задачи с учётом ограничений системы.

Календарно-сетевым планированием управляет Schedule Engine. Он рассчитывает сроки с учётом длительности, зависимостей, ограничений, иерархии и календарей. Для изменения входных данных планирования предусмотрены отдельные команды.

Что можно делать через CRUD ODataЧто можно делать через CRUD OData

В примерах <taskId>, <projectId> и <parentTaskId> обозначают реальные GUID соответствующих объектов.

Свойства существующей задачиСвойства существующей задачи

Через PATCH можно обновлять, в частности:

• name и description — название и описание;
• allowTimeEntry — разрешение ввода времени;
• categoryId — категорию;
• lookupValue1Id, lookupValue2Id и другие доступные дополнительные свойства — с учётом их типов и настройки;
• leadTaskId и number — родителя и порядок задачи в допустимой структуре проекта.

Это примеры доступных свойств, а не разрешение записывать любое поле, полученное при чтении. Системные и вычисляемые свойства, например structNumber, indent и fullPath, формируются системой.

Изменение родителя или порядка запускает нормализацию структуры и пересчёт плана. Простое изменение названия или описания не является командой перепланирования.

Для технической корневой задачи название, описание и разрешение ввода времени синхронизируются с проектом: их следует менять через свойства проекта. Для наследуемых проектов и защищённых версий действуют дополнительные ограничения. Корневую задачу нельзя удалить.

Чтение задач проектаЧтение задач проекта

GET https://api.timetta.com/odata/ProjectTasks?$filter=projectId eq <projectId>&$select=id,name,leadTaskId,number,structNumber,startDate,endDate,duration

Значения startDate и endDate в результате показывают рассчитанные сроки. Возможность прочитать поле не означает, что его можно изменить через PATCH.

Добавление задачиДобавление задачи

POST https://api.timetta.com/odata/ProjectTasks
Content-Type: application/json

{
  "projectId": "<projectId>",
  "leadTaskId": "<parentTaskId>",
  "name": "Подготовить исходные данные",
  "description": "Собрать материалы для выполнения работ",
  "allowTimeEntry": true
}

Перед отправкой замените значения в угловых скобках на GUID. Родитель должен принадлежать выбранному плану. Для добавления задачи первого уровня укажите корневую задачу проекта.

Ограничение на изменение полей планирования относится к обновлению существующей задачи. Создание допускает начальные значения полей, разрешённые моделью и бизнес-правилами, но не гарантирует сохранение произвольного интервала дат. Новая обычная задача по умолчанию получает ограничение ASAP, после чего движок определяет её допустимые сроки.

Обновление обычных свойствОбновление обычных свойств

PATCH https://api.timetta.com/odata/ProjectTasks(<taskId>)
Content-Type: application/json

{
  "name": "Подготовить и согласовать исходные данные",
  "lookupValue1Id": "55256e63-ea27-4aaf-a744-70d29f6539d0",
  "lookupValue2Id": "a725f7cb-35e2-43cc-ab9d-fc5fec5e927d",
  "allowTimeEntry": false
}

Идентификаторы значений справочников в примере необходимо заменить на доступные в вашей системе. Логические значения передаются без кавычек: false, а не "false".

Передавайте только изменяемые свойства. Не отправляйте обратно весь объект из GET: он содержит рассчитанные и системные поля.

Что нельзя менять обычным обновлениемЧто нельзя менять обычным обновлением

У существующей задачи через CRUD нельзя менять следующие поля планирования:

Ограничение действует как при автоматическом, так и при ручном планировании проекта. Переключение isAutoPlanning не разрешает прямую запись дат: этот флаг влияет на ресурсное планирование, а правила календарных ограничений и зависимостей остаются общими.

Например, попытка изменить даты через PATCH:

{
  "startDate": "2026-10-30",
  "endDate": "2026-11-23"
}

приведёт к ошибке TmtArgumentException:

Use an explicit scheduling command to change dates, duration, type, milestone, constraints, or dependencies. Argument name: StartDate.

В текущей реализации имя аргумента StartDate используется для всей этой проверки. Поэтому сообщение может появиться и при изменении другого поля из таблицы.

Если интеграция должна обновить только справочники, описание или разрешение ввода времени, удалите поля планирования из запроса. Если требуется изменить сам календарный план, используйте интерфейс планирования Timetta либо учитывайте ограничения использования команд Schedule Engine.

Как Schedule Engine определяет срокиКак Schedule Engine определяет сроки

Даты задачи — результат расчёта. Движок учитывает начало проекта, рабочие календари, длительность, зависимости и ограничения задачи и её родительских групп.

Поддерживаются два ограничения:

• ASAP — разместить задачу как можно раньше с учётом всех условий;
• SNET — начать не раньше указанной даты. Это нижняя граница начала, а не закрепление точной даты.

Более сильная зависимость или нерабочий день могут сдвинуть задачу позже запрошенного срока. Даты и длительность группы рассчитываются по её подзадачам; прямое изменение её длительности или границ не поддерживается.

Команда меняет свои входные данные и запускает общий пересчёт. Он может затронуть другие задачи и группы. Неизменяемые командой зависимости и явные ограничения сохраняются.

Команды планированияКоманды планирования

Ниже приведён обзор текущего API задач Schedule Engine. Он помогает понять назначение операций и не является гарантией неизменности их контракта.

Команды выполняются HTTP-методом POST. Для команды конкретной задачи используется форма:

POST /odata/ProjectTasks(<taskId>)/<Command>

Команды коллекции AddTask и RemoveAssignments вызываются без идентификатора задачи в URL:

POST /odata/ProjectTasks/AddTask
POST /odata/ProjectTasks/RemoveAssignments

Во всех перечисленных ниже командах передаётся expectedRevision — ожидаемая ревизия выбранного плана. В таблицах указаны остальные основные параметры.

Сроки, длительность и ограниченияСроки, длительность и ограничения

Для вехи изменение начала или окончания работает как перенос. Снятие SNET может сдвинуть задачу и её преемников раньше.

Трудозатраты и назначенияТрудозатраты и назначения

ЗависимостиЗависимости

Поддерживаются связи «окончание — начало» (FS), «начало — начало» (SS), «окончание — окончание» (FF) и «начало — окончание» (SF). При пересчёте учитываются все действующие связи. Удаление связи может освободить задачу для более раннего начала.

Структура проектаСтруктура проекта

Наличие этих команд не отменяет CRUD для создания, удаления и допустимых изменений структуры. Для обычной интеграции предпочтителен CRUD.

Что должен учитывать клиент командного APIЧто должен учитывать клиент командного API

Если интеграция всё же использует команды планирования, ей недостаточно отправить новые значения и сохранить ответ одной задачи.

1. Актуальное состояние и ревизия. Получайте снимок выбранного плана через GetPlanSnapshot проекта или версии. Используйте его revision как expectedRevision следующей команды. Это ревизия всего плана, а не rowVersion отдельной задачи.
2. Конфликты изменений. При конфликте ревизий перечитайте снимок и заново оцените операцию на актуальном состоянии.
3. Изменения всего плана. Обрабатывайте возвращённые изменения и новую ревизию. В зависимости от команды результат содержит projectPlanChanges либо сам является конвертом изменений плана. Изменения могут затронуть несколько задач, назначения и ресурсный план.
4. Предупреждения и ошибки. Учитывайте результат операции, ошибки валидации и предупреждения. Например, requestedStartAdjusted означает, что рассчитанное начало отличается от запрошенного, а plannedFinishExceeded — превышение планового окончания проекта.
5. Изменения контракта. Проверяйте совместимость интеграции при обновлениях Timetta; не полагайтесь на неизменность параметров и формата ответа команд.

Помимо команд задач, контур Schedule Engine включает операции ресурсного плана, изменения календарей и режима планирования, а также Undo/Redo. Отмена восстанавливает сохранённое состояние плана: обратный перенос даты не равнозначен Undo.