goalsmanagement.goalcard.start

Scope: goalsmanagement

Кто может вызывать: Администратор портала или администратор модуля — как кнопка «Запустить» в разделе «Контроль процессов». Подробнее: Права доступа

Запустить процесс постановки целей для подразделения. Метод выполняет тот же путь, что и кнопка «Запустить» в разделе «Контроль процессов»: создаёт запуск процесса и карточки целей сотрудников отдела. Парный метод — goalsmanagement.goalcard.stop.

Пока процесс подразделения не запущен, карточки отдела доступны только для просмотра: goalsmanagement.goalcard.create и goalsmanagement.goalcard.approve возвращают VALIDATION_ERROR. Состояние запуска показывает поле started в goalsmanagement.process.getInfo.

HTTP: POST

Побочные эффекты: изменяет данные:

  • создаёт или обновляет запуск процесса подразделения (runId) со статусом «запущен» (1); при включённых параллельных процессах и дате старта в будущем — «отложенный» (D);
  • создаёт карточку целей в статусе «Черновик» каждому активному сотруднику отдела с учётом исключений привязки (excludeEmployee, excludeHead, выборочное участие);
  • первый запуск / параллельные процессы: сотрудник, у которого уже есть активная карточка этого runId, новую не получает (карточки других запусков не трогаются);
  • перезапуск после stop (и при выключенных параллельных процессах): предыдущие карточки отдела деактивируются; в новую черновую карточку переносятся собственные цели из утверждённой карточки; каскад «сверху» (из другого подразделения того же совместного запуска) переносится на карточку руководителя перезапущенного отдела; каскад от руководителя этого отдела на подчинённых в новой карте подчинённых не показывается, пока руководитель снова не утвердит карту;
  • если у получателя каскада уже другой runId (отделы перезапускали порознь), связь каскада при перезапуске карты каскадирующего снимается — повторное утверждение не создаст цель в чужом запуске;
  • отправляет каждому сотруднику, получившему карточку, уведомление о заполнении целей; для отложенного запуска уведомления придут в день старта;
  • при выключенных параллельных процессах отмечает подразделение как запущенное (statusProcess = "1", даты startProcess / endProcess).

Повторный вызов для уже запущенного процесса ничего не меняет и возвращает текущее состояние с alreadyStarted: true. Исключение: если в отделе не осталось активных сотрудников, проверка сотрудников срабатывает раньше проверки запуска, и повторный вызов вернёт VALIDATION_ERROR, а не alreadyStarted. Состояние такого отдела смотрите в goalsmanagement.process.getInfo.

Тот же путь кода, что у кнопки «Запустить» в «Контроле процессов»: отдельной REST-логики перезапуска нет — сценарий «остановить → запустить» через goalsmanagement.goalcard.stop и этот метод.

Параметры метода

Параметр Тип Обяз. Описание
departmentId int да ID отдела. Процесс должен быть привязан к отделу методом goalsmanagement.process.saveBinding
processId int нет Только при включённых параллельных процессах: какой процесс запустить. 0 или не передан — процесс из привязки отдела. При выключенных параллельных процессах игнорируется
runId string нет Только при включённых параллельных процессах: конкретный запуск (остановленный периодический). Предстоящий запуск (U) метод не активирует — его запустит агент в дату начала периода

Возвращаемые данные

Ответ в конверте модуля: result.result — состояние запуска; result.error. Ключи total/next для не-list методов могут отсутствовать в сериализации, если не переданы.

Поле Тип Описание
departmentId int ID отдела
processId int ID запущенного процесса
runId string ID запуска процесса на отделе
status string Статус запуска: 1 — запущен, D — отложен до даты старта, U — предстоящий период
started bool true — карточки этого запуска можно заполнять и согласовывать: goalcard.create и goalcard.approve не отклонят их из-за состояния процесса
alreadyStarted bool true — процесс уже был запущен до вызова, данные не менялись
dateStart string Дата начала процесса, ДД.ММ.ГГГГ
dateEnd string Дата окончания процесса, ДД.ММ.ГГГГ
cards array Активные карточки целей этого запуска: id — ID карточки, employeeId — ID сотрудника

Обработка ошибок

Справочник кодов: error-codes.md.

Код Описание
UNAUTHORIZED Пользователь не авторизован
ACCESS_DENIED Вызывающий не администратор портала и не администратор модуля
VALIDATION_ERROR Не передан departmentId; к отделу не привязан процесс; в отделе нет активных сотрудников; до конца периода осталось меньше минимального числа дней (настройка модуля); запуск runId не найден или не активен. Текст ошибки — как в интерфейсе
INTERNAL_ERROR Внутренняя ошибка сервера

Пример запроса (POST)

curl -X POST "https://{портал}/rest/{user_id}/{webhook_code}/goalsmanagement.goalcard.start.json" \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          --data '{
          "departmentId": 12
        }'

Пример ответа

{
          "result": {
            "result": {
              "departmentId": 12,
              "processId": 42,
              "runId": "run_6f1c2a9e4b7d",
              "status": "1",
              "started": true,
              "alreadyStarted": false,
              "dateStart": "14.10.2026",
              "dateEnd": "13.10.2027",
              "cards": [
                { "id": 501, "employeeId": 15 },
                { "id": 502, "employeeId": 16 }
              ]
            },
            "error": null
          }
        }

См. также

Предыдущая
goalsmanagement.goalcard.setDelegate
Следующая
goalsmanagement.goalcard.status.list