Настройки узлов и пользователей

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

Настройки можно читать по подразделению, команде или пользователю. Для узла API возвращает роли участников и дополнительные настройки, а для пользователя — подразделения, которые нужно учитывать в бизнес-процессах и отчетах. Результат также позволяет отличить выключенную настройку от отсутствующей и определить, какие подразделения изменились.

Получить сервисы настроекПолучить сервисы настроек

Выберите сервис по исходным данным. Модуль предоставляет два сервиса:

• Bitrix\HumanResources\Public\Service\NodeSettingsService — читает настройки полномочий и дополнительные настройки подразделений и команд, изменяет поддерживаемые настройки типа boolean.

• Bitrix\HumanResources\Public\Service\UserSettingsService — возвращает подразделения, которые участвуют в бизнес-процессах и отчетах пользователя.

Перед получением сервисов подключите модуль humanresources. Контейнер Bitrix\HumanResources\Public\Service\Container предоставляет методы для получения NodeSettingsService и UserSettingsService. Для сценария с настройками узла и пользователя вызовите оба метода.

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

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

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

$nodeSettingsService = Container::getNodeSettingsService();
$userSettingsService = Container::getUserSettingsService();

В следующих примерах модуль уже подключен. Каждый блок объявляет краткое имя класса Container с помощью use, получает нужный сервис и задает входные идентификаторы. Числа в примерах условные. Перед запуском замените их идентификаторами своих подразделений, команд, пользователей и структур.

API настроек позволяет изменять только настройки WelcomeBox, AutoCheckin, DayStartCheckinRequired и AiReports. Полномочия, исключения команд и пользовательские исключения доступны только для чтения. Эта граница помогает сразу выбрать поддерживаемый сценарий и не искать отсутствующие методы записи.

Определить участников бизнес-процессов и отчетовОпределить участников бизнес-процессов и отчетов

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

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

Используйте NodeSettingsService, когда нужно определить роли для конкретного подразделения или команды. Сервис возвращает коллекции значений NodeSettingsAuthorityType, а параметр $nodeId принимает идентификатор нужного узла.

Получить полномочия для бизнес-процессовПолучить полномочия для бизнес-процессов

Когда код обрабатывает один известный узел, вызовите getBusinessProcAuthoritySettings(). Метод возвращает роли, которые согласуют бизнес-процессы этого узла. Если сервис не находит настройку, он возвращает пустую коллекцию.

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

use Bitrix\HumanResources\Public\Service\Container;

// Идентификатор подразделения или команды
$nodeId = 10;
$nodeSettingsService = Container::getNodeSettingsService();
$authorities = $nodeSettingsService->getBusinessProcAuthoritySettings($nodeId);

if ($authorities->count() === 0)
{
    // Для узла не сохранены полномочия для бизнес-процессов
}

Когда нужно проверить несколько узлов, передайте их одним массивом в getBusinessProcAuthoritySettingsForNodes(). Один вызов возвращает настройки всех нужных узлов, поэтому не нужно обращаться к сервису отдельно для каждого идентификатора.

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

Пример. Код запрашивает полномочия трех узлов и проверяет, сохранили ли настройку для узла 20.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификаторы подразделений или команд
$nodeIds = [10, 20, 30];

$nodeSettingsService = Container::getNodeSettingsService();
$authoritiesByNode = $nodeSettingsService
    ->getBusinessProcAuthoritySettingsForNodes($nodeIds);

if (!isset($authoritiesByNode[20]))
{
    // Для узла 20 не сохранены полномочия для бизнес-процессов
}

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

Получить полномочия для отчетовПолучить полномочия для отчетов

Чтобы определить получателей отчетов одного узла, вызовите getReportsAuthoritySettings(). Метод возвращает соответствующие роли. Если сервис не находит настройку, он подставляет NodeSettingsAuthorityType::DepartmentHead. Это значение по умолчанию, а не признак сохраненной настройки.

Пример. Код получает роли получателей отчетов для подразделения с идентификатором 10.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификатор подразделения или команды
$nodeId = 10;
$nodeSettingsService = Container::getNodeSettingsService();
$authorities = $nodeSettingsService->getReportsAuthoritySettings($nodeId);

