Organisation structure

From MoodleDocs
workplacelogo.png 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.

Moodle Workplace Organisation Structure

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
  • Manually assign managers 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.

People & Jobs

The People tab shows users and jobs that have been assigned to them. 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.

Organisation structure - People.png

To manage a user's job(s), select the View jobs and reporting lines option in the Action menu, where you will see 3 panels:

  • Jobs assigned: Current and previous jobs
  • Reports to: Manager(s) who the user reports to
  • People reporting to <user>: Staff reporting to the user
Organisation structure - Jobs and Reporting Lines.png

Jobs assigned

The Jobs assigned panel displays the following information:

  • Position and department (a Not active label is shown if the position has an end date in the past)
  • Start date and end date or, if not set, Present
  • Depending on the set permissions of the assigned position, the labels Manager and/or Department lead are displayed, alongside the selected permissions
  • Actions
    • Transfer this job to a new one: 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).
    • Edit dates: Modify or set the start and end date.
    • Delete job permanently: 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.


To create a new job assignment, select the + Assign job button.


For each job, you have to select 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.

Reports to

The Reports to panel shows all managers who the user reports to. The following information is displayed for each manager:

  • Name: Profile image, first name, last name
  • Depending on the set permissions, the labels Manager and/or Department lead are displayed, alongside the selected permissions
  • Actions
    • View jobs and reporting lines: jump straight to the manager's jobs page

People reporting to

The People reporting to panel shows all users who are reporting to the current user. Moodle Workplace supports two types of assigned staff:

  • Automatically assigned: The assignment is performed automatically based on the department and position of the assignee. The assignee will be reporting to any user who has been granted Department lead or Manager permissions in the assignee's department or position, respectively.
  • Manually assigned: A user can be manually assigned to a manager.


The following information is displayed for staff:

  • Name: Profile image, first name, last name
  • Relevant jobs (automatically assigned staff only): Position and department of the role in which the person is reporting to the current user
  • Reporting line: For automatically assigned staff the position(s) and department(s) of the reporting line from the staff to the current user is shown. For manually assigned staff, a label indicating this is displayed.
  • Permissions: Permissions of the assignment.
  • Start date: Date when the person started the position.
  • Actions
    • Edit assignment (manually assigned staff only): Modify the assignment's permissions
    • Un-assign person (manually assigned staff only): Delete the assignment. This action cannot be undone!
    • View jobs and reporting lines: jump straight to the manager's jobs page


To manually assign a via the + Assign staff button.

Organisation structure - Assign staff.png

You need to select at least one person who will be reporting to the current user. The permissions are the same as described in the Positions section.

Bulk actions

When users have been selected, the a number of bulk actions are available, impacting only the selected users.

Organisation structure - People Bulk Actions.png

The following bulk options are available:

  • Add a job: A new job assignment is created for each user, once a position, a department, and a start date has been provided.
  • Set jobs as finished: Once the end date (default to today) has been provided, all jobs are set to be finished.
  • Assign a manager manually: The chosen user(s) will be the new manager of the selected users. To deal with existing managers, there are two options available (note, that this only impacts manually added managers!):
    • Keep existing managers and add new ones: Existing managers of the users will be retained, and the new managers you have specified will be added alongside them. Use this option if you want to maintain the current manager assignments and add additional managers.
    • Replace existing managers: Existing managers assigned to the users will be completely replaced by the new managers you have specified. Use this option if you want to completely replace the existing manager assignments with the new ones.
Organisation structure - People Bulk Actions - Assign Manager.png
  • Un-assign managers: All manually assigned managers of the selected users will be removed. This action cannot be undone!
  • Transfer to a new job: A new job assignment is created for each user, once a position, a department, and a start date has been provided. All jobs for all the selected users will be set as finished one day before the new job starts.

Reports

Currently, the only report available, is All jobs report, which represents the legacy Job assignment page before the People tab has been introduced in version 4.3.

Organisation structure - Reports.png

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 our screenshot, Thomas Gaunter holds the position of 'Lead Developer' in the department 'Applications development'. Additionally, she is the Project Manager for a customer called Romgen Pharma.

Organisation - Matrix organisation 1.png

When looking at the jobs and reporting lines, we can see that the development job is her ongoing position (no end date set), while the project manager functions is set from the Jan 1, 2023 to Dec 31, 2023. She has two reporting lines, one to Charlie Smith who is heading up the Apps development department, and Genovera Tanton who is in charge of the aforementioned customer.

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:

Organisation - Locked Framework.png

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.

Shared Organisation Structure

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>

Example of the CLI command that will import the above sample department file with the following settings:

  • departments need to be imported into a new framework,
  • the column 'code' should be used as the identifier for the parent lookup
  • column 'code' should be mapped to 'idnumber'
  • in case when idnumber is not unique, importer should increment it (other options would be 'skip' - not to import at all, and 'empty' - to set idnumber to empty).

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