Organisation structure
This feature is part of Moodle Workplace™, which is available through Moodle Certified Partners and Service Providers only.Overview
Organisation structure is a combination of three Moodle Workplace features: departments, positions and jobs. Departments specify where a user is operating; positions specify what a user's function is. You deploy department and position hierarchies to represent your organisation structure and define reporting lines by assigning job assignments to employees in any department with any position.
These concepts — frameworks, departments, positions and job assignments — allow you to adapt the software to your company structure, defining roles and hierarchies that automatically create reporting lines. You can further assign management rights and security permissions to each role. The following diagram provides a high-level overview of the organisational components:
User a has been assigned to job assignment C. Job assignment C is linked to Department 3.1.1 and Position 2.2. So, user a works in Department 3.1.1 and has Position 2.2.
User b, on the other hand, has been assigned to two job assignments: A and B. A is linked to Department 2.1 and Position 1.1; B is linked to Department 3.1.1 and has position Position 2. User b not only has two jobs in the organisation but is also likely to be the manager of user a! Do you see why this is the case? They both work in the same department, and the position of user a is located below the position of user b in the position framework.
An organisation structure belongs to a single tenant unless it has been configured in the Shared Space. By default, these organisation structures can be managed by users within the admin, tenant admin, or organisation structure manager roles, respectively.
Departments
Departments are organised into department frameworks. Frameworks act as containers for departments and are usually part of the same business entity, managed centrally, for example subdivisions of an organisation or countries in a multinational corporation.
Department structures can be hierarchical; however, it is more likely that only one of the structures in an organisation is hierarchical and the others are flat. See Example 1 for a typical scenario.
You access the management of organisations via Site administration > Users > Organisation structure or directly via the Organisation structure icon in the Workplace launcher. To set up a new department framework, select the + New framework button on the Departments tab and give the framework a descriptive Name. The ID number and Description fields are optional, but it is recommended that you fill those in.
The Locked option has been described in the Locking frameworks section further down.
To add departments to your department framework, select the + New department button to the right-hand side of the framework.
The input screen is identical to the one for adding department frameworks; only the heading is different and you have the ability to select the department parent.
To create sub-departments select the + icon next to a department; alternatively, use the built-in drag-and-drop functionality. To support complex organisation structures, drag-and-drop will be disabled if there are too many nodes.
The Jobs column displays the number of active and, in parentheses, the number of past job assignments. On the right-hand side, you will see the familiar Actions options for each department. Be careful when deleting a department, as this action cannot be undone. Note that you can only delete a department when no jobs are assigned to it or any sub-departments.
Having an organisation structure can help the tenant administrator to:
- Create dynamic rules that automatically do something based on a users position or department (for example, enrol them in an induction course)
- Create custom reports that have a specific department (or position) as their audience
- Filter/search lists of users within the organisation based on their position and department
- Create team managers by assigning jobs with "Manager" or "Department lead" positions to users
Positions
Positions are organised into position frameworks.
A position framework is effectively a container that related positions are grouped in, for example, subdivisions of an organisation or countries in a multinational corporation.
Position structures can be hierarchical; however, it is more likely that only one of the structures in an organisation is hierarchical and the others are flat. See Example 2 for a typical scenario.
Positions are structured in the same way as departments but have two additional properties, called Manager and Department lead. These are effectively permissions that are tied to their respective positions:
- Manager: This is the manager of anyone in a lower position, regardless of their department. This is not to be confused with Moodle's manager role!
- Department lead: This is the manager of anyone in a lower department or sub-department(s), regardless of their position.
You access the management of positions via Site administration > Users > Organisation structure or directly via the Organisation structure icon in the Workplace launcher. To set up a new position framework, select the + New framework button on the Positions tab and give the framework a descriptive Name. The ID number and Description fields are optional, but it is recommended that you fill those in.
To add positions to your position framework, select the + New position button to the right-hand side of the framework and give the position a descriptive Name. The ID number and Description fields are optional, but it is recommended that you fill those in. The Parent selection determines where in the hierarchy the position will be located.
For both the Manager and Department lead options, the following three permissions are available:
- Allocate users to programs/certifications: This setting grants permission to assign users to programs and certifications.
- View user reports: This option allows managers to view reports containing progress data about their staff. The list of staff can be narrowed down via the "Relation to the report viewer" condition.
- Receive notifications: If this option is selected, managers and department leads will receive alerts when configured appropriately.
Any user holding a Manager or Department lead position can display their team list on the dashboard. The list can further be narrowed down via the Organisation structure filter on the Teams tab.
To create sub-departments select the + icon next to a department; alternatively, use the built-in drag-and-drop functionality. To support complex organisation structures, drag-and-drop will be disabled if there are too many nodes.
The Jobs column displays the number of active and, in parentheses, the number of past job assignments. The Permissions column shows the manager and department lead permissions with icons. On the right-hand side, you will see the familiar Actions options for each position. Be careful when deleting a position, as this action cannot be undone. Note that you can only delete a position when no jobs are assigned to it or any positions.
Job Assignments (Jobs)
A job assignment connects a department and a position to a user and adds some auxiliary data, namely the start and end dates. Note that departments and positions need to be created to proceed with job assignments.
You access the management of jobs via Site administration > Users > Organisation structure or directly via the Organisation structure icon in the Workplace launcher. To create a new job assignment, select the + New job button on the Job assignments tab.
For each job, you have to Select users, a Position, and a Department. The default Start date option is today's date. It is not possible to leave Start date empty. The Start date and optional End date are used to decide whether a job is current or a past job.
If you select multiple users, you effectively create multiple jobs with the same position, department, start date, and end date for each employee.
Moodle Workplace deliberately does not perform any checks on overlapping jobs. This is to facilitate scenarios where one employee holds two or more positions in the same company (see Jobs actions).
In the sample screenshot, Arda Gotfrey has been promoted to the position of the UK Regional Manager, while Blythe Boshere is holding two simultaneous positions in Spain and Italy. Note that managers are assigned indirectly via positions, not directly to an employee.
Jobs actions
There are several actions you can perform on jobs via the action menu:
- Transfer this user to a new job: A new job assignment will be created and the current job will be set as finished one day before the new job starts.
- Set job as finished: Specify the End date for the job (default is today). The job only appears in the list of job assignments when the Show past jobs filter has been enabled.
- Assign another job for this user: A new job assignment will be created in addition to the current job.
- Edit dates: Modify or set the start and end date.
- Delete job completely: Remove the job assignment irrevocably. It is not recommended to delete job assignments unless they were created by mistake. Instead, you should set the job as finished to guarantee a complete and consistent job and learning history of all users.
Example 1: Organisation structure hierarchy based on departments
An organisation structure based on departments is modelled around where in the business staff are located, as opposed to what their function is. In this type of organisation, departments represent different divisions and teams inside the company. Their structure is almost always hierarchical.
The Regions department framework shown earlier is an example of such an organisation structure. The department hierarchy is usually accompanied by a position framework with staff and department leads. When users get assigned jobs in different departments, the manager(s) will see everybody from their department as their team.
Example 2: Organisation structure hierarchy based on positions
An organisation structure based on positions is modelled around what the functions of staff are, as opposed to where in the business they are located. In this type of organisation, the hierarchy is stored in a position tree.
In the position hierarchy shown earlier on, the CEO has the top position, and underneath are the COO, CTO, etc. The managers of several teams are located under the COO, and the members of these teams are positioned under these managers. This means that there might be project managers operating in different parts of the company, but while they are all part of a (different) local team, they report to the (same) COO.
In this structure, all positions with sub-positions have manager permissions that allow users who hold jobs in these positions to see everybody in the positions below them as their team. In our scenario, the CEO does not need to receive notifications from their subordinates but sees reports on them.
Example 3: Matrix Organisation
In a matrix organisation, some individuals report to more than one supervisor or manager. A software developer might report to the COO for their day-to-day activities and report to a project manager for a particular project she is working on. Conversely, a manager might be responsible for multiple cross-functional or cross-business teams.
When representing a matrix organisation, you can create completely isolated sets of departments; for example, one framework could be based on physical location and another on a product team within the organisation.
In the example screenshot, Aloysia Harrington holds the position of Lead Developer in the department UK. Additionally, she is the Project Manager for a customer called Romgen Pharma from March 1, 2020, until August 31, 2021. In her role as lead developer, she reports directly to the CTO; in her role as project manager, she reports to the colleague who is responsible for the customer.
Example 4: Co-Managers
The main idea behind co-managers is to have multiple managers in the same department, so they can 'manage' each other. To achieve this setup, the following configuration is recommended:
Create jobs in the same department for all co-managers and enable the Department lead permission for that department. There are four co-managers in the Editorial department in the example below - three Project Managers and one Lead Developer.
When logging in as any of the co-managers - here, Arleen Smaile - the My teams tab shows the other co-managers once the filter has been configured accordingly. Either set Show everybody reporting to me or narrow down the filtering further via the Customise... option, as done here.
Co-managers can now be managed in the same way as any other staff in the team.
Locked frameworks
Selecting the Locked option in the framework settings lets you restrict assigning jobs to certain users. If enabled, the following rules apply to the framework:
- Only users with the capability tool/organisation:assigninlocked are allowed to assign jobs in locked departments and positions.
- When a user has permission to manage departments or positions, but does not have permission to use locked frameworks, editing, adding or deleting of new items will not be allowed
- Locking departments or positions only affects the ability to assign jobs. Jobs in the locked departments or positions are still visible to everybody, for example, on "Organisation structure" pages (on Jobs, Departments and Positions tabs), in custom reports, on user profile pages, in the "My teams" blocks, etc
- A lock icon is shown next to locked department and position frameworks on the overview page
- The tool/organisation:assigninlocked capability can be used in the "tenant administrator" role, but is not allowed by default
To demonstrate the impact of the Locked feature, check out the following screenshots (disabled on the left, enabled on the right) when viewed by a tenant administrator:
A typical use case for the Locked framework feature is to award the Organisation structure manager capabilities to Tenant administrators, so they can create their own frameworks within their Tenants, without allowing them to use the frameworks of the Shared space.
Organisation structures can be created in the Shared Space to be used across all tenants.
Jobs can be assigned to users in their tenants using shared Departments and Positions, and when moving users between tenants, jobs using shared departments and positions will be moved along.
To create shared departments and positions, you need to access the Shared space from the tenant switch dropdown in the navigation bar. When inside the Shared Space, go to the Organisation structure tool, and create new departments and positions as usual. Note that there are no jobs in the Shared Space because users cannot belong to Shared space.
Once departments and positions have been created in the Shared space, they can be used from within all the other tenants. When creating a new job, they will be available in the departments and position selectors, and they can be assigned to the users in the tenant.
Automations and Integrations
Organisation structures are often managed by an existing HR system that has to synchronise data with other systems. Moodle Workplace offers two main options to automate this process:
CSV files
The Migration tool supports the creation of departments and positions in bulk. The Import wizard allows you to specify how columns in the CSV file should be mapped onto the properties of departments and positions.
Only the name field is required, that is, the smallest working CSV file can have only a single column.
Below a sample CSV file adding 10 nodes to the department hierarchy
id,code,parent,name,description,descriptionformat
1,SAL,,Sales,Sales department,1
2,SAD,SAL,Sales development,Sales development department,1
3,CSC,SAL,Customer Success,Customer Success department,1
4,EDI,,Editorial,Editorial department,400
5,AND,EDI,Art and design,Art and design department,1
6,PRO,EDI,Production,Production department,1
7,RNE,EDI,Research and Education,Research and Education department,1
8,MED,RNE,Medical advising,Medical advising department,1
9,MHR,RNE,Mental Health research,Mental Health research department,1
10,ONR,RNE,Oncology research,Oncology research department,1
The Upload users tool has been enhanced in Moodle Workplace to assign job assignments in bulk or change existing jobs (set the end date).
The Moodle CLI has been extended to support the import of CSV files for departments and positions. In order to import organisation elements into a department framework, the CLI syntax is as follows:
php admin/tool/wp/cli/import.php --file=<CSV file> --importer=”tool_organisation\\tool_wp\\importer\\departments_csv" --tenant=<tenant_id> --user=<user_id> --settings=<settings>
The following command imports the above sample department file into a new framework:
php admin/tool/wp/cli/import.php --file="/var/www/html/organisation1.csv" --importer="tool_organisation\\tool_wp\\importer\\departments_csv" --tenant=1 --user=admin --settings="{\"target_framework\":\"new\",\"hierarchy\":\"selected\",\"identifier\":\"code\",\"csvmapping:name\":\"name\",\"csvmapping:idnumber\":\"code\",\"csvmapping:description\":\"description\",\"csvdefault:descriptionformat\":\"1\",\"csvmapping:parentid\":\"parent\",\"conflict:csvdata:idnumberconflict:action\":\"increment\"}"
The following command imports the above sample department file into an existing framework with the idnumber "org2":
php admin/tool/wp/cli/import.php --file="/var/www/html/organisation1.csv" --importer="tool_organisation\\tool_wp\\importer\\departments_csv" --tenant=1 --user=admin --settings="{\"target_framework\":\"selected\",\"select_frameworkidnumber\":\"org2\",\"hierarchy\":\"selected\",\"identifier\":\"code\",\"csvmapping:name\":\"name\",\"csvmapping:idnumber\":\"code\",\"csvmapping:description\":\"description\",\"csvdefault:descriptionformat\":\"1\",\"csvmapping:parentid\":\"parent\",\"conflict:csvdata:idnumberconflict:action\":\"increment\"}"
For more information on the importing and exporting data can be found in the Migration CLI section.
Web services
The following web services have been introduced to handle organisations:
- tool_organisation_create_departments
- tool_organisation_create_job
- tool_organisation_create_positions
- tool_organisation_department_delete
- tool_organisation_department_move
- tool_organisation_get_managed_users
- tool_organisation_get_potential_parent_departments
- tool_organisation_get_potential_parent_positions
- tool_organisation_get_teams_tab_filters
- tool_organisation_is_jobs_tab_available
- tool_organisation_job_delete
- tool_organisation_position_delete
- tool_organisation_position_move
- tool_organisation_update_departments
- tool_organisation_update_job
- tool_organisation_update_positions
Parameters descriptions are available inside Moodle itself - see Using web services