Для списка узлов используйте getReportsAuthoritySettingsForNodes(). Метод возвращает все переданные идентификаторы, поэтому результат можно обработать без дополнительных проверок ключей. Если настройка узла отсутствует, сервис добавляет для него коллекцию с NodeSettingsAuthorityType::DepartmentHead.

Пример. Код получает роли получателей отчетов для узлов 10 и 20. В результате есть ключ для каждого идентификатора из $nodeIds, даже если настройку для него не сохраняли.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификаторы подразделений или команд
$nodeIds = [10, 20];

$nodeSettingsService = Container::getNodeSettingsService();
$authoritiesByNode = $nodeSettingsService
    ->getReportsAuthoritySettingsForNodes($nodeIds);

$nodeTenAuthorities = $authoritiesByNode[10];
$nodeTwentyAuthorities = $authoritiesByNode[20];

Пустой входной массив дает пустой результат.

Учесть различия значений по умолчаниюУчесть различия значений по умолчанию

Отсутствие настройки влияет на бизнес-процессы и отчеты по-разному. Учитывайте это различие, чтобы не принять значение отчетов по умолчанию за явно сохраненное.

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

Выбрать роль для настройки узлаВыбрать роль для настройки узла

Выберите значение NodeSettingsAuthorityType по роли участника, которая должна согласовать бизнес-процессы или получить отчеты. Таблица помогает сопоставить значение перечисления со структурной ролью.

Чтобы проверить наличие конкретной роли, передайте значение перечисления в метод коллекции has(). Метод сравнивает значения строго. Для перебора всех ролей получите массив методом getItems().

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

use Bitrix\HumanResources\Public\Service\Container;
use Bitrix\HumanResources\Type\NodeSettingsAuthorityType;

// Идентификатор подразделения или команды
$nodeId = 10;
$nodeSettingsService = Container::getNodeSettingsService();
$authorities = $nodeSettingsService->getReportsAuthoritySettings($nodeId);

if ($authorities->has(NodeSettingsAuthorityType::DepartmentHead))
{
    // Руководитель подразделения получает отчеты узла
}

Учесть работу пользователя в нескольких подразделенияхУчесть работу пользователя в нескольких подразделениях

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

Получить подразделения для бизнес-процессовПолучить подразделения для бизнес-процессов

Чтобы получить подразделения для согласования бизнес-процессов пользователя, передайте его идентификатор $userId в getBusinessProcAuthoritySettings(). Метод возвращает массив с идентификаторами подразделений, которые остались после применения настройки BusinessProcExcludeNodes. Результат показывает, руководителей каких подразделений нужно учитывать при согласовании.

Пример. Код получает подразделения, руководители которых должны участвовать в бизнес-процессах пользователя с идентификатором 25.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификатор пользователя
$userId = 25;
$userSettingsService = Container::getUserSettingsService();
$businessProcNodeIds = $userSettingsService
    ->getBusinessProcAuthoritySettings($userId);

Если пользователь состоит в подразделениях 10, 20 и 30, а администратор добавил подразделение 30 в исключения, метод возвращает [10, 20]. Для пользователя из одного подразделения без исключений результат содержит идентификатор этого подразделения.

Получить подразделения для отчетовПолучить подразделения для отчетов

Чтобы определить получателей отчетов пользователя, передайте $userId в getReportsAuthoritySettings(). Метод возвращает идентификаторы подразделений, руководители которых должны получить отчеты, и не включает в результат узлы из настройки ReportsExcludeNodes.

Пример. Код получает подразделения, руководители которых должны получить отчеты пользователя с идентификатором 25.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификатор пользователя
$userId = 25;
$userSettingsService = Container::getUserSettingsService();
$reportNodeIds = $userSettingsService
    ->getReportsAuthoritySettings($userId);

Если пользователь состоит в подразделениях 10 и 30, а администратор добавил подразделение 30 в исключения, метод возвращает [10]. Вызывающий код продолжает определять получателей только для подразделения 10.

