Добавить запись в отчёт — документация 0.4

orch.reportAdd · Оркестратор

Записывает строку в отчёт оркестратора (номер, сумма, дата, статус…). Значения проверяются по полям отчёта; запись помнит задание и робота

Записывает строку в отчёт оркестратора — бизнес-результат работы робота: платёж, заявку, документ с номером, суммой и статусом. Запись помнит задание и робота, которые её создали; из записей строятся отчёты, графики и SQL-запросы в панели. Значения проверяются по полям отчёта.

Действие работает в задании оркестратора и при запуске из студии, подключённой к оркестратору: тогда оно обращается к „области для отладки“, выбранной в «Оркестратор» → «Подключение…», и работает с настоящими данными этой области.

Свойства #

Свойство	Имя в файле	Значение	Обязательное	По умолчанию	Описание
Отчёт	`report`	текст	да	—	Ключ отчёта в оркестраторе (латиница), например payments — указан на странице отчёта в панели
Значения полей	`values`	выражение	да	—	Объект «ключ поля: значение», например { number: row['Номер'], amount: row['Сумма'], status: 'Новый' }
Режим	`mode`	выбор из списка	нет	`insert`	insert — новая запись; upsert — по ключу записи отчёта: если такая запись уже есть, она обновляется, иначе добавляется. Значения: `insert`, `upsert`.

Результат #

Значение выхода сохраняется в переменную, выбранную для него в свойствах шага (раздел выходов).

Выход	Имя в файле
Id записи	`recordId`

Как работает #

Отчёт (report) — ключ отчёта латиницей (payments), его показывает страница отчёта в панели («Отчёты»). Отчёт ищется в рабочей области задания.
Значения полей (values) — объект „ключ поля: значение“: { number: row['Номер'], amount: row['Сумма'], status: 'Новый' }. Даты — '16.11.2026' или ISO.
Режим (mode):
- insert — всегда новая запись;
- upsert — если у отчёта задан ключ записи (например, номер платежа) и такая запись уже есть, она обновляется, иначе добавляется. Повторный запуск процесса не создаёт дублей.
Выход Id записи — для orch.reportUpdate.
Много строк сразу быстрее записать orch.reportAddMany.

Ошибки #

Код	Причина и что делать
`InvalidArgument`	Не указан ключ отчёта; значения — не объект
`ReportNotFound`	Нет отчёта с таким ключом в области — проверьте ключ на странице отчёта
`ReportValidation`	Значения не подходят к полям отчёта: нет такого поля, не число в числовом поле, неверная дата, не заполнено обязательное поле. Это бизнес-ошибка — задание с ней не повторяется автоматически. Текст называет поле и значение
`ReportsUnavailable`	База отчётов недоступна — системная ошибка, задание можно повторить
`OrchestratorUnavailable`	Процесс запущен без оркестратора (студия не подключена) или нет связи с сервером после 4 попыток (паузы 1, 2 и 4 с). Проверьте подключение студии или что агент робота на связи
`AccessDenied`	Не хватает прав в рабочей области или задание уже завершено

Пример #

{
  "type": "orch.reportAdd",
  "props": {
    "report": "payments",
    "values": "{ number: row['Номер'], amount: row['Сумма'], paid_on: row['Дата'], status: 'Новый' }",
    "mode": "upsert"
  },
  "out": { "recordId": "recordId" }
}