Документация

Синхронизация команд и дежурств

Версия v2.5.1 · Обновлено

Синхронизация команд и дежурств#

Синхронизация переносит в IncidentRelay команды, пользователей и расписания из внешней системы. IR сам обращается к её API через заданный интервал. Изменения из IR обратно не отправляются.

Настройки одного подключения называются источником: адрес API, авторизация, запросы, соответствие полей и правила обновления. Для каждого источника выбирается одна группа IR.

Что подготовить#

Что нужноДля чего
Учётная запись администратораГлобальный администратор выбирает любую активную группу; администратор группы — только группы, которыми управляет.
Адрес внешнего APIНапример, https://org-service.example.com. Это система с командами и дежурствами.
Токен внешнего APIДля org-service — PAT с правами чтения команд, сотрудников, расписаний и текущих дежурных.
Работающий scheduler IRОн выполняет предпросмотр, применение и периодические обновления.
Сетевой доступ из IRWeb и scheduler должны разрешать имя API, подключаться к нему и доверять его сертификату.

При обновлении приложения сначала выполните python manage.py migrate, затем запустите обновлённые процессы web и scheduler. Подробнее — планировщик и установка.

Не путайте два токена. В настройках источника нужен токен внешнего API. Персональный токен IR нужен только для скрипта, который настраивает IR через его API. Для настройки в интерфейсе достаточно своей сессии в IR.

Первый запуск через интерфейс#

1. Добавьте источник#

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

В форме уже есть готовые запросы и маппинг для org-service. Для этой системы их можно оставить и заполнить только своё подключение. Для другого API используйте разбор запросов и маппинга ниже.

2. Заполните подключение#

ПолеПример и пояснение
НазваниеДежурства платформы — имя, по которому источник будет виден в IR.
Группа назначенияГруппа IR, в которой должны появиться команды. После создания источника её изменить нельзя.
Базовый адрес APIhttps://org-service.example.com. Пути /api/v1/... уже находятся в операциях.
Доступ к сетиДля публичного API — «Только публичные сети». Для внутреннего — «Разрешённые сети сервера», после настройки серверного allowlist.
Не проверять TLS-сертификатПо умолчанию выключено. Включите для подключения к API с самоподписанным сертификатом без настройки доверия CA. Отключает проверку сертификата и имени сервера только для этого источника.
Заголовки авторизацииJSON с заголовками, которые ожидает внешняя система.

Пример заголовков org-service:

{
  "Authorization": "PAT замените-на-ваш-PAT"
}

Для API с Bearer-авторизацией значение будет Bearer ваш-токен. Выбирайте формат, который требует внешняя система.

Заголовки сохраняются зашифрованными. После сохранения поле очищается: сервер не возвращает секрет в браузер. При редактировании пустое поле сохраняет прежние заголовки, новый JSON заменяет их целиком, а {} удаляет. Не помещайте токены в URL или обычные поля маппинга.

3. Сохраните начальные настройки#

Для первого запуска можно оставить значения по умолчанию:

  • Полная синхронизация — 3600 секунд, раз в час.
  • Обновление текущего дежурного — 60 секунд.
  • Горизонт расписания — 2 месяца, текущий и следующий.
  • Локальное редактирование, управление найденными командами и удаление исчезнувших объектов — выключены.
  • Источник состава и ролей — API синхронизации.

Нажмите Сохранить настройки внизу окна. Окно останется открытым. Сохранение создаёт конфигурацию подключения; команды и люди появятся после применения предпросмотра.

4. Проверьте ответ API#

Нажмите Получить структуру ответа. IR запросит первую страницу каталога команд и покажет названия и типы полей, например:

{
  "teams": [{"enrolledScopeUuid": "str", "name": "str"}],
  "nextPageToken": "str"
}

str означает строку, а не реальное значение поля. Эта проверка помогает проверить адрес и авторизацию и выбрать пути для маппинга. Она проверяет только каталог команд; карточки, профили и смены проверяются при предпросмотре.

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