Получить исключения команд из отчетовПолучить исключения команд из отчетов

Перед формированием отчетов по командам получите списки пользователей, чьи отчеты не должны входить в отчет команды. Метод getTeamReportExceptionsSettingsForNodes() принимает идентификаторы команд и возвращает массив, где каждой команде соответствует список исключенных пользователей.

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

use Bitrix\HumanResources\Public\Service\Container;

// Идентификаторы команд
$teamIds = [40, 50];

$nodeSettingsService = Container::getNodeSettingsService();
$exceptionsByTeam = $nodeSettingsService
    ->getTeamReportExceptionsSettingsForNodes($teamIds);

$excludedUserIds = $exceptionsByTeam[40] ?? [];

Используйте список из результата, чтобы не включать отчеты этих пользователей в обработку команды. Если у команды нет исключений, ее ключ отсутствует в массиве, поэтому пример получает список через ?? []. Пустой входной список также дает пустой результат.

Работать с настройками типа boolean для подразделенийРаботать с настройками типа boolean для подразделений

Настройки типа boolean включают и выключают отдельные возможности подразделений. Выбор метода зависит от области задачи: один узел, все подразделения пользователя или подразделения, которыми он управляет. NodeSettingsService поддерживает четыре настройки:

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

• get<Setting>SettingsForMyDepartments() — прочитать настройки подразделений пользователя,

• get<Setting>SettingsForManagedDepartments() — прочитать настройки управляемых подразделений,

• set<Setting>ForMyManagedDepartments() — изменить настройки управляемых подразделений.

Вместо <Setting> подставьте название настройки из таблицы. Например, для AutoCheckin используйте getAutoCheckinSettingsForMyDepartments().

Сервис возвращает true для включенной настройки и false для выключенной. Значение null показывает, что сервис не нашел сохраненного значения. Не заменяйте null на false, если логика должна отличать явно выключенную возможность от настройки, которую еще не задавали.

Прочитать и изменить AutoCheckin для одного узлаПрочитать и изменить AutoCheckin для одного узла

Прочитайте текущее значение методом getAutoCheckinSetting(). Если настройку еще не задавали, передайте новое значение в setAutoCheckinSetting().

Пример. Код включает автоматический чекин, если подразделение 10 еще не имеет сохраненной настройки.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификатор подразделения
$nodeId = 10;
$nodeSettingsService = Container::getNodeSettingsService();
$autoCheckin = $nodeSettingsService->getAutoCheckinSetting($nodeId);

if ($autoCheckin === null)
{
    $nodeSettingsService->setAutoCheckinSetting($nodeId, true);
}

Если нужно показать или сравнить настройки нескольких узлов, используйте getAutoCheckinSettingsForNodes(). Метод возвращает каждый переданный идентификатор и добавляет null для узла без сохраненного значения. Результат содержит полную карту узлов, поэтому не нужны отдельные запросы и проверки отсутствующих ключей.

Пример. Код получает настройки автоматического чекина для подразделений 10 и 20, а затем проверяет, сохраняли ли значение для подразделения 20.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификаторы подразделений
$nodeIds = [10, 20];

$nodeSettingsService = Container::getNodeSettingsService();
$autoCheckinByNode = $nodeSettingsService
    ->getAutoCheckinSettingsForNodes($nodeIds);

if ($autoCheckinByNode[20] === null)
{
    // Для узла 20 настройку еще не сохраняли
}

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

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

• MEMBER_HEAD — руководитель,

• MEMBER_DEPUTY_HEAD — заместитель руководителя,

• MEMBER_EMPLOYEE — сотрудник.

Каждая непустая группа содержит настройки подразделений. Ключом служит идентификатор подразделения, а значением — true, false или null. Если для роли нет подразделений, сервис не добавляет ее ключ в результат, поэтому получайте группу через ?? [].

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

use Bitrix\HumanResources\Public\Service\Container;

// Идентификатор пользователя
$userId = 25;
$nodeSettingsService = Container::getNodeSettingsService();
$settingsByRole = $nodeSettingsService
    ->getWelcomeBoxSettingsForMyDepartments($userId);

