Интеграция с ServiceNow

Интеграция с ServiceNow (Администрирование > Настройки > ServiceNow) обеспечивает двунаправленную синхронизацию между Canopy и вашей CMDB ServiceNow. В этом руководстве описано всё — от первоначальной настройки до продвинутых сценариев и лучших практик эксплуатации.

Настройки ServiceNow

Зачем интегрировать ServiceNow с Canopy?

ServiceNow CMDB и инструменты корпоративной архитектуры служат разным, но взаимодополняющим целям:

	ServiceNow CMDB	Canopy
Фокус	ИТ-операции — что работает, кто отвечает, какие инциденты произошли	Стратегическое планирование — как должен выглядеть ландшафт через 3 года?
Обслуживается	ИТ-операции, управление активами	Команда EA, бизнес-архитекторы
Сильная сторона	Автоматическое обнаружение, рабочие процессы ITSM, операционная точность	Бизнес-контекст, карта возможностей, планирование жизненного цикла, оценки
Типичные данные	Имена хостов, IP-адреса, статус установки, группы назначения, контракты	Бизнес-критичность, функциональное соответствие, технический долг, стратегическая дорожная карта

Canopy является основной системой записи для вашего архитектурного ландшафта — имена, описания, планы жизненного цикла, оценки и бизнес-контекст хранятся здесь. ServiceNow дополняет Canopy операционными и техническими метаданными (имена хостов, IP-адреса, данные SLA, статус установки), поступающими из автоматического обнаружения и рабочих процессов ITSM. Интеграция обеспечивает связь этих двух систем, при этом Canopy является ведущей.

Что вы можете сделать

Pull-синхронизация — наполнение Canopy CI из ServiceNow с последующим принятием управления. Последующие pull-операции обновляют только операционные поля (IP, статус, SLA), которые SNOW обнаруживает автоматически
Push-синхронизация — экспорт курируемых EA данных обратно в ServiceNow (имена, описания, оценки, планы жизненного цикла), чтобы команды ITSM видели контекст EA
Двунаправленная синхронизация — Canopy ведёт большинство полей; SNOW ведёт небольшой набор операционных/технических полей. Обе системы остаются синхронизированными
Карта идентификаторов — постоянное перекрёстное отслеживание (sys_id <-> UUID карточки) обеспечивает связь записей между синхронизациями

Архитектура интеграции

+------------------+         HTTPS / Table API          +------------------+
|   Canopy       | <--------------------------------> |  ServiceNow      |
|                  |                                     |                  |
|  Карточки        |  Pull: SNOW CI -> Карточки Turbo    |  CMDB CI         |
|  (Application,   |  Push: Карточки Turbo -> SNOW CI    |  (cmdb_ci_appl,  |
|   ITComponent,   |                                     |   cmdb_ci_server, |
|   Provider, ...) |  Identity Map: sys_id &lt;-> UUID      |   core_company)  |
+------------------+                                     +------------------+

Интеграция использует Table API ServiceNow через HTTPS. Учётные данные шифруются при хранении с помощью Fernet (AES-128-CBC), производного от вашего SECRET_KEY. Все операции синхронизации регистрируются как события с source: "servicenow_sync" для полного аудита.

Планирование интеграции

Прежде чем настраивать что-либо, ответьте на следующие вопросы:

1. Какие типы карточек нуждаются в данных из ServiceNow?

Начните с малого. Наиболее распространённые точки интеграции:

Приоритет	Тип Canopy	Источник ServiceNow	Почему
Высокий	Application	`cmdb_ci_business_app`	Приложения — основа EA; в CMDB есть авторитетные имена, владельцы и статусы
Высокий	ITComponent (Software)	`cmdb_ci_spkg`	Программные продукты для отслеживания EOL и технологического радара
Средний	ITComponent (Hardware)	`cmdb_ci_server`	Серверный ландшафт для карты инфраструктуры
Средний	Provider	`core_company`	Реестр вендоров для управления затратами и отношениями
Низкий	Interface	`cmdb_ci_endpoint`	Конечные точки интеграции (часто поддерживаются вручную в EA)
Низкий	DataObject	`cmdb_ci_database`	Экземпляры баз данных

2. Какая система является источником истины для каждого поля?

Это самое важное решение. По умолчанию Canopy ведёт — инструмент EA является системой записи для вашего архитектурного ландшафта. ServiceNow должен вести только узкий набор операционных и технических полей, поступающих из автоматического обнаружения или рабочих процессов ITSM. Всё остальное — имена, описания, оценки, планирование жизненного цикла, затраты — принадлежит команде EA в Canopy.

Рекомендуемая модель — «Canopy ведёт, SNOW дополняет»:

