Введение и базовые концепции

Структура компании в Битрикс24 объединяет подразделения, команды и пользователей. Модуль Управление персоналом humanresources предоставляет API, чтобы найти нужную часть структуры, получить ее участников и роли, определить руководителей и подчиненных или прочитать настройки.

API сгруппирован в сервисы по типам задач. Контейнер Bitrix\HumanResources\Public\Service\Container возвращает нужный сервис, а сервис выполняет операцию со структурой компании.

Основные объектыОсновные объекты

Структура компании — дерево подразделений и команд. В дереве есть корневой узел и связанные с ним дочерние узлы.

Узел — элемент структуры. Узел хранит положение в иерархии и относится к одному из двух типов: DEPARTMENT или TEAM.

Подразделение — узел типа DEPARTMENT. Подразделения образуют административную иерархию компании.

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

Участник — связь пользователя с узлом. Один пользователь может состоять в нескольких узлах, поэтому пользователя и участника нельзя считать одним объектом.

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

Как подключить модульКак подключить модуль

Перед обращением к API подключите модуль humanresources. Метод Loader::includeModule() возвращает false, если модуль недоступен.

use Bitrix\Main\Loader;

if (!Loader::includeModule('humanresources'))
{
    throw new \RuntimeException('Модуль humanresources не установлен');
}

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

Как получить сервис и узелКак получить сервис и узел

Пример. Код получает узел по известному внутреннему идентификатору. Число 42 — условный идентификатор. Замените его идентификатором узла из своего сценария.

use Bitrix\HumanResources\Public\Service\Container;
use Bitrix\Main\Loader;

if (!Loader::includeModule('humanresources'))
{
    throw new \RuntimeException('Модуль humanresources не установлен');
}

$nodeService = Container::getNodeService();

// Внутренний идентификатор узла структуры компании
$nodeId = 42;
$node = $nodeService->getById($nodeId);

if ($node === null)
{
    throw new \RuntimeException('Узел не найден');
}

echo $node->name;

Метод Container::getNodeService() возвращает сервис для чтения и поиска узлов. Метод getById() принимает внутренний идентификатор узла и возвращает объект Node или null, если узел не найден. После успешного запроса пример выводит название узла из свойства name.

Как выбрать API для задачиКак выбрать API для задачи

Для типовых операций используйте API из пространства имен Bitrix\HumanResources\Public. Если готового метода сервиса недостаточно для выборки данных, соберите запрос с помощью билдеров и фильтров Bitrix\HumanResources\Builder. Подробнее читайте в статье Выборки узлов и участников через билдеры.

Основные сценарииОсновные сценарии

Используйте материалы раздела в зависимости от задачи:

• Архитектура модуля и выбор сервиса — связи объектов, выбор сервиса и форматы результатов.

• Узлы структуры компании — получение, поиск и обход подразделений и команд.

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

• Выборки узлов и участников через билдеры — составные фильтры, обход иерархии, пагинация и сортировка через билдеры.

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

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

• Производительность и частые ошибки — ограничения выборок и диагностика пустых или неожиданных результатов.

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