Начало работы с организационной структурой

Доступ к организационной структуре можно получить через объект System:

const item = System.organisationStructure;

Создание элемента оргструктуры

Создать новый элемент оргструктуры можно с помощью метода OrganisationStructure.createItem:

const item = System.organisationStructure.createItem('Директор по развитию', OrganisationStructureItemType.Position);

В данном примере Директор по развитию — название создаваемого элемента оргструктуры, а OrganisationStructureItemType.Position — тип элемента.

Элемент может быть одного из трех типов:

• OrganisationStructureItemType.Department — отдел. Отдел состоит из неограниченного количества сотрудников и одного начальника отдела. Внутри отдела можно создавать группы сотрудников и отдельные должности.
• OrganisationStructureItemType.Group — группа сотрудников. Группа сотрудников определяет группу пользователей с общими должностными обязанностями.
• OrganisationStructureItemType.Position — должность. На должность может быть назначен только один сотрудник. Примеры должностей: директор, главный бухгалтер, секретарь и т. д.

Добавление элемента оргструктуры

Добавить вновь созданный элемент в существующую организационную структуру (к заданному родителю) можно с помощью метода OrganisationStructureItem.addChild:

const tree = await System.organisationStructure.fetchTree();
tree.getRoot().addChild(item);

Получение текущей оргструктуры

Текущее дерево организационной структуры можно загрузить с помощью метода OrganisationStructure.fetchTree:

const tree = await System.organisationStructure.fetchTree();

Найти элемент оргструктуры

Найти элемент оргструктуры можно по его названию с помощью метода OrganisationStructureTree.find.
Будет возвращен первый найденный элемент или undefined, если такого элемента нет.

    // Получаем текущую оргструктуру
    const tree = await System.organisationStructure.fetchTree();
    // Находим элемент с названием Генеральный директор и записываем в переменную
    const ceo = tree.find('Генеральный директор');

Найти корневой элемент оргструктуры

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

const root = tree.getRoot();

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

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

     // Записываем в переменную текущую оргструктуру
     const tree = await System.organisationStructure.fetchTree();
     // Записываем в переменную массив возвращенных ошибок
     const errs = await tree.validate();
     // Ставим условие, что если массив ошибок включает более 0 элементов,
     if (errs.length > 0) {
          // то они должны быть записаны в строку с использованием метода `join`; указываем разделитель (запятая с пробелом)
          Context.data.errors = errs.join(', ');
     } else {
          // Если массив ошибок пустой, то в строку должно быть записано соответствующее сообщение
          Context.data.errors = 'Оргструктура составлена правильно';
     }

Ошибки, которые могут быть возвращены

• group must not contain childs — у группы не может быть дочерних элементов;
• root must be an 'POSITION' — корневой элемент должен иметь тип Должность;
• parent required — у элемента должен быть родительский элемент;
• department must contain 1 child, got — у отдела должен быть хотя бы один дочерний элемент;
• department child must be 'POSITION', got — дочерний элемент отдела должен иметь тип Должность (начальник отдела); у отдела всегда должен быть начальник;
• invalid sort/duplicate sort — некорректная сортировка/дублирующаяся сортировка;
• cycle in tree — найден цикл в дереве;
• duplicate id — дублирующийся ID;
• unknown parent — неизвестен/не найден родительский элемент;
• root not found — не найден корневой элемент оргструктуры.

Сохранение дерева в качестве текущей организационной структуры

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

const errs = await System.organisationStructure.save(tree);
if (errs.length === 0) {
     // Успешно сохранено
}

В данном примере tree — сохраняемое дерево.

Найти все отделы в оргструктуре и записать их в поле типа «Категория»

    // Находим все отделы в оргструктуре по фильтру, который использует тип элемента `DEPARTMENT` — Отдел
    const deps = await System.organisationStructure.search().where(i => i.type.like('DEPARTMENT')).all();
    // Запускаем цикл, в котором проходим по каждому из найденных элементов и задаем начальное значение счётчика для генерации уникального кода
    let counter = 1;
    for (let item of deps) {
    // Записываем значения поля типа Категория в переменную `variants`
        const variants = Context.fields.kategoriya.data.variants;
        // Если у элемента оргструктуры есть название,
        if (item.data.name) {
        // то делаем в поле типа Категория новую запись, присваивая ей уникальный код и имя; увеличиваем значение счётчика
            variants.push({ code: 'item'+counter.toString(), name: item.data.name });
        }
        counter ++;
    }