Тип поля	Источник истины	Почему
Имена и описания	Turbo ведёт	Команда EA курирует авторитетные имена и пишет стратегические описания; имена в CMDB могут быть некорректными или автогенерированными
Бизнес-критичность	Turbo ведёт	Стратегическая оценка команды EA — не операционные данные
Функциональное / техническое соответствие	Turbo ведёт	Оценки модели TIME — забота EA
Жизненный цикл (все фазы)	Turbo ведёт	Планирование, внедрение, активный, вывод, окончание — всё это данные планирования EA
Данные о затратах	Turbo ведёт	EA отслеживает совокупную стоимость владения; CMDB может иметь позиции контрактов, но EA владеет консолидированным представлением
Тип хостинга, категория	Turbo ведёт	EA классифицирует приложения по модели хостинга для стратегического анализа
Техническая метаинформация	SNOW ведёт	IP-адреса, версии ОС, имена хостов, серийные номера — данные автоматического обнаружения
SLA / операционный статус	SNOW ведёт	Статус установки, цели SLA, метрики доступности — операционные данные ITSM
Группа назначения / поддержка	SNOW ведёт	Операционное владение, отслеживаемое в рабочих процессах ServiceNow
Даты обнаружения	SNOW ведёт	Первое/последнее обнаружение, последнее сканирование — метаданные автоматизации CMDB

3. Как часто следует синхронизировать?

Сценарий	Частота	Примечания
Первоначальный импорт	Однократно	Режим добавления, тщательная проверка
Активное управление ландшафтом	Ежедневно	Автоматизация через cron в нерабочие часы
Отчётность по соответствию	Еженедельно	Перед генерацией отчётов
По запросу	По мере необходимости	Перед крупными обзорами EA или презентациями

Шаг 1: Предварительные требования ServiceNow

Создание сервисной учётной записи

В ServiceNow создайте выделенную сервисную учётную запись (никогда не используйте личные учётные записи):

Роль	Назначение	Обязательна?
`itil`	Доступ на чтение к таблицам CMDB	Да
`cmdb_read`	Чтение конфигурационных элементов	Да
`rest_api_explorer`	Полезна для тестирования запросов	Рекомендуется
`import_admin`	Доступ на запись в целевые таблицы	Только для push-синхронизации

Лучшая практика: Создайте пользовательскую роль с доступом только на чтение к конкретным таблицам, которые вы планируете синхронизировать. Роль itil слишком широкая — пользовательская роль с ограниченной областью снижает риск.

Сетевые требования

Бэкенд Canopy должен иметь доступ к вашему экземпляру SNOW через HTTPS (порт 443)
Настройте правила межсетевого экрана и списки разрешённых IP
Формат URL экземпляра: https://company.service-now.com или https://company.servicenowservices.com

Выбор метода аутентификации

Метод	Преимущества	Недостатки	Рекомендация
Basic Auth	Простая настройка	Учётные данные отправляются с каждым запросом	Только для разработки/тестирования
OAuth 2.0	На основе токенов, с областью, удобный для аудита	Больше шагов настройки	Рекомендуется для производства

Для OAuth 2.0:

В ServiceNow: System OAuth > Application Registry
Создайте новую конечную точку OAuth API для внешних клиентов
Запишите Client ID и Client Secret
Ротируйте секреты каждые 90 дней

Шаг 2: Создание подключения

Перейдите в Администрирование > ServiceNow > вкладка Подключения.

Создание и тестирование

Нажмите Добавить подключение
Заполните:

Поле	Пример значения	Примечания
Имя	`Производственная CMDB`	Описательная метка для вашей команды
URL экземпляра	`https://company.service-now.com`	Обязательно HTTPS
Тип аутентификации	Basic Auth или OAuth 2.0	OAuth рекомендуется для производства
Учётные данные	(по типу аутентификации)	Шифруются при хранении через Fernet

Нажмите Создать, затем нажмите значок тестирования (символ WiFi) для проверки подключения

Зелёный индикатор «Подключено» — готово к работе
Красный индикатор «Ошибка» — проверьте учётные данные, сеть и URL

Несколько подключений

Вы можете создать несколько подключений для:

Производственных и тестовых экземпляров
Региональных экземпляров SNOW (например, EMEA, APAC)
Разных команд с отдельными сервисными учётными записями

Каждый маппинг ссылается на конкретное подключение.

Шаг 3: Проектирование маппингов

Переключитесь на вкладку Маппинги. Маппинг связывает один тип карточки Canopy с одной таблицей ServiceNow.

Создание маппинга

Нажмите Добавить маппинг и настройте:

Поле	Описание	Пример
Подключение	Какой экземпляр ServiceNow использовать	Производственная CMDB
Тип карточки	Тип карточки Canopy для синхронизации	Application
Таблица SNOW	Имя API таблицы ServiceNow	`cmdb_ci_business_app`
Направление синхронизации	Какие операции доступны (см. ниже)	ServiceNow -> Canopy
Режим синхронизации	Как обрабатывать удаления	Консервативный
Макс. коэффициент удаления	Порог безопасности для массовых удалений	50%
Фильтр запроса	Закодированный запрос ServiceNow для ограничения области	`active=true^install_status=1`
Пропустить стейджинг	Применять изменения без промежуточной проверки	Выкл (рекомендуется для начальной синхронизации)