5. Получите предпросмотр и сопоставьте команды#

Нажмите Предпросмотр изменений. Задание выполняет scheduler; окно обновит результат после завершения. Его можно закрыть — задание продолжится. Повторное нажатие Настроить загрузит актуальное состояние.

Действие в таблицеЧто произойдёт при применении
createСоздастся пользователь, команда, членство, ротация или смена.
updateИзменятся перечисленные поля объекта.
skipНайденная команда будет пропущена: управление существующими командами выключено.
deleteИсчезнувший управляемый объект будет удалён либо его членство отключено.

Предпросмотр сохраняет план, но ещё не меняет команды, людей и расписания. Проверьте состав и будущие изменения, особенно строки delete.

После получения каталога в разделе маппинга появятся списки для сопоставления внешних команд с командами выбранной группы IR. Без явного выбора IR ищет единственное точное совпадение имени; если его нет, создаёт команду. Несколько одинаковых имён требуют ручного выбора. Для обновления найденной команды также включите Управлять найденными командами.

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

6. Примените и включите обновление#

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

После успешного применения:

  • Проверьте команды и ротации в соответствующих разделах IR.
  • В настройках источника включите Включить периодическую синхронизацию.
  • Нажмите Сохранить настройки.

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

Как выбрать правила обновления#

НастройкаВыключенаВключена
Разрешить локальное редактированиеИмпортированные объекты защищены от ручного изменения.Их можно менять в IR; следующий импорт перезапишет совпадающие импортируемые поля.
Управлять найденными командамиРанее существовавшие команды пропускаются.Источник может обновлять сопоставленные команды. Команду другого источника присвоить нельзя.
Удалять исчезнувшие управляемые объектыОбъекты, которые перестали приходить, остаются в IR.После полной успешной загрузки удаляются только объекты, которыми управляет источник.
Включить периодическую синхронизациюАвтоматические обновления остановлены.Полный импорт и обновление текущих дежурных выполняются по расписанию.

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

Команды и ротации удаляются мягким удалением IR. Удаление смен ограничено успешно загруженным периодом. При уходе человека из источника отключаются управляемые членства; глобальная учётная запись и OIDC identity сохраняются. При ошибке запроса прежние данные не удаляются.

ИнтервалЧто обновляетЗначения
Полная синхронизацияКоманды, профили, членства, календарные смены3600 — раз в час, 600 — раз в 10 минут. Диапазон: 60–604800 секунд.
Обновление дежурногоФактически дежурящего человека по операции current60 — раз в минуту. Диапазон: 10–3600 секунд.
Горизонт расписанияКалендарные месяцы, включая текущий2 в ноябре означает ноябрь и декабрь. Диапазон: 1–11 месяцев.

Границы периода рассчитываются в UTC. Например, 10 ноября 2026 года с горизонтом 2 запрашивается период с 2026-11-01T00:00:00Z до 2027-01-01T00:00:00Z.

Чтобы изменить работающий источник, снимите галочку периодической синхронизации, внесите правки и сохраните. После изменения конфигурации или авторизации нужны новый предпросмотр и применение; затем обновления можно включить снова.

Пользователи, роли и OIDC#

Для каждого человека нужны стабильный внешний ID и корректный email. При первом импорте IR ищет пользователя по email без учёта регистра. Если найден один — использует его. Если не найден — создаёт учётную запись без локального пароля и глобальных административных прав. Следующие импорты используют сохранённую связь с внешним ID.

Чтобы импортированные люди могли войти через OIDC:

  • Настройте и включите провайдера OIDC в IR.
  • Включите связывание по email (auto_link_by_email).
  • Убедитесь, что email каталога совпадает с email, который OIDC передаёт при входе.
  • Пользователь входит через OIDC, и его identity связывается с существующей учётной записью. auto_create_users для неё не требуется.

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

