Архитектура модуля и выбор сервиса

Публичный API модуля humanresources разделяет структуру компании, ее узлы, связи участников и роли. Выбор конкретного сервиса зависит от исходных данных и от того, что нужно получить. По идентификатору подразделения можно найти узел или его участников, а по идентификатору пользователя — подразделения, команды и управленческие связи.

Готовые методы сервисов подходят для типовых задач: найти узел, получить участников или определить руководителя. Для выборки с несколькими условиями модуль предоставляет билдер — объект, который объединяет фильтры, направление и глубину обхода, сортировку и другие параметры. Связи объектов и различия между сервисами и билдерами помогают выбрать API для своей задачи.

Как связаны структура, узлы, участники и роли

Данные структуры компании образуют последовательность связанных объектов:

Структура
└── Узел
    ├── Дочерний узел
    └── Участник
        ├── Пользователь
        └── Роль в узле

Структура задает границы дерева и содержит корневой узел. Остальные узлы связаны с родительскими и дочерними узлами. Идентификатор структуры ограничивает запрос одним деревом, а идентификатор узла выбирает элемент внутри этого дерева.

Как тип узла влияет на выборку

Узел — это объект Node, который представляет подразделение или команду в структуре компании. Узел хранит свое положение в дереве и относится к одному из типов:

  • DEPARTMENT — подразделение административной структуры,

  • TEAM — команда.

Тип узла определяет состав выборки и доступный сервис пользователей. Если запрос должен работать и с подразделениями, и с командами, передайте нужные типы в аргументе nodeTypes выбранного метода NodeService. Значение по умолчанию зависит от метода. Например, findAll() выбирает подразделения, а findChildrenByNodeIds() — подразделения и команды.

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

Как участник связывает пользователя с узлом

Пользователь и участник структуры — разные объекты. Пользователь представляет учетную запись, а объект NodeMember — связь пользователя с конкретным узлом. Один пользователь может состоять в нескольких узлах и иметь отдельную роль в каждой связи.

Роль определяет положение участника внутри узла. Через роли API различает руководителя, заместителя и сотрудника. Для поиска состава узла, связей пользователя и участников с нужной ролью используйте сервисы участников. Подробные сценарии приведены в статье Участники и роли в структуре компании.

Что возвращают сервисы

Сервисы возвращают отдельные объекты Node и NodeMember, коллекции этих объектов или массивы. Формат результата и способ его проверки зависят от конкретного метода.

Результат

Когда используется

Как проверять

Node

Найден один узел

Проверить результат на null, если метод допускает отсутствие узла

NodeCollection

Найден набор узлов

Проверить количество элементов или перебрать коллекцию

NodeMember

Найдена одна связь пользователя с узлом

Проверить результат на null, если связь может отсутствовать

NodeMemberCollection

Найден набор связей участников

Проверить количество элементов или перебрать коллекцию

Индексированный массив

Метод возвращает список идентификаторов или объектов

Проверить массив на пустоту и учитывать порядок, если метод сохраняет порядок элементов

Ассоциативный массив

Результат сгруппирован или индексирован по идентификатору

Обращаться к значению по ключу и проверять наличие ключа

Не заменяйте проверку null проверкой пустой коллекции. Иначе код может принять отсутствие одного объекта за результат множественной выборки или вызвать метод коллекции у значения null.

Выбор сервиса

После подключения модуля humanresources получайте сервисы через Bitrix\HumanResources\Public\Service\Container. Выбирайте сервис по исходному объекту и ожидаемому результату. Общие сервисы работают с узлами и связями, а сервисы подразделений и команд — с соответствующей управленческой иерархией.

Задача

Метод контейнера

Сервис

Найти узел, корневой узел, родителей или потомков

getNodeService()

NodeService

Найти связи участников по узлам, пользователям или ролям

getNodeMemberService()

NodeMemberService

Связать выборку пользователей с данными их узлов

getUserService()

Общий Node\UserService

Проверить роль пользователя, получить руководителей, подчиненных или управляемые узлы в административной структуре

getUserDepartmentService()

Department\UserService

Проверить роль пользователя, получить руководителей, подчиненных, управляемые узлы или цепочки команд

getUserTeamService()

Team\UserService

Прочитать настройки полномочий узлов

getNodeSettingsService()

NodeSettingsService

Получить настройки или исключения пользователя

getUserSettingsService()

UserSettingsService

Для фильтрации через NodeService передайте параметр structureAction в метод, который принимает этот параметр. Значение null отключает фильтр по действию. Подходящий метод выберите в разделе Настроить выборку под задачу.

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

Сервисы подразделений и команд не взаимозаменяемы: каждый из них предоставляет операции для своего типа узла. Общий Node\UserService используйте для связей пользователя с узлами, когда логика не зависит от типа узла.

Как выбрать между сервисом и билдером

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

