1С: Синхронизация оргструктуры – как устроен обработчик

Оргструктуру из 1С в UnSpot передаёт та же обработка, что и пользователей — «UnSpot SCIM Adapter»: в конце каждого запуска она отправляет одним запросом всё дерево организаций и подразделений. UnSpot сравнивает его с имеющимся деревом и создаёт, обновляет и удаляет подразделения. В статье описано, что именно передаётся, когда, по каким правилам UnSpot применяет присланное дерево и что происходит с подразделениями, которые созданы вручную. Как включить передачу — в статье 1С: Синхронизация оргструктуры – настройка интеграции; общие вопросы протокола, токена и журнала — в статье 1С: Синхронизация пользователей – как устроен обработчик.

Кратко

• В конце каждого запуска обработка отправляет всё дерево организаций и подразделений одним запросом PUT /OrgUnits.
• UnSpot сопоставляет подразделения по названию на каждом уровне и приводит своё дерево к присланному.
• Сотрудника к подразделению привязывает не этот запрос, а запросы создания и обновления пользователя.
• Обновление принимается не чаще раза в час; при больших деревьях (больше 500 подразделений) применяется в фоне.
• Незнакомое слово — загляните в раздел Термины статьи-обзора.

Важно знать

• Присланный список считается полным. Синхронизируемое подразделение, которого в нём нет, удаляется вместе с вложенными.
• Идентификаторы 1С в UnSpot не передаются. Переименование подразделения выглядит для UnSpot как удаление старого и создание нового.
• Пустой список удалит все синхронизируемые подразделения.

Как работает передача оргструктуры

Передача состоит из трёх частей:

1. Скрипт выбора данных в 1С собирает массив подразделений: путь, руководитель и описание каждого. Как он это делает — в статье 1С: Синхронизация оргструктуры – как устроен скрипт.
2. Обработка добавляет сотрудникам путь их подразделения и отправляет дерево запросом PUT /OrgUnits. Запрос выполняется после создания, обновления и удаления пользователей и после отложенного назначения руководителей.
3. UnSpot сопоставляет присланное дерево с имеющимся и приводит его в соответствие с 1С.

Обмен, как и при синхронизации пользователей, односторонний и по инициативе 1С: UnSpot к информационной базе не обращается. Протокол, адрес, аутентификация и таймаут те же, что у остальных запросов обработки, — см. статью 1С: Синхронизация пользователей – как устроен обработчик.

Что и когда передаётся

Запрос PUT /OrgUnits отправляется, если включён флажок «Оргструктура» (в режиме «Только обновление оргструктуры» форма включает его сама). Тело запроса — список items, по одному элементу на организацию или подразделение:

PUT /api/scim/OrgUnits
{
  "items": [
    { "path": "Компания", "manager": "ceo@company.ru", "description": "ООО Компания" },
    { "path": "Компания/Департамент продаж", "manager": "d.ivanov@company.ru", "description": null },
    { "path": "Компания/Департамент продаж/Отдел продаж", "manager": "a.sidorov@company.ru", "description": null }
  ]
}

PUT /api/scim/OrgUnits
{
  "items": [
    { "path": "Компания", "manager": "ceo@company.ru", "description": "ООО Компания" },
    { "path": "Компания/Департамент продаж", "manager": "d.ivanov@company.ru", "description": null },
    { "path": "Компания/Департамент продаж/Отдел продаж", "manager": "a.sidorov@company.ru", "description": null }
  ]
}

В примере «Компания» — организация. Головная организация попадает в путь, только если головных организаций в базе несколько; при одной пути начинаются с её подразделений или с обособленных подразделений.

Запрос передаёт всё дерево целиком, а не изменения: UnSpot считает присланный список полным описанием синхронизируемой части оргструктуры.

Кроме дерева, каждому сотруднику в запросах на создание и обновление передаётся путь его подразделения (поле orgUnit). Если флажок «Оргструктура» выключен, вместо пути передаётся только название подразделения (поле department), а запрос PUT /OrgUnits не отправляется.

Что учитывать. Руководитель подразделения передаётся вместе с деревом независимо от флажка «Менеджер»: этот флажок управляет только полем «Руководитель» у сотрудников.

Как UnSpot применяет присланное дерево

Лимит и очередь

UnSpot принимает обновление оргструктуры по SCIM не чаще одного раза в час на компанию. Ограничение устанавливается до разбора путей подразделений: запрос с неверной структурой данных (например, с пустым path или лишними полями) отклоняется раньше и лимит не расходует, а запрос с ошибкой в самих путях уже закроет возможность отправить следующий в течение часа. Повторный запрос раньше срока отклоняется ошибкой 400 с сообщением о том, что подразделения сейчас нельзя обновить (по-английски — «Unable to update organisation units. Please try again later.», по-русски — «Организационные подразделения не могут быть обновлены. Пожалуйста, попробуйте позже»).

Если в запросе больше 500 подразделений или в UnSpot уже больше 500 синхронизируемых подразделений, дерево применяется в фоне: UnSpot принимает запрос сразу, а изменения появляются позже. Результат применения в ответе обработке не возвращается.