Источник состава и ролей определяет, кто назначает доступ:

  • API синхронизации (sync) создаёт членства из внешнего состава и защищает созданные им роли от перезаписи при входе через OIDC. По умолчанию роль в группе — viewer, участника команды — responder, ответственного — manager.
  • OIDC (oidc) оставляет назначения членств и ролей настроенным маппингам SSO. Пользователей, команды и расписания по-прежнему импортирует источник. Настройте маппинги SSO до входа пользователей.

Способ входа в обоих случаях может быть OIDC. Роли источника задаются через group_role, member_role, responsible_role в JSON маппинга. Личные настройки уведомлений и интерфейса остаются за пользователем.

В org-service roster — участники дежурств, а не все сотрудники подразделения. В режиме sync ответственный также добавляется в команду. Участники смен и замен вне этого состава получают пользовательские записи, но только из-за участия в смене членами команды не становятся. В режиме sync им также создаётся доступ к группе, если его ещё нет.

Настройка другого API: операции#

Операции API (JSON) описывают, куда обращаться. Маппинг полей и роли участников (JSON) описывает, как прочитать полученный ответ: например, какое поле содержит email.

ОперацияНазначениеОтвет после выбора items
teamsКаталог команд. Обязательна.Массив команд.
teamПодробная карточка команды. Не нужна, если состав и расписания уже есть в каталоге.Объект команды.
userПрофиль и email человека. Не нужна, если профиль приходит вместе с составом.Объект или массив из одного профиля; для user_fetch: all — каталог.
shiftsСмены одной команды за период. Обязательна.Массив смен, либо пустой [], если смен нет.
currentФактический дежурный по расписанию. Необязательна.В пакетном режиме — массив ответов по слотам.

Готовые операции org-service; этот JSON можно целиком вставить в поле операций:

{
  "teams": {
    "method": "GET", "path": "/api/v1/support-team-catalog", "items": "teams",
    "pagination": {"mode": "cursor", "parameter": "pageToken", "next_path": "nextPageToken", "size_parameter": "pageSize", "size": 100}
  },
  "team": {"method": "GET", "path": "/api/v1/duty-scopes/{team_id}"},
  "user": {"method": "GET", "path": "/api/v1/employees", "params": {"uuid": "{user_id}"}, "items": "employees"},
  "shifts": {
    "method": "GET", "path": "/api/v1/duty-scopes/{team_id}/shifts",
    "params": {"from": "{from}", "to": "{to}"}, "items": "shifts"
  },
  "current": {
    "method": "POST", "path": "/api/v1/duty-schedules:batch-current",
    "body": {"scheduleUuids": "{schedule_ids}"}, "items": "duties"
  }
}

method — GET или POST для чтения данных. path добавляется к базовому адресу; params передаются в строке запроса; body — JSON-тело POST. items выбирает нужный объект или массив: например, для ответа {"result":{"teams":[]}} укажите result.teams. Если ответ сам является массивом, оставьте items пустым или укажите $.

IR подставляет значения в фигурных скобках:

ПодстановкаЗначение
{team_id}Внешний ID из team_fields.id. Доступен в team, shifts и индивидуальном user.
{user_id}Внешний ID человека для индивидуального user.
{from}, {to}Начало и конец периода для каталога, карточек, профилей и смен.
{schedule_ids}Массив внешних ID расписаний для current.
{schedule_id}Один ID расписания при current_fetch: per_schedule.

В {"scheduleUuids":"{schedule_ids}"} подстановка заменяет значение целиком: в запрос уходит массив, а не строка. Значения в URL кодируются автоматически.

user_fetch: per_user получает каждый профиль отдельно; all загружает каталог с пагинацией и выбирает нужных людей по ID. current_fetch: batch получает назначения пакетами до 500 расписаний; per_schedule обращается к каждому расписанию отдельно и принимает объект или массив из одного элемента.

Пагинация#