Распространённые маппинги таблиц SNOW

Тип Canopy	Таблица ServiceNow	Описание
Application	`cmdb_ci_business_app`	Бизнес-приложения (наиболее распространённый)
Application	`cmdb_ci_appl`	Общие CI приложений
ITComponent (Software)	`cmdb_ci_spkg`	Программные пакеты
ITComponent (Hardware)	`cmdb_ci_server`	Физические/виртуальные серверы
ITComponent (SaaS)	`cmdb_ci_cloud_service_account`	Учётные записи облачных сервисов
Provider	`core_company`	Вендоры / компании
Interface	`cmdb_ci_endpoint`	Конечные точки интеграции
DataObject	`cmdb_ci_database`	Экземпляры баз данных
System	`cmdb_ci_computer`	CI компьютеров
Organization	`cmn_department`	Отделы

Примеры запросов фильтрации

Всегда фильтруйте, чтобы избежать импорта устаревших или выведенных из эксплуатации записей:

# Только активные CI (минимальный рекомендуемый фильтр)
active=true

# Активные CI со статусом установки «Установлен»
active=true^install_status=1

# Приложения в производственном использовании
active=true^used_for=Production

# CI, обновлённые за последние 30 дней
active=true^sys_updated_on>=javascript:gs.daysAgoStart(30)

# Определённая группа назначения
active=true^assignment_group.name=IT Operations

# Исключить выведенные из эксплуатации CI
active=true^install_statusNOT IN7,8

Лучшая практика: Всегда включайте active=true как минимум. Таблицы CMDB часто содержат тысячи выведенных из эксплуатации записей, которые не должны импортироваться в ваш архитектурный ландшафт.

Шаг 4: Настройка маппингов полей

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

Добавление полей

Для каждого маппинга поля вы настраиваете:

Настройка	Описание
Поле Canopy	Путь поля в Canopy (автозаполнение предлагает варианты на основе типа карточки)
Поле SNOW	Имя API столбца ServiceNow (например, `name`, `short_description`)
Направление	Источник истины для каждого поля: SNOW ведёт или Turbo ведёт
Преобразование	Как конвертировать значения: Прямое, Карта значений, Дата, Логическое
Идентификатор (флажок ID)	Используется для сопоставления записей при начальной синхронизации

Пути полей Canopy

Автозаполнение группирует поля по секциям. Полная справка путей:

Путь	Цель	Пример значения
`name`	Отображаемое имя карточки	`"SAP S/4HANA"`
`description`	Описание карточки	`"Основная ERP-система для финансов"`
`lifecycle.plan`	Жизненный цикл: дата планирования	`"2024-01-15"`
`lifecycle.phaseIn`	Жизненный цикл: дата внедрения	`"2024-03-01"`
`lifecycle.active`	Жизненный цикл: дата активации	`"2024-06-01"`
`lifecycle.phaseOut`	Жизненный цикл: дата вывода	`"2028-12-31"`
`lifecycle.endOfLife`	Жизненный цикл: дата окончания	`"2029-06-30"`
`attributes.<key>`	Любой пользовательский атрибут из схемы полей типа карточки	Зависит от типа поля

Например, если ваш тип Application имеет поле с ключом businessCriticality, выберите attributes.businessCriticality из выпадающего списка.

Поля идентификации — как работает сопоставление

Отметьте одно или несколько полей как Идентификатор (значок ключа). Они используются при первой синхронизации для сопоставления записей ServiceNow с существующими карточками Canopy:

Поиск в карте идентификаторов — если связь sys_id <-> UUID карточки уже существует, используется она
Точное совпадение имени — сопоставление по значению поля идентификации (например, по имени приложения)
Нечёткое совпадение — если нет точного совпадения, используется SequenceMatcher с порогом сходства 85%

Лучшая практика: Всегда отмечайте поле name как поле идентификации. Если имена различаются между системами (например, SNOW включает номера версий типа «SAP S/4HANA v2.1», а Canopy — «SAP S/4HANA»), приведите их в соответствие перед первой синхронизацией для лучшего качества сопоставления.

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

Шаг 5: Запуск первой синхронизации

Переключитесь на вкладку Панель синхронизации.

Запуск синхронизации

Для каждого активного маппинга вы видите кнопки Pull и/или Push в зависимости от настроенного направления синхронизации:

Pull (значок загрузки из облака) — извлекает данные из SNOW в Canopy
Push (значок выгрузки в облако) — отправляет данные Canopy в ServiceNow

Что происходит во время Pull-синхронизации

1. ИЗВЛЕЧЕНИЕ  Получение всех подходящих записей из SNOW (пакетами по 500)
2. СОПОСТАВЛЕНИЕ  Сопоставление каждой записи с существующей карточкой:
                  a) Карта идентификаторов (постоянный поиск sys_id &lt;-> UUID карточки)
                  b) Точное совпадение имени по полям идентификации
                  c) Нечёткое совпадение имени (порог сходства 85%)