Билдер формирует составную выборку. Используйте NodeDataBuilder для узлов и NodeMemberDataBuilder для связей участников, если нужно объединить несколько условий:

  • тип и идентификаторы узлов,

  • направление и глубину обхода иерархии,

  • активность и доступное действие,

  • роли и идентификаторы пользователей,

  • пагинацию, набор полей и сортировку.

Билдеры возвращают те же объекты Node, NodeMember и соответствующие коллекции. О составе фильтров и примерах читайте в статье Выборки узлов и участников через билдеры.

Как читать данные от узла и от пользователя

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

От узла к участникам

Начинайте с узла, если известны подразделение или команда. Сначала получите объект Node через NodeService, затем запросите связи участников через NodeMemberService, Department\UserService или Team\UserService.

Такое направление подходит для следующих задач:

  • получить состав подразделения или команды,

  • отобрать участников по роли,

  • найти руководителя узла,

  • перейти к дочерним узлам и собрать данные по части дерева.

От пользователя к узлам

Начинайте с пользователя, если нужно определить его положение в структуре. Общий Node\UserService находит связи пользователя с узлами. Сервисы подразделений и команд дополняют этот сценарий операциями управленческой иерархии.

Такое направление подходит для следующих задач:

  • получить узлы пользователя,

  • определить его роль в узле,

  • найти руководителей или подчиненных,

  • получить узлы, которыми пользователь управляет,

  • построить цепочку управленческих связей.

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

Как значения по умолчанию меняют результат

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

В таблицах ниже методы без имени класса относятся к NodeService.

Типы узлов

Метод

Значение по умолчанию

Когда задать явно

Параметр nodeTypes

findAll() и findAllByMemberEntityId()

[NodeEntityType::DEPARTMENT]

Когда нужны команды или оба типа узлов

findChildrenByNodeIds()

[NodeEntityType::DEPARTMENT,
NodeEntityType::TEAM]

Когда нужен только один тип узла

findParentsByNodeId()

null

Когда автоматический выбор типов по исходному узлу не подходит

findAllByAccessCodes()

null

Когда выборку нужно ограничить подразделениями или командами

Активность

Метод

Значение по умолчанию

Когда задать явно

Параметр activeFilter

findAll(), findAllByAccessCodes() и findChildrenByNodeIds()

NodeActiveFilter::ONLY_GLOBAL_ACTIVE

Когда нужны узлы с другим состоянием активности

Параметр nodeActiveFilter

findAllByMemberEntityId()

NodeActiveFilter::ONLY_GLOBAL_ACTIVE

Когда нужны узлы с другим состоянием активности

Параметр active

NodeMemberFilter

true

Передайте null, чтобы отключить фильтр активности связей

Глубина обхода и структура

Метод

Значение по умолчанию

Когда задать явно

Параметр depthLevel

findParentsByNodeId() и findChildrenByNodeIds()

DepthLevel::FIRST

Когда нужна цепочка глубже ближайшего уровня

findAllByName()

DepthLevel::FULL

Когда поиск нужно ограничить частью ветви

Параметр structureId

NodeFilter

null

Передайте идентификатор, если запрос должен работать с конкретной структурой

Полные наборы параметров приведены в разделах Настроить выборку под задачу, Задать фильтр узлов и Задать фильтр участников. Рекомендации по объему результата читайте в статье Производительность и частые ошибки.

Ограничения публичного API

Публичный API модуля — классы и методы пространства имен Bitrix\HumanResources\Public. Сервисы из этого пространства выполняют типовые операции чтения. Некоторые сервисы также изменяют данные. Используйте такие операции, только когда в документации указан конкретный метод.

Публичный API не предоставляет универсальных методов для следующих операций:

  • создание, переименование, перемещение и удаление узлов,

  • произвольное изменение роли участника,

  • изменение состава команды,

  • выдача прав пользователю.

Билдеры пространства имен Bitrix\HumanResources\Builder\Structure не относятся к публичному API. Они входят в отдельный поддерживаемый API для составных выборок. Билдеры только читают данные: они не создают, не изменяют и не удаляют узлы, связи участников или роли.

Методы публичного API и билдеры используют объекты, типы и перечисления из других пространств имен модуля. Считайте их частью поддерживаемого контракта, только если они описаны в этом разделе как параметры, результаты или элементы выборки. Остальные классы относятся к внутренней реализации и могут изменяться без предупреждения.

Как выбрать способ обращения к API

  1. Определите исходный объект: структуру, узел, связь участника или пользователя.

  2. Выберите сервис для готовой операции или билдер для составной выборки.

  3. Вызовите нужный метод с учетом его значений по умолчанию.

  4. Проверьте тип результата: null, отдельный объект, коллекция или массив.

Такой порядок отделяет навигацию по дереву от работы с участниками и управленческой иерархией. Сервисы выполняют типовые задачи, а билдеры дополняют их составными выборками. Исходные данные определяют способ обращения к API, а формат результата — способ проверки.

Предыдущая
Введение и базовые концепции
Следующая
Узлы структуры компании