Разбор пути

Из каждого пути UnSpot убирает пробелы и / по краям и строит дерево. Если у подразделения нет родителя в запросе, недостающие родители создаются по пути: подразделение Компания/Департамент/Отдел без отдельных элементов для «Компания» и «Департамент» создаст оба родителя. Пустой путь — ошибка формата, и весь запрос отклоняется.

Сопоставление с имеющимся деревом

Подразделения сопоставляются по названию на каждом уровне, без учёта регистра и лишних пробелов. Идентификаторы подразделений из 1С в UnSpot не передаются и не хранятся, поэтому переименование подразделения в 1С воспринимается как удаление старого подразделения и создание нового. Сотрудники при этом остаются в дереве: обработка сначала обновляет путь подразделения у сотрудников — UnSpot создаёт новое подразделение и переносит в него сотрудника, — и только потом отправляет дерево, после чего старое подразделение удаляется.

Создание и обновление

• Если подразделения с таким названием на этом уровне нет, оно создаётся с пометкой «синхронизируемое» вместе со всеми вложенными.
• Если есть — оно обновляется, когда изменились описание или руководитель либо когда подразделение было создано вручную и ещё не синхронизируемое. Ручное подразделение с совпавшим названием не дублируется, а переходит под управление 1С.
• Руководитель подразделения приводится к значению из запроса: по email ищется пользователь UnSpot; если email пустой или пользователя нет, руководитель подразделения снимается.

Удаление

После создания и обновления UnSpot удаляет лишнее:

• синхронизируемое подразделение, которого нет в присланном дереве, удаляется вместе со всеми вложенными подразделениями;
• подразделение, созданное вручную внутри синхронизируемого, удаляется, если его нет в присланном дереве;
• синхронизируемое подразделение внутри ручного, которое не перешло под управление 1С, удаляется;
• ручное подразделение верхнего уровня, которого нет в дереве, остаётся без изменений.

Сотрудники удаляемых подразделений не удаляются: у них очищается привязка к подразделению.

Что учитывать. Запрос с пустым списком подразделений (items: []) удалит все синхронизируемые подразделения. Включённый флажок «Оргструктура» при ошибке в скрипте выбора данных может привести именно к такому запросу — проверяйте число подразделений кнопкой «Сохранить и проверить».

Привязка сотрудников

Сотрудника привязывает к подразделению не запрос PUT /OrgUnits, а запросы на создание и обновление пользователя. По пути из поля orgUnit UnSpot находит подразделение (без учёта регистра) или создаёт всю цепочку недостающих подразделений с пометкой «синхронизируемое» и привязывает сотрудника. Пустое значение снимает привязку. Если одновременно переданы поля orgUnit и department, учитывается только orgUnit.

При выключенном флажке «Оргструктура» в поле department приходит только название подразделения, и для каждого уникального названия создаётся подразделение верхнего уровня. Если позже включить флажок, такие плоские подразделения, которых нет в дереве, будут удалены, а сотрудники — привязаны к подразделениям из дерева.

Что происходит с подразделением: сводка

Название, положение в дереве и описание синхронизируемого подразделения нельзя изменить вручную — UnSpot вернёт сообщение о том, что подразделение синхронизируется. Руководитель при каждом запуске приводится к значению из 1С.

Совместная работа с другими источниками

Дерево подразделений в UnSpot общее для всех источников, а удаление работает по пометке «синхронизируемое». Если дерево одновременно передают 1С и каталог (Active Directory и другие), каждый источник при запуске удаляет синхронизируемые подразделения, которых нет в его выгрузке, и источники перетирают друг друга. Выберите один источник оргструктуры — обычно 1С, где она полнее. Если дерево ведёт каталог, выключенного флажка «Оргструктура» мало: обработка всё равно передаёт сотрудникам название подразделения (поле department), и UnSpot переносит их в плоские подразделения (см. «Привязка сотрудников»). Чтобы 1С не трогала подразделения, используйте собственный скрипт, который не добавляет в структуру сотрудника ключи orgUnit и department (пустое значение тоже не годится: оно очищает подразделение), — см. 1С: Собственный скрипт – настройка интеграции.

Что записывается в журнал

Передача дерева отражается в журнале регистрации 1С двумя записями: количество выбранных подразделений на этапе подготовки (orgstructure: N) и запись оргструктура: N код: … с кодом и телом ответа UnSpot после отправки. Имя события — UnSpot#ггммдд. Подробнее о журнале — в статье 1С: Синхронизация пользователей – как устроен обработчик.

Связанные статьи

• 1С: Синхронизация оргструктуры – настройка интеграции — варианты передачи, флажки и проверка результата.
• 1С: Синхронизация пользователей – как устроен обработчик — протокол, передаваемые данные, токен и журнал.
• 1С: Синхронизация оргструктуры – как устроен скрипт — как скрипт строит дерево.
• 1С: Обзор интеграции — какие бывают интеграции с 1С и с чего начать.
• External API: Синхронизация пользователей по стандарту SCIM — описание SCIM-эндпоинтов, включая /OrgUnits.
• Подчинённость через оргструктуру — права руководителя подразделения.