Getting started with the organizational chart

You can access the organizational chart using the System object:

const item = System.organisationStructure;

Create an org chart item

You can create a new org chart item using the OrganisationStructure.createItem method:

const item = System.organisationStructure.createItem('Director of Development', OrganisationStructureItemType.Position);

In this example, Director of Development is the name of the org chart item that needs to be created, and OrganisationStructureItemType.Position is the type of this org chart item.

There are three types of org chart items:

OrganisationStructureItemType.Department is a department. A department consists of an unlimited number of employees and the head of the department. Inside a department, you can create groups of employees and distinct positions.
OrganisationStructureItemType.Group is a group of employees. A group of employees is a group of users with the same roles and responsibilities.
OrganisationStructureItemType.Position is a position. Only one user can be assigned to a position. Examples of positions: director, chief accountant, secretary, etc.

Add an org chart item

To add a new org chart item into an existing organizational chart (to a specified parent), you can use the OrganisationStructureItem.addChild method:

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

Get the current organizational chart

You can get the current org chart tree using the OrganisationStructure.fetchTree method:

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

Find an org chart item

You can find an org chart item by its name using the OrganisationStructureTree.find method. The method will return the item or undefined if no such item exists.

    // Getting the current org chart tree
    const tree = await System.organisationStructure.fetchTree();
    // Finding the item names CEO and writing it to a variable
    const ceo = tree.find('CEO');

Find the root item of the org chart

You can get the root item of the org chart, that is, the highest element in the hierarchy, using the OrganisationStructureTree.getRoot method:

const root = tree.getRoot();

You can check the org chart for errors and view the errors found in the process using the OrganisationStructureTree.validate method. If validation fails, the method returns an array with errors. If validation is successful, an empty array is returned. We recommend to validate the org chart when you modify it using scripts, as this can cause errors, unlike visual editing in the Administration workspace.

     // Writing the current org chart into a variable
     const tree = await System.organisationStructure.fetchTree();
     // Writing an array or errors returned after validation into a variable
     const errs = await tree.validate();
     // Setting a condition: if the array of errors includes more than 0 items,
     if (errs.length > 0) {
          // these items need to be written to a string with the `join` method; a separator is set
          Context.data.errors = errs.join(', ');
     } else {
          // If the array of errors is empty, the corresponding message needs to be passed to the string
          Context.data.errors = 'The org chart is correct';
     }

Possible errors

“group must not contain childs”: a group of employees cannot have child items.
“root must be an 'POSITION'”: the root item has to be of the Position type.
“parent required”: an item needs to have a parent item.
“department must contain 1 child, got”: a department needs to have at least one child item.
“department child must be 'POSITION', got”: at least one child item of a department needs to be of the Position type (head of the department); a department must have a head.
“invalid sort/duplicate sort”: inappropriate or duplicate sorting.
“cycle in tree”: a loop has been found in the org chart tree.
“duplicate id”: items with duplicate IDs have been found.
“unknown parent”: the parent of an item is unknown or not found.
“root not found”: the root item is not found.

Save a tree as the current org chart

The method allows you to save the configured org chart tree as the current organizational chart. Before saving, the org chart will be automatically validated (see the description of validation in the example above).

const errs = await System.organisationStructure.save(tree);
if (errs.length === 0) {
     // Saved successfully
}

In this example, tree is the org chart that needs to be saved.

Find all departments and write them to a Category type field

    // Finding all departments in the org chart using the DEPARTMENT item type as a filter
    const deps = await System.organisationStructure.search().where(i => i.type.like('DEPARTMENT')).all();
    // Iterating through each of the items and setting the starting value of the counter to generate uniqure codes
    let counter = 1;
    for (let item of deps) {
    // Writing Category field type values into the `variants` variable
        const variants = Context.fields.category1.data.variants;
        // If the org chart item has a name,
        if (item.data.name) {
        // a new entry appears in the Category type field. It is assigned a name and a unique code. The counter’s value is increased
            variants.push({ code: 'item'+counter.toString(), name: item.data.name });
\t\t}
\t\tcounter ++;
\t}