pagination.modeКогда выбратьУсловие окончания загрузки
noneВесь массив приходит одним ответом.Один запрос.
cursorОтвет содержит токен следующей страницы.Токен отсутствует или пуст.
offsetAPI принимает смещение и размер страницы.Вернулось меньше записей, чем size.
pageAPI принимает номер и размер страницы.Вернулось меньше записей, чем size.

parameter — имя параметра токена, смещения или номера; size_parameter — имя размера страницы. Для нумерации с единицы задайте start: 1. Для cursor поле next_path указывает, где читать следующий токен. У org-service это pageToken, pageSize и nextPageToken, размер страницы — не более 100.

Повтор токена или достижение max_pages завершают запуск ошибкой. null и объект ошибки вместо массива не считаются успешной пустой загрузкой.

Настройка другого API: маппинг#

Слева в маппинге находится поле IR, справа — путь во внешнем ответе. Если API возвращает:

{"uuid":"person-1","contacts":{"email":"anna@example.com"},"firstname":"Анна","lastname":"Петрова"}

значение user_fields может быть таким:

{
  "id": "uuid",
  "email": "contacts.email",
  "name": {"paths": ["firstname", "lastname"], "join": " "}
}

Это пример только значения user_fields. Измените соответствующую часть большого JSON, сохранив другие разделы. IR получит ID person-1, email anna@example.com и имя Анна Петрова.

РазделЧто описываетОсновные поля IR
team_fieldsКоманду из каталогаid, name, description.
detail_fieldsДополнение из карточки teamname, description, enabled.
team_filterПоле каталога, которое должно быть непустымДля org-service — enrolledScopeUuid.
membersМассив участников командыpath до массива и fields с id; при наличии — name, username, email, inactive.
responsibleОбъект ответственногоpath и fields как у участника. Можно задать null, если не нужен.
schedulesМассив слотов дежурстваpath и fields: id, необязательные name, timezone (по умолчанию UTC).
user_fieldsПрофиль из userid, email, username, name, phone, inactive.
shift_fieldsОдну сменуid, schedule_id, user_id, start, end, title, unavailable, inactive.
replacementsЗамены внутри сменыpath и fields: id, user_id, start, end, precedence, inactive. Пустой массив — без замен.
current_fieldsТекущее назначениеid расписания, status, user_id; при наличии — valid_until, start, end.
team_matchesРучное соответствие команд{"external-team-1":42}, где 42 — ID команды IR.

Пути читаются через точку: employee.employeeUuid, person.inactive. Числовая часть выбирает индекс массива: contacts.0.email. $ означает значение целиком.

Другие варианты маппинга:

{
  "timezone": {"value": "UTC"},
  "inactive": {"path": "state", "values": {"enabled": false, "disabled": true}},
  "phone": {"path": "contacts.phone", "default": null}
}

value задаёт константу. values переводит значения внешней системы в значения IR. default применяется при отсутствии поля или подходящего соответствия. inactive и unavailable должны давать JSON true/false, а не строки. Времена должны включать часовой пояс: например, 2026-11-10T09:00:00+03:00.

В org-service команда определяется по enrolledScopeUuid, а не по CMDB externalId. Фильтр по этому полю выбирает все подключённые команды. Фильтры по eligibility или типу графика могут исключить уже подключённые команды. Люди связываются по employeeUuid/uuid, ротации — по UUID расписаний.

Расписание и фактический дежурный#

Один внешний scheduleUuid создаёт одну ротацию IR. Два параллельных слота команды создают две ротации. Импортируются готовые интервалы, recurrence повторно не разворачивается. В пересекающихся заменах побеждает большее precedence; пересекающиеся смены одного слота не приводят к произвольному выбору человека.

Календарь показывает импортированные интервалы. При настроенной операции current фактическое назначение берётся из её ответа:

СтатусПоведение
activeНазначается известный активный пользователь.
gapДежурного в слоте нет.
unavailableДежурный недоступен.
ambiguousИсточник не смог однозначно определить дежурного.
stale в IRСвежего ответа ещё нет или срок его действия истёк.

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