$headSettings = $settingsByRole['MEMBER_HEAD'] ?? [];

foreach ($headSettings as $nodeId => $value)
{
    if ($value === null)
    {
        // Для подразделения нет сохраненного значения
    }
}

По такой же схеме работают методы для AutoCheckin, DayStartCheckinRequired и AiReports. Если пользователь не состоит в подразделениях или его роль не относится к стандартным ролям подразделения, сервис возвращает пустой массив.

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

Методы с суффиксом ForManagedDepartments подходят, когда нужно показать или обработать настройки подразделений, которыми пользователь управляет как руководитель или заместитель. Они возвращают настройки только непосредственно управляемых подразделений и не обходят дочерние узлы. В массиве результата ключ содержит идентификатор подразделения, а значение — true, false или null.

Пример. Код получает настройки AI-отчетов для подразделений, которыми пользователь 25 управляет в структуре 1.

use Bitrix\HumanResources\Public\Service\Container;

// Идентификаторы пользователя и структуры
$userId = 25;
$structureId = 1;

$nodeSettingsService = Container::getNodeSettingsService();
$settingsByNode = $nodeSettingsService
    ->getAiReportsSettingsForManagedDepartments(
        userId: $userId,
        structureId: $structureId,
    );

Параметр $structureId ограничивает поиск конкретной структурой. Передайте null или не указывайте параметр, чтобы использовать структуру по умолчанию. Если пользователь не управляет подразделениями в выбранной структуре, метод возвращает пустой массив.

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

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

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

use Bitrix\HumanResources\Public\Service\Container;

// Идентификаторы пользователя и структуры
$userId = 25;
$structureId = 1;

$nodeSettingsService = Container::getNodeSettingsService();
$affectedNodeIds = $nodeSettingsService
    ->setDayStartCheckinRequiredForMyManagedDepartments(
        userId: $userId,
        value: true,
        structureId: $structureId,
    );

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

Повторная запись AiReports = true вызывает событие OnAiReportsEnabled для каждой записи. Учитывайте этот побочный эффект, если обработчик события запускает внешние действия.

Определить участников AI-отчетовОпределить участников AI-отчетов

Когда последующая операция должна обработать пользователей подразделений с AI-отчетами, вызовите getUsersByMaxRoleWithAiReportsEnabled(). Сервис выбирает активных участников узлов, где AiReports имеет значение true, и относит каждого пользователя к группе с его наиболее приоритетной ролью.

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

• MEMBER_HEAD,

• MEMBER_DEPUTY_HEAD,

• MEMBER_EMPLOYEE.

Пример. Код получает пользователей с включенными AI-отчетами и разделяет их по наиболее приоритетной роли.

use Bitrix\HumanResources\Public\Service\Container;

$nodeSettingsService = Container::getNodeSettingsService();
$usersByRole = $nodeSettingsService
    ->getUsersByMaxRoleWithAiReportsEnabled();

$headUserIds = $usersByRole['MEMBER_HEAD'] ?? [];
$deputyUserIds = $usersByRole['MEMBER_DEPUTY_HEAD'] ?? [];
$employeeUserIds = $usersByRole['MEMBER_EMPLOYEE'] ?? [];

Сервис определяет наиболее приоритетную роль и добавляет пользователя только в одну группу. Он возвращает пустой массив, если ни одно подразделение не использует AI-отчеты или в таких подразделениях нет активных участников со стандартными ролями.

Проверить результат и обработать ошибкиПроверить результат и обработать ошибки

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

Методы не возвращают объект результата с ошибкой. При выполнении следующих методов вызывающий код может получить исключения слоя данных:

• Bitrix\HumanResources\Exception\WrongStructureItemException,

• Bitrix\Main\ArgumentException,

• Bitrix\Main\ObjectPropertyException,

• Bitrix\Main\SystemException.

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

Продолжить изучениеПродолжить изучение

• Узлы структуры компании

• Пользователи и иерархия

• Конструкторы выборок