Синхронизация команд и дежурств#
Синхронизация переносит в IncidentRelay команды, пользователей и расписания из внешней системы. IR сам обращается к её API через заданный интервал. Изменения из IR обратно не отправляются.
Настройки одного подключения называются источником: адрес API, авторизация, запросы, соответствие полей и правила обновления. Для каждого источника выбирается одна группа IR.
Что подготовить#
| Что нужно | Для чего |
|---|---|
| Учётная запись администратора | Глобальный администратор выбирает любую активную группу; администратор группы — только группы, которыми управляет. |
| Адрес внешнего API | Например, https://org-service.example.com. Это система с командами и дежурствами. |
| Токен внешнего API | Для org-service — PAT с правами чтения команд, сотрудников, расписаний и текущих дежурных. |
| Работающий scheduler IR | Он выполняет предпросмотр, применение и периодические обновления. |
| Сетевой доступ из IR | Web и scheduler должны разрешать имя API, подключаться к нему и доверять его сертификату. |
При обновлении приложения сначала выполните python manage.py migrate, затем запустите обновлённые процессы web и scheduler. Подробнее — планировщик и установка.
Не путайте два токена. В настройках источника нужен токен внешнего API. Персональный токен IR нужен только для скрипта, который настраивает IR через его API. Для настройки в интерфейсе достаточно своей сессии в IR.
Первый запуск через интерфейс#
1. Добавьте источник#
Откройте Администрирование → Синхронизация → Добавить источник. Настройки откроются в модальном окне. Кнопка Настроить у существующего источника открывает то же окно для редактирования.
В форме уже есть готовые запросы и маппинг для org-service. Для этой системы их можно оставить и заполнить только своё подключение. Для другого API используйте разбор запросов и маппинга ниже.
2. Заполните подключение#
| Поле | Пример и пояснение |
|---|---|
| Название | Дежурства платформы — имя, по которому источник будет виден в IR. |
| Группа назначения | Группа IR, в которой должны появиться команды. После создания источника её изменить нельзя. |
| Базовый адрес API | https://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 секунд. |
| Обновление дежурного | Фактически дежурящего человека по операции current | 60 — раз в минуту. Диапазон: 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 | Ответ содержит токен следующей страницы. | Токен отсутствует или пуст. |
offset | API принимает смещение и размер страницы. | Вернулось меньше записей, чем size. |
page | API принимает номер и размер страницы. | Вернулось меньше записей, чем 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 | Дополнение из карточки team | name, 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 | Профиль из user | id, 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 blocked | HTTPS, серверный allowlist и режим доступа к сети у источника. |
| Внешний API возвращает 401/403 | PAT, срок, права и формат заголовка. Токен IR не заменяет внешний PAT. |
API DNS resolution failed | DNS внутри контейнеров 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 и галочку управления найденными командами. |
| Конфликт email | Email всех людей, включая ответственных и заменяющих; отсутствие дублей и удалённых совпавших аккаунтов. |
| Нельзя включить обновление | Применён ли предпросмотр текущей конфигурации. После правок он нужен снова. |
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.