Ответ хранится не дольше current_max_age_seconds — по умолчанию 120 секунд, настройка находится в JSON маппинга. valid_until и конец смены могут сократить срок. При сбое API прежний ответ пригоден только до истечения срока. Обновление текущих дежурных выполняется отдельно от полного импорта и учитывает отсутствие сотрудника без изменения ревизии расписания.

При приостановке периодической синхронизации календарь остаётся, а кэш фактического дежурного постепенно истекает. При разрешённом локальном редактировании смены и замены меняются через Импортированное расписание в действиях ротации. Время в этой форме указано в UTC.

Подключение в закрытом контуре#

API вызывается сервером IR. Успешный запрос с вашего компьютера ещё не подтверждает доступ из контейнера или сервера IR.

  • Проверьте DNS, маршрутизацию и доступ к порту API из web и scheduler.
  • Добавьте IP или подсеть API в серверную конфигурацию. Например:

``ini [orchestration] webhook_private_network_allowlist = 10.20.30.0/24 ``

  • Перезапустите процессы IR, чтобы они перечитали конфигурацию.
  • В источнике выберите Разрешённые сети сервера (private_network_policy: allowlist).
  • Для сертификата внутреннего CA установите доверие к нему в окружении процессов IR. Если нужно подключиться без проверки сертификата, включите у источника Не проверять TLS-сертификат и сохраните настройки.

В API эта настройка называется config.verify_tls: true (по умолчанию) включает проверку, false отключает. Она применяется к получению структуры ответа, предпросмотру, импорту и обновлению текущих дежурных. После изменения нужен новый предпросмотр и применение, прежде чем снова включить периодическую синхронизацию. Настройка не отменяет серверный allowlist и не влияет на другие источники или исходящие вебхуки.

Несколько подсетей разделяются запятыми. Для обычного HTTP дополнительно нужен webhook_allow_http = true в той же секции. Выбор allowlist в форме не добавляет адреса в серверный список: используется общая политика исходящих запросов IR.

Проверить DNS, TCP и TLS в стандартном Docker-развёртывании можно без PAT:

docker exec incidentrelay curl --noproxy '*' -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  --connect-timeout 10 --max-time 20 \
  'https://example.com/api/v1/support-team-catalog?pageSize=1'

Замените URL на адрес своего API и повторите команду для контейнера incidentrelay-scheduler: структуру ответа получает web, импорт выполняет scheduler. Ответ HTTP 401/403 без PAT ожидаем и подтверждает, что HTTP-соединение состоялось; он ещё не подтверждает права токена или правильность пути API. Could not resolve host указывает на DNS, Connection refused — на отказ подключения, таймаут — на отсутствие ответа в отведённое время. При ошибке проверки сертификата настройте доверие внутреннему CA в обоих контейнерах. --noproxy '*' проверяет прямое соединение, как и транспорт синхронизации: переменные HTTP_PROXY/HTTPS_PROXY он не использует. Проверка curl не заменяет проверку серверного allowlist в IR.

Как подключиться к API IR из скрипта#

Нужны базовый адрес IR, ID группы назначения и персональный токен администратора этой группы. Токену нужны scopes directory-sync:read и directory-sync:write. Токен только с resources:* или токен команды не подходит.

Пример проверки подключения; IR_TOKEN — переменная окружения с токеном IR:

curl --fail-with-body 'https://ir.example.com/api/admin/directory-sync/options' \
  -H "Authorization: Bearer ${IR_TOKEN}"

Ответ содержит доступные groups, команды teams и готовую конфигурацию preset. Их ID — локальные ID IR, не UUID внешней системы.