3. ПРЕОБРАЗОВАНИЕ  Применение маппингов полей для конвертации SNOW -> формат Canopy
4. СРАВНЕНИЕ  Сравнение преобразованных данных с существующими полями карточки
5. СТЕЙДЖИНГ  Назначение действия каждой записи:
              - create: Новая, подходящая карточка не найдена
              - update: Совпадение найдено, поля различаются
              - skip:   Совпадение найдено, различий нет
              - delete: В карте идентификаторов, но отсутствует в SNOW
6. ПРИМЕНЕНИЕ  Выполнение промежуточных действий (создание/обновление/архивация карточек)

Когда Пропустить стейджинг включён, шаги 5 и 6 объединяются — действия применяются напрямую без записи промежуточных записей.

Просмотр результатов синхронизации

Таблица История синхронизации показывает после каждого запуска:

Столбец	Описание
Начало	Когда синхронизация началась
Направление	Pull или Push
Статус	`completed`, `failed` или `running`
Извлечено	Всего записей получено из ServiceNow
Создано	Новых карточек создано в Canopy
Обновлено	Существующих карточек обновлено
Удалено	Карточек архивировано (мягкое удаление)
Ошибки	Записей, которые не удалось обработать
Длительность	Фактическое время

Нажмите значок списка на любом запуске для просмотра отдельных промежуточных записей, включая diff на уровне полей для каждого обновления.

Понимание направления синхронизации и направления полей

Это наиболее часто неправильно понимаемая концепция. Существует два уровня направления, которые работают вместе:

Уровень таблицы: направление синхронизации

Устанавливается на самом маппинге. Контролирует какие операции синхронизации доступны на панели синхронизации:

Направление синхронизации	Кнопка Pull?	Кнопка Push?	Когда использовать...
ServiceNow -> Canopy	Да	Нет	CMDB является мастер-источником, вы только импортируете
Canopy -> ServiceNow	Нет	Да	Инструмент EA обогащает CMDB оценками
Двунаправленный	Да	Да	Обе системы вносят данные в разные поля

Уровень поля: направление

Устанавливается для каждого маппинга поля. Контролирует значение какой системы приоритетнее во время синхронизации:

Направление поля	При Pull (SNOW -> Turbo)	При Push (Turbo -> SNOW)
SNOW ведёт	Значение импортируется из ServiceNow	Значение пропускается (не передаётся)
Turbo ведёт	Значение пропускается (не перезаписывается)	Значение экспортируется в ServiceNow

Как они работают вместе — пример

Маппинг: Application <-> cmdb_ci_business_app, Двунаправленный

Поле	Направление	Pull делает...	Push делает...
`name`	Turbo ведёт	Пропускает (EA курирует имена)	Передаёт имя EA -> SNOW
`description`	Turbo ведёт	Пропускает (EA пишет описания)	Передаёт описание -> SNOW
`lifecycle.active`	Turbo ведёт	Пропускает (EA управляет жизненным циклом)	Передаёт дату запуска -> SNOW
`attributes.businessCriticality`	Turbo ведёт	Пропускает (оценка EA)	Передаёт оценку -> пользовательское поле SNOW
`attributes.ipAddress`	SNOW ведёт	Импортирует IP из обнаружения	Пропускает (операционные данные)
`attributes.installStatus`	SNOW ведёт	Импортирует операционный статус	Пропускает (данные ITSM)

Ключевое понимание: Направление на уровне таблицы определяет какие кнопки отображаются. Направление на уровне поля определяет какие поля фактически передаются при каждой операции. Двунаправленный маппинг, где Canopy ведёт большинство полей, а SNOW ведёт только операционные/технические поля — наиболее мощная конфигурация.

Лучшая практика: направление поля по типу данных

По умолчанию должно быть Turbo ведёт для подавляющего большинства полей. Устанавливайте SNOW ведёт только для операционных и технических метаданных из автоматического обнаружения или рабочих процессов ITSM.

Категория данных	Рекомендуемое направление	Обоснование
Имена, метки отображения	Turbo ведёт	Команда EA курирует авторитетные, чистые имена — имена в CMDB часто автогенерированные или непоследовательные
Описание	Turbo ведёт	Описания EA содержат стратегический контекст, бизнес-ценность и архитектурную значимость
Бизнес-критичность (модель TIME)	Turbo ведёт	Основная оценка EA — не операционные данные
Функциональное/техническое соответствие	Turbo ведёт	Оценка и классификация дорожной карты EA
Жизненный цикл (все фазы)	Turbo ведёт	Планирование, внедрение, активный, вывод, окончание — всё это решения планирования EA
Данные о затратах	Turbo ведёт	EA отслеживает совокупную стоимость владения и распределение бюджета
Тип хостинга, классификация	Turbo ведёт	Стратегическая категоризация, поддерживаемая архитекторами
Информация о вендоре/поставщике	Turbo ведёт	EA управляет стратегией вендоров, контрактами и рисками
Техническая метаинформация (ОС, IP, хост)	SNOW ведёт	Данные автоматического обнаружения — EA этого не поддерживает
Цели SLA, метрики доступности	SNOW ведёт	Операционные данные из рабочих процессов ITSM
Статус установки, операционное состояние	SNOW ведёт	CMDB отслеживает, установлен ли CI, выведен из эксплуатации и т.д.
Группа назначения, команда поддержки	SNOW ведёт	Операционное владение, управляемое в ServiceNow
Метаданные обнаружения (первое/последнее обнаружение)	SNOW ведёт	Временные метки автоматизации CMDB