ЗапросНазначение
GET /api/admin/directory-syncСписок доступных источников и их ID.
POST /api/admin/directory-syncСоздание: name, group_id, объект config, headers, enabled: false. За основу config можно взять preset.
GET /api/admin/directory-sync/{id}Настройки, актуальная revision, результат и состояние задания. Секреты не возвращаются.
PUT /api/admin/directory-sync/{id}Обновление с актуальной revision. Пропустите headers, чтобы сохранить секрет.
POST /api/admin/directory-sync/{id}/sampleСтруктура ответа каталога.
POST /api/admin/directory-sync/{id}/previewПредпросмотр; тело {"revision":1}.
POST /api/admin/directory-sync/{id}/applyПрименение; тело содержит revision и preview_token предпросмотра.
POST /api/admin/directory-sync/{id}/runОчередной импорт утверждённой конфигурации; тело содержит revision.

Запуск возвращает 202: задание принято в очередь. Опрашивайте GET источника: pending_mode и running показывают незавершённую работу, last_error — ошибку, preview_result — предпросмотр, last_result — результат применения. Ошибка фактического дежурного хранится отдельно в current_error. Полная схема есть в OpenAPI IR.

API конкретных смен использует права ротации: GET/POST /api/rotations/{rotation_id}/imported-shifts, PUT/DELETE /api/rotations/imported-shifts/{shift_id}. Пагинация списка — after/next_cursor; user_id — ID пользователя IR. Локальное удаление хранится как отметка до следующего импорта.

Если что-то не работает#

СимптомЧто проверить
Нет раздела или API IR возвращает 403Роль администратора группы, выбранную группу и scopes токена.
Предпросмотр постоянно в очередиScheduler: systemctl status incidentrelay-scheduler; журнал: journalctl -u incidentrelay-scheduler -f. В Docker: docker compose logs -f incidentrelay-scheduler.
API target blockedHTTPS, серверный allowlist и режим доступа к сети у источника.
Внешний API возвращает 401/403PAT, срок, права и формат заголовка. Токен IR не заменяет внешний PAT.
API DNS resolution failedDNS внутри контейнеров web и scheduler.
API TLS connection failedДоверие CA, имя в сертификате и настройки TLS в окружении IR.
API connection refused или API connection failedАдрес, порт API и прямой доступ из контейнеров IR.
API request timed outСеть, время ответа API и timeout_seconds.
API response exceeded the 8 MiB limitУменьшите размер страницы API.
items mapping must resolve to an arrayПуть items должен выбирать массив нужной операции.
В предпросмотре нет командОтвет каталога и team_filter. Для org-service нужен непустой enrolledScopeUuid.
Команда помечена skipСоответствие команде IR и галочку управления найденными командами.
Конфликт emailEmail всех людей, включая ответственных и заменяющих; отсутствие дублей и удалённых совпавших аккаунтов.
Нельзя включить обновлениеПрименён ли предпросмотр текущей конфигурации. После правок он нужен снова.
Preview expired или Local data changed since previewПолучите новый предпросмотр и проверьте план.
Календарь есть, но дежурного нетcurrent_error, статус и свежесть current, активность пользователя, включённые обновления.

При временных сетевых ошибках выполняется до трёх попыток. Ограничения запуска: 8 МиБ на ответ, 10 000 запросов, 30 минут и 100 000 записей на операцию. Таймаут задаётся через timeout_seconds (1–60 секунд). Redirect не выполняется; ошибки авторизации не повторяются. Заголовки и исходные тела ответов в ошибки и журналы не включаются.

При получении структуры ответа сбои внешнего API имеют код sync_api_error: HTTP 502 для ошибок подключения или ответа, HTTP 504 для таймаута. HTTP 409 sync_conflict относится к состоянию синхронизации, например занятому источнику или устаревшей ревизии. В предыдущих версиях teams: API connection failed тоже возвращался как sync_conflict; сам по себе этот код не доказывает конфликт команд или параллельный запуск. Для фоновых запусков результат запроса остаётся HTTP 202, а причину последующего сбоя нужно читать в last_error или current_error.

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