Пропуск стейджинга — когда использовать

По умолчанию pull-синхронизации следуют рабочему процессу стейджинг-применение:

Извлечение -> Сопоставление -> Преобразование -> Сравнение -> СТЕЙДЖИНГ -> Проверка -> ПРИМЕНЕНИЕ

Записи помещаются в промежуточную таблицу, позволяя вам просмотреть изменения перед применением.

Режим пропуска стейджинга

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

Извлечение -> Сопоставление -> Преобразование -> Сравнение -> ПРЯМОЕ ПРИМЕНЕНИЕ

Промежуточные записи не создаются — изменения происходят немедленно.

	Стейджинг (по умолчанию)	Пропуск стейджинга
Этап проверки	Да — проверка diff перед применением	Нет — изменения применяются сразу
Таблица промежуточных записей	Заполняется записями create/update/delete	Не заполняется
Аудит	Промежуточные записи + история событий	Только история событий
Производительность	Немного медленнее (записывает промежуточные строки)	Немного быстрее
Отмена	Можно прервать перед применением	Необходимо отменять вручную

Когда использовать каждый вариант

Сценарий	Рекомендация
Первый импорт	Используйте стейджинг — проверьте, что создаётся, перед применением
Новый или изменённый маппинг	Используйте стейджинг — убедитесь, что преобразования полей дают корректный результат
Стабильный, хорошо проверенный маппинг	Пропустите стейджинг — нет необходимости проверять каждый запуск
Автоматизированные ежедневные синхронизации (cron)	Пропустите стейджинг — автоматические запуски не могут ждать проверки
Большая CMDB (10 000+ CI)	Пропустите стейджинг — избегает создания тысяч промежуточных строк
Среда с требованиями соответствия	Используйте стейджинг — сохранение полного аудита в промежуточной таблице

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

Режимы синхронизации и безопасность удалений

Режимы синхронизации

Режим	Создание	Обновление	Удаление	Подходит для
Добавление	Да	Да	Никогда	Первоначальный импорт, среды с низким риском
Консервативный	Да	Да	Только карточки, созданные при синхронизации	По умолчанию для текущих синхронизаций
Строгий	Да	Да	Все связанные карточки	Полное зеркало CMDB

Добавление никогда не удаляет карточки из Canopy, что делает его самым безопасным вариантом для первоначального импорта и сред, где Canopy содержит карточки, отсутствующие в ServiceNow.

Консервативный (по умолчанию) отслеживает, была ли каждая карточка изначально создана движком синхронизации. Только эти карточки могут быть автоматически архивированы, если они исчезнут из ServiceNow. Карточки, созданные вручную в Canopy или импортированные из других источников, никогда не затрагиваются.

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

Максимальный коэффициент удаления — предохранитель

В качестве предохранителя движок пропускает все удаления, если их количество превышает настроенный коэффициент:

удаления / всего_связанных > макс_коэффициент_удаления  ->  ПРОПУСТИТЬ ВСЕ УДАЛЕНИЯ

Пример с 10 связанными записями и порогом 50%:

Сценарий	Удаления	Коэффициент	Результат
3 CI удалены нормально	3 / 10 = 30%	Ниже порога	Удаления выполняются
6 CI удалены одновременно	6 / 10 = 60%	Выше порога	Все удаления пропущены
SNOW возвращает пусто (сбой)	10 / 10 = 100%	Выше порога	Все удаления пропущены

Это предотвращает катастрофическую потерю данных от изменений запроса фильтрации, временных сбоев ServiceNow или неправильно настроенных имён таблиц.

Лучшая практика: Держите коэффициент удаления на уровне 50% или ниже для таблиц с менее чем 100 записями. Для больших таблиц (1000+) можно безопасно установить 25%.

Настройка	Значение
Тип карточки	Application
Таблица SNOW	`cmdb_ci_business_app`
Направление	Двунаправленный
Режим	Консервативный
Фильтр	`active=true^install_status=1`

Поле Canopy	Поле SNOW	Направление	Преобразование	ID?
`name`	`name`	Turbo ведёт	Прямое	Да
`description`	`short_description`	Turbo ведёт	Прямое
`lifecycle.active`	`go_live_date`	Turbo ведёт	Дата
`lifecycle.endOfLife`	`retirement_date`	Turbo ведёт	Дата
`attributes.businessCriticality`	`busines_criticality`	Turbo ведёт	Карта значений
`attributes.hostingType`	`hosting_type`	Turbo ведёт	Прямое
`attributes.installStatus`	`install_status`	SNOW ведёт	Прямое
`attributes.ipAddress`	`ip_address`	SNOW ведёт	Прямое

Настройка	Значение
Тип карточки	ITComponent
Таблица SNOW	`cmdb_ci_server`
Направление	Двунаправленный
Режим	Консервативный
Фильтр	`active=true^hardware_statusNOT IN6,7`

Поле Canopy	Поле SNOW	Направление	Преобразование	ID?
`name`	`name`	Turbo ведёт	Прямое	Да
`description`	`short_description`	Turbo ведёт	Прямое
`attributes.manufacturer`	`manufacturer.name`	Turbo ведёт	Прямое
`attributes.operatingSystem`	`os`	SNOW ведёт	Прямое
`attributes.ipAddress`	`ip_address`	SNOW ведёт	Прямое
`attributes.serialNumber`	`serial_number`	SNOW ведёт	Прямое
`attributes.hostname`	`host_name`	SNOW ведёт	Прямое

Настройка	Значение
Тип карточки	ITComponent
Таблица SNOW	`cmdb_ci_spkg`
Направление	Двунаправленный
Режим	Консервативный
Фильтр	`active=true`

Поле Canopy	Поле SNOW	Направление	Преобразование	ID?
`name`	`name`	Turbo ведёт	Прямое	Да
`description`	`short_description`	Turbo ведёт	Прямое
`attributes.version`	`version`	SNOW ведёт	Прямое
`attributes.vendor`	`manufacturer.name`	Turbo ведёт	Прямое

Настройка	Значение
Тип карточки	Provider
Таблица SNOW	`core_company`
Направление	Двунаправленный
Режим	Добавление
Фильтр	`vendor=true`

Поле Canopy	Поле SNOW	Направление	Преобразование	ID?
`name`	`name`	Turbo ведёт	Прямое	Да
`description`	`notes`	Turbo ведёт	Прямое
`attributes.website`	`website`	Turbo ведёт	Прямое
`attributes.contactEmail`	`email`	SNOW ведёт	Прямое

Настройка	Значение
Тип карточки	Application
Таблица SNOW	`cmdb_ci_business_app`
Направление	Canopy -> ServiceNow
Режим	Добавление

Поле Canopy	Поле SNOW	Направление	Преобразование	ID?
`name`	`name`	SNOW ведёт	Прямое	Да
`attributes.businessCriticality`	`u_ea_business_criticality`	Turbo ведёт	Карта значений
`attributes.functionalSuitability`	`u_ea_functional_fit`	Turbo ведёт	Карта значений
`attributes.technicalSuitability`	`u_ea_technical_fit`	Turbo ведёт	Карта значений

Справочник типов преобразований

Прямое (по умолчанию)

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

Карта значений

Преобразует перечисляемые значения между системами. Настройте с помощью JSON-маппинга:

{
  "mapping": {
    "1": "missionCritical",
    "2": "businessCritical",
    "3": "businessOperational",
    "4": "administrativeService"
  }
}

Маппинг автоматически обращается при push из Canopy в ServiceNow.

Формат даты

Обрезает значения datetime ServiceNow (2024-06-15 14:30:00) до формата только даты (2024-06-15). Используйте для дат фаз жизненного цикла, где время несущественно.

Логическое

Конвертирует между строковыми булевыми значениями ServiceNow ("true", "1", "yes") и нативными булевыми значениями.

Лучшие практики безопасности

Управление учётными данными

Практика	Детали
Шифрование при хранении	Все учётные данные шифруются через Fernet (AES-128-CBC), производный от `SECRET_KEY`. При ротации `SECRET_KEY` повторно введите все учётные данные ServiceNow.
Минимальные привилегии	Создайте выделенную сервисную учётную запись SNOW с доступом только на чтение к конкретным таблицам. Предоставляйте доступ на запись только при использовании push-синхронизации.
OAuth 2.0 предпочтителен	Basic Auth отправляет учётные данные при каждом вызове API. OAuth использует краткосрочные токены с ограничениями области.
Ротация учётных данных	Ротируйте пароли или секреты клиента каждые 90 дней.

Сетевая безопасность

Практика	Детали
HTTPS обязателен	HTTP URL отклоняются при валидации. Все подключения должны использовать HTTPS.
Валидация имён таблиц	Имена таблиц проверяются по `^[a-zA-Z0-9_]+$` для предотвращения инъекций.
Валидация sys_id	Значения sys_id проверяются как 32-символьные шестнадцатеричные строки.
Список разрешённых IP	Настройте контроль доступа по IP в ServiceNow, чтобы разрешить только IP-адрес вашего сервера Canopy.

Контроль доступа

Практика	Детали
Защита RBAC	Конечные точки ServiceNow только для чтения требуют разрешения `servicenow.view`; все изменения требуют `servicenow.manage`.
Аудит	Все изменения, созданные синхронизацией, публикуют события с `source: "servicenow_sync"`, видимые в истории карточки.
Без раскрытия учётных данных	Пароли и секреты никогда не возвращаются в ответах API.

Контрольный список для производства

Выделенная сервисная учётная запись ServiceNow (не личная)
OAuth 2.0 с грантом клиентских учётных данных
График ротации учётных данных (каждые 90 дней)
Сервисная учётная запись ограничена только маппированными таблицами
Настроен список разрешённых IP ServiceNow для сервера Canopy
Максимальный коэффициент удаления 50% или ниже
Мониторинг запусков синхронизации на необычные ошибки или удаления
Запросы фильтрации включают active=true как минимум

Руководство по эксплуатации

Последовательность начальной настройки

Создайте сервисную учётную запись ServiceNow с минимальными требуемыми ролями
Проверьте сетевое подключение (может ли Canopy достичь SNOW через HTTPS?)
Создайте подключение в Canopy и протестируйте его
Убедитесь, что типы метамодели имеют все поля для синхронизации
Создайте первый маппинг в режиме ДОБАВЛЕНИЯ с включённым стейджингом
Запустите первую pull-синхронизацию — проверьте промежуточные записи
Примените промежуточные записи
Проверьте импортированные карточки в Реестре
При необходимости скорректируйте маппинги полей, повторите
Переключите маппинг в КОНСЕРВАТИВНЫЙ режим для текущего использования
После нескольких успешных запусков включите «Пропустить стейджинг» для автоматизации

Текущие операции

Задача	Частота	Как
Запуск pull-синхронизации	Ежедневно или еженедельно	Панель синхронизации > кнопка Pull (или cron)
Проверка статистики синхронизации	После каждого запуска	Проверьте количество ошибок/удалений
Тестирование подключений	Ежемесячно	Нажмите кнопку тестирования на каждом подключении
Ротация учётных данных	Ежеквартально	Обновите в обеих системах — SNOW и Canopy
Проверка карты идентификаторов	Ежеквартально	Проверьте осиротевшие записи через статистику синхронизации
Аудит истории карточек	По необходимости	Фильтруйте события по источнику `servicenow_sync`

Настройка автоматических синхронизаций

Синхронизации можно запускать через API для автоматизации:

# Ежедневная pull-синхронизация в 2:00
0 2 * * * curl -s -X POST \
  -H "Authorization: Bearer $TURBOEA_TOKEN" \
  "https://canopy.company.com/api/v1/servicenow/sync/pull/$MAPPING_ID" \
  >> /var/log/canopy-sync.log 2>&1

Лучшая практика: Запускайте синхронизации в непиковые часы. Для больших таблиц CMDB (10 000+ CI) ожидайте 2-5 минут в зависимости от задержки сети и количества записей.

Планирование ёмкости

Размер CMDB	Ожидаемая длительность	Рекомендация
< 500 CI	< 30 секунд	Синхронизация ежедневно, стейджинг опционален
500-5000 CI	30с - 2 минуты	Синхронизация ежедневно, пропуск стейджинга
5000-20 000 CI	2-5 минут	Синхронизация ночью, пропуск стейджинга
20 000+ CI	5-15 минут	Синхронизация еженедельно, используйте фильтры для разделения

Устранение неполадок

Проблемы подключения

Симптом	Причина	Решение
`Connection failed: [SSL]`	Самоподписанный или просроченный сертификат	Убедитесь, что SNOW использует действительный сертификат публичного CA
`HTTP 401: Unauthorized`	Неверные учётные данные	Повторно введите имя пользователя/пароль; проверьте, не заблокирована ли учётная запись
`HTTP 403: Forbidden`	Недостаточно ролей	Предоставьте роли `itil` и `cmdb_read` сервисной учётной записи
`Connection failed: timed out`	Блокировка межсетевым экраном	Проверьте правила; добавьте IP Canopy в список разрешённых SNOW
Тест ОК, но синхронизация не работает	Разрешения на уровне таблицы	Предоставьте доступ на чтение к конкретной таблице CMDB

Проблемы синхронизации

Симптом	Причина	Решение
0 записей извлечено	Неверная таблица или фильтр	Проверьте имя таблицы; упростите запрос фильтрации
Все записи — «create»	Несовпадение идентификаторов	Отметьте `name` как идентификатор; проверьте совпадение имён
Много ошибок	Сбои преобразования	Проверьте промежуточные записи на сообщения об ошибках
Удаления пропущены	Коэффициент превышен	Увеличьте порог или исследуйте, почему CI исчезли
Изменения не видны	Кэш браузера	Принудительное обновление; проверьте историю карточки на наличие событий
Дублирование карточек	Несколько маппингов для одного типа	Используйте один маппинг на тип карточки на подключение
Push-изменения отклонены	Отсутствуют разрешения SNOW	Предоставьте роль `import_admin` сервисной учётной записи

Диагностические инструменты

# Предварительный просмотр маппинга записей (5 примеров, без побочных эффектов)
POST /api/v1/servicenow/mappings/{mapping_id}/preview

# Обзор таблиц экземпляра SNOW
GET /api/v1/servicenow/connections/{conn_id}/tables?search=cmdb

# Просмотр столбцов таблицы
GET /api/v1/servicenow/connections/{conn_id}/tables/cmdb_ci_business_app/fields

# Фильтрация промежуточных записей по действию или статусу
GET /api/v1/servicenow/sync/runs/{run_id}/staged?action=create
GET /api/v1/servicenow/sync/runs/{run_id}/staged?action=update
GET /api/v1/servicenow/sync/runs/{run_id}/staged?status=error

Справочник API (краткий)

Все конечные точки требуют Authorization: Bearer <token>. Конечные точки только для чтения требуют разрешения servicenow.view, изменяющие — servicenow.manage. Базовый путь: /api/v1.

Подключения

Метод	Путь	Описание
GET	`/servicenow/connections`	Список подключений
POST	`/servicenow/connections`	Создание подключения
GET	`/servicenow/connections/{id}`	Получение подключения
PATCH	`/servicenow/connections/{id}`	Обновление подключения
DELETE	`/servicenow/connections/{id}`	Удаление подключения + всех маппингов
POST	`/servicenow/connections/{id}/test`	Тестирование подключения
GET	`/servicenow/connections/{id}/tables`	Обзор таблиц SNOW
GET	`/servicenow/connections/{id}/tables/{table}/fields`	Список столбцов таблицы

Маппинги

Метод	Путь	Описание
GET	`/servicenow/mappings`	Список маппингов с маппингами полей
POST	`/servicenow/mappings`	Создание маппинга с маппингами полей
GET	`/servicenow/mappings/{id}`	Получение маппинга с маппингами полей
PATCH	`/servicenow/mappings/{id}`	Обновление маппинга (заменяет поля, если указаны)
DELETE	`/servicenow/mappings/{id}`	Удаление маппинга
POST	`/servicenow/mappings/{id}/preview`	Предварительный просмотр (5 примеров записей)

Операции синхронизации

Метод	Путь	Описание
POST	`/servicenow/sync/pull/{mapping_id}`	Pull-синхронизация (`?auto_apply=true` по умолчанию)
POST	`/servicenow/sync/push/{mapping_id}`	Push-синхронизация
GET	`/servicenow/sync/runs`	Список истории синхронизации (`?limit=20`)
GET	`/servicenow/sync/runs/{id}`	Детали запуска + статистика
GET	`/servicenow/sync/runs/{id}/staged`	Список промежуточных записей запуска
POST	`/servicenow/sync/runs/{id}/apply`	Применение ожидающих промежуточных записей

Зачем интегрировать ServiceNow с Canopy?​

Что вы можете сделать​

Архитектура интеграции​

Планирование интеграции​

1. Какие типы карточек нуждаются в данных из ServiceNow?​

2. Какая система является источником истины для каждого поля?​

3. Как часто следует синхронизировать?​

Шаг 1: Предварительные требования ServiceNow​

Создание сервисной учётной записи​

Сетевые требования​

Выбор метода аутентификации​

Шаг 2: Создание подключения​

Создание и тестирование​

Несколько подключений​

Шаг 3: Проектирование маппингов​

Создание маппинга​

Распространённые маппинги таблиц SNOW​

Примеры запросов фильтрации​

Шаг 4: Настройка маппингов полей​

Добавление полей​

Пути полей Canopy​

Поля идентификации — как работает сопоставление​

Шаг 5: Запуск первой синхронизации​

Запуск синхронизации​

Что происходит во время Pull-синхронизации​

Просмотр результатов синхронизации​

Рекомендуемая процедура первой синхронизации​

Понимание направления синхронизации и направления полей​

Уровень таблицы: направление синхронизации​

Уровень поля: направление​

Как они работают вместе — пример​

Лучшая практика: направление поля по типу данных​

Пропуск стейджинга — когда использовать​

Режим пропуска стейджинга​

Когда использовать каждый вариант​

Режимы синхронизации и безопасность удалений​

Режимы синхронизации​

Максимальный коэффициент удаления — предохранитель​

Рекомендуемая прогрессия​

Рекомендуемые сценарии по типам​

Сценарий 1: Приложения из CMDB (наиболее распространённый)​

Сценарий 2: ИТ-компоненты (серверы)​

Сценарий 3: Программные продукты с отслеживанием EOL​

Сценарий 4: Вендоры / поставщики (двунаправленный)​

Сценарий 5: Передача оценок EA обратно в ServiceNow​

Справочник типов преобразований​

Прямое (по умолчанию)​

Карта значений​

Формат даты​

Логическое​

Лучшие практики безопасности​

Управление учётными данными​

Сетевая безопасность​

Контроль доступа​

Контрольный список для производства​

Руководство по эксплуатации​

Последовательность начальной настройки​

Текущие операции​

Настройка автоматических синхронизаций​

Планирование ёмкости​

Устранение неполадок​

Проблемы подключения​

Проблемы синхронизации​

Диагностические инструменты​

Справочник API (краткий)​

Подключения​

Маппинги​

Операции синхронизации​