Looking for up-to-date Help documentation? Documentation for the latest releases of Totara is now available at totara.help!

Visit the new Help site

All pages

Position assignments

During upgrade, all existing position assignments are converted to job assignments and each job assignment is given an ID number relevant to its location in a user's job assignment list. Put simply, all legacy primary positions are converted to a job assignment and given an ID number of 1. All legacy secondary positions are converted to a job assignment and given an ID number of 2.

If a position title was not specified on the primary or secondary position pages prior to upgrade, position assignments are converted to unnamed job assignments. All position, organisation, appraiser, manager and temporary manager details assigned prior to upgrade, are located under the applicable job assignment.

It's important not to change the order of any job assignments for users after upgrade if you currently (or intend to) use HR Import.

If a user's first job (top of the list) and second job (bottom of the list) are swapped, it would result in the first job assignment having an ID number of 2 and the second would have an ID number of 1.

After upgrading and before your site goes live, please see follow the appropriate steps for HR Import before making any job assignment changes.

Job Assignments list on a user profile page (screenshot)

Job Assignments List

Job Assignment (screenshot)

A user Job Assignment.

Manager assignments

When assigning a user to a manager, you are no longer assigning the user to a person, rather you're assigning them to a person's job. For example, let's say the user you were choosing a manager for, had a job of Health & Safety Representative. When selecting the manager, you would choose the related manager job e.g. Health & Safety Manager.

See the example below showing two job assignments for the manager, with Health & Safety Manager being the job selected.

Manager Job Assignment

HR Import

For sites that use HR Import to populate position data, special care needs to be taken for those upgrading to 9.0 from earlier versions of Totara. Before proceeding, make sure you understand how position assignments have changed.

A number of changes have been made to HR Import to allow for the importing of one or more job assignments:

  • The option Link job assignments has been added to the User element to allow for backwards compatibility. See Updating job assignments for use with HR Import for usage of this setting.
  • The column Job assignment ID number has been added. This column relates to the ID Number field in a user's job assignments list.

  • The column Manager's job assignment ID number has been added. This is required when using the user's job assignment ID number. If specified, the specific job belonging to the manager will be linked to the user's job assignment. If Link job assignments is set as to the user's first job assignment, the manager's first job assignment will be linked to the user's job assignment.
  • The column Position title has been renamed to Job assignment full name.
  • The columns Position start date and Position end date were renamed to Job assignment start date and Job assignment end date.
  • It's not possible to delete job assignments via HR Import.

Updating job assignments for use with HR Import

Choose from the option below that applies to you and ensure the steps are taken after upgrading and before your site goes live.

I want to use the default Job Assignment ID number converted during upgrade

When you import user records, the imported records will be linked to the user's existing job assignment records using the ID number. One or multiple records may be imported if multiple jobs is enabled.

  1. Go to Site administration > HR Import > Elements > User.
  2. Next to Link job assignments, choose using the user's job assignment ID number and select Save changes.
  3. Go to Site administration > HR Import > Sources > User.
  4. Enable (check) the Job Assignment ID Number column for the appropriate source (CSV or External Database) and select Save changes.
  5. Ensure your source includes the jobassignmentidnumber field and the job assignment ID number(s) being imported match the existing job assignment ID number(s) for each user i.e. 1 or 2. If a matching job assignment record does not already exist, a new one is created.

  6. Import your source data.

I want to use my own Job Assignment ID numbers

In order to import job assignment data from an external source by linking with the external source's ID Numbers, the ID Numbers must first be imported, replacing the default job assignment ID Numbers. These steps should be followed before allowing your site to go live.


  1. Upgrade to Totara 9.0 or later.
  2. Go to Site administration > HR Import > Elements > User.
  3. Next to Link job assignments, choose "to the user's first job assignment" and select Save changes.
  4. Go to Site administration > HR Import > Sources > User.
  5. Enable (check) the Job Assignment ID Number column and select Save changes.
  6. Ensure your source file includes the jobassignmentidnumber"field and is populated for each user. Note that your source should only contain the primary job assignment for each user at this stage.
  7. Import your source data.

    During this import, the job assignment ID number values from your source will overwrite the existing ID numbers for each users' first job assignment (ID Numbers 1 will be replaced with your external ID Number).

  8. If you had previously set up old secondary position assignments, they will now exist as users' second job assignments, with ID number 2. You now need to manually update the ID Number for each of them to the ID number from your HR management system (replace ID Numbers 2 with your external ID Numbers).
  9. Go to Site administration > HR Import > Elements > User.
  10. Finally, next to Link job assignments, choose using the user's job assignment ID number and select Save changes.

Important notes

After successful import with the option using the user's job assignment ID number enabled, the Link job assignments option is removed from the User element settings. A job assignment ID number column will be required when importing job assignment data. Any number of job assignments, each identified by the job assignment ID number field, can now be imported in a single upload (assuming the Multiple job assignments site setting is enabled).

Please be aware that new job assignments (unlike upgraded positions) do not have default ID numbers, so they must have an ID number specified when being imported.

You can now allow manual changes to job assignments (it is safe to allow users to manually change job assignment ordering, etc). Job assignment ID numbers can also be changed at any time by any user that has the capability required to edit job assignments.

Report Builder

General changes

Report builder columns, filters and content options based on a user's position assignment, previously only displayed or checked a user's primary positions.

These have been replaced with new job assignment columns, filters and content options that apply across all of a user's job assignments. These columns have been moved from the User header and are all located under a new All User's Job Assignments header to make them easier to find. The User, Organisation, and Position content options are now applied across all of a user's job assignments. This means if a report has a content option set to Show user's direct reports and a user has three job assignments, all three managers would see the user when viewing the report.

Any existing columns or filters for position and organisation text area custom fields, or framework descriptions, will be lost on upgrade.

Custom report sources

Any custom report sources using the old position functions will need to be updated to use the corresponding job assignment function. Any custom columns or filters using the position assignment joins or fields will need to be updated. The add_basic_user_content_options() function is an easy way to add the Show by user, Show by users current position, and Show by users current organisation content options to a report. Simply call it inside the sources define_contentoptions() function (see totara/reportbuilder/rb_sources/rb_source_user.php for an example).

Learning Plans

If a user has more than one job assignment with a different manager linked to their job assignments, approval requests and other learning plan notifications go to all of the user's managers. All of a user's managers have the ability to approve, decline or delete a user's learning plan and its components (depending on the plan permissions).

The first manager to act on any approval will be successful and other managers will see that approval has already occurred.


Existing appraisals

Existing appraisals that were assigned to a user prior to upgrade will be automatically linked to their first job assignment.

New appraisals

When activating an appraisal, previously the system would warn against missing roles and disallow activation if it was a static appraisal. There is no longer a check for missing roles because appraisals are now linked to job assignments. Providing an appraisal has assigned users and questions, it can be activated.

When accessing an appraisal, if a user has multiple job assignments defined, they have to select a job assignment to link to the appraisal. They cannot proceed with the appraisal until a job assignment is selected. If a user has only one job assignment, it is automatically linked to the appraisal. If a user does not have an existing job assignment, then a default one is created and automatically linked to the appraisal.


Once a job assignment is linked to an appraisal it cannot be changed.


The setting Select job assignment on sign-up replaces Select position on sign-up. See Seminar Global Settings for information on how it works in 9.0.

For sites that had this setting enabled prior to upgrade, users that had selected a position on signup will see their signup position changed to the equivalent job assignment and all notifications will go to the manager of the specific job assignment. There is no change in behaviour for users that did not select a position on signup, except that all notifications will go to all managers linked to their specific job assignments.


Dynamic audience rules based on position assignments previously only applied to users' primary positions. These have been replaced with new job assignment rules that apply across all of a user's job assignments. For sites currently only using primary and not secondary position assignments, existing audience membership will not change on upgrade. However, sites currently using secondary position assignments might see audience memberships change on upgrade.

The position and organisation audience rules have been combined under a new All Job Assignments header and the rules are:

  • Titles (New option - The job assignment full name).
  • Start dates (Previously "Position Start Date").
  • End dates (Previously "Position End Date").
  • Positions.
  • Position Names.
  • Position ID Numbers.
  • Position Assignment Dates.
  • Position Types.
  • Position Custom Fields.
  • Organisations.
  • Organisation Names.
  • Organisation ID Numbers.
  • Organisation Types.
  • Organisation Custom Fields.
  • Managers.
  • Has Direct Reports.


When assigning management hierarchies to a program, one or more of the manager's job assignments can be selected. Only staff managed under the selected job assignments will be assigned to the program via this method.

For upgraded sites that already have managers selected, the first job assignment (previously primary position) will be used.

Developers please note that, any custom code using assignment via management hierarchy must use the ASSIGNTYPE_MANAGERJA constant (which has a value of 6) rather than the ASSIGNTYPE_MANAGER constant (which has a value of 4). You will need to ensure that any calls to Totara functions using this assignment type, use the manager's job assignment id in place of where the manager's user id was being used. Data in the prog_assignment table will updated during upgrade.


The transition from position assignments to job assignments can be mostly easy if the correct steps are taken in the correct order. A lot of it depends on what you've got set up already and how you want to use it going forward. Here are a few examples will help show how it can work.

One job per employee

Let's say your company only has one job per person. You've already got the data in Totara and you're currently using HR Import to sync position assignment data. When you upgrade, you don't care about job assignment id numbers, because there's only one job per person. After upgrading to Totara Learn 9.2.2 (or higher), you can leave the Multiple job assignments setting enabled or change it to disabled, it makes no difference (except to prevent users from manually creating a second job assignment, which could cause problems if they switch their first and second jobs and then you do an import).

In HR Import, leave the Link job assignments setting on to first job assignment and don't ever change it. You'll need to rearrange a few columns in your import source or fix up the column name mappings to match your existing source, but you don't need to provide any extra data. You can then run HR Import as usual and no other changes are required.

Multiple jobs, using Totara auto-generated job assignment id numbers

Before upgrading, you could only have been importing the primary position assignment using HR Import. Maybe you've manually set up the secondary positions in Totara, or they have not yet been set up at all. After upgrading to 9.2.2 (or higher) your existing primary position assignments are now the first job assignments and have a job assignment id number 1. If you had secondary position assignments then they are now the second job assignments and have job assignment id number 2. In this scenario, you don't have any better job assignment id numbers to use, so you'll stick with 1 and 2 (you can add others if you want).

You'll need to leave Multiple job assignments enabled. In HR Import, change Link job assignments to using the job assignment id number. Check your columns - you won't be able to enable the job assignment data columns (e.g. organisation, manager) without first enabling the job assignment id number column. In your import source, you'll need to add the job assignment id number column. Since your source currently only has primary position assignments, you need to put 1 into this field for all records.

You can now add multiple job assignments to your source. They need to have some other (not 1) job assignment id number. Perhaps you want to synchronise your source and your Totara data by adding all secondary job assignment from Totara into your import source. There's no way to extract the existing secondary job assignments from Totara, so you'll either have to populate your import source from your external HR system or manually populate it. To match up the records, you need to put 2 into the job assignment id number in your source for these secondary job assignments. If you want a third job assignment, you could put 3 or anything else you want.

You can now run HR Import. Existing records with matching job assignment id numbers will be updated. If you added a record in your source with job assignment id number 2 and in Totara you had an upgraded job assignment with id number 2 then the Totara record will be updated. User/job assignment id number combinations from the source which don't exist in Totara will be created. User/job assignment id number combinations in Totara which are not in the source will not be affected.

Note that the option Link job assignments will be removed from the form after the first import, so you'll always need to provide the job assignment id numbers going forward.

 Multiple job assignments, your external HR system has job assignment id numbers

The confusion here comes from figuring out how to populate your existing Totara job assignments with your external HR job assignment id numbers. To successfully import multiple job assignments, your external source and your existing Totara job assignments must have the same job assignment id numbers. This needs to happen as a separate step before your import will be able to use that link.

One method is to manually set them, but that could be very time consuming and prone to mistakes. Instead, you can use HR Import to populate the job assignment id numbers in Totara (which will replace the 1 and 2 that were automatically generated during upgrade to 9.2.2 or higher).

An example: Say we had a user with primary and secondary position assignments. After upgrade they will have two job assignments. The first has id number 1, position DEV3 and manager Jane. The second has id number 2, position UX and manager Tim. In our external HR system, they have two jobs. The first job assignment has id number PRIMARY, position DEV3 and manager Jane. The second job assignment has id number CONSULTANT, position UX and manager Tim. We had previously been updating their primary position assignment using HR Import, and updating their secondary position assignment manually. To be able to import both these records automatically, we need to somehow set the Totara job assignment id numbers to PRIMARY and CONSULTANT.

Before upgrading to 9.2.2 (or higher), your HR Import source could only have contained primary position assignments. We'll use this fact to our advantage. In HR Import, set it to Link job assignments with the option to first job assignment. Enable the job assignment id number column. In the source, add the job assignment id number column and populate it with the id numbers from your external HR system. The source must still only contain the primary job assignments for each user, but now it's got one extra column.

Run the import. It will update the job assignment id number of the first job assignment for each user, changing it from 1 to whatever id numbers your external HR system uses. In our example, it would now be PRIMARY.

Now you need to manually update the job assignment id numbers of your second job assignments in Totara. There's no way to automatically transfer them from your external system into Totara. In our example, we need to manually change it from 2 to CONSULTANT.

At this point, the job assignment id numbers in the two systems match. Change the Link job assignments setting to using job assignment id number. Add the secondary job assignments to the import source, including their job assignment id numbers. You can add more than just a second if you want - these can't have existed in Totara previously, so will be created when you import. When you run import, the records will be linked by job assignment id number and updated. After the first import, you won't be able to change the link setting back to first job assignment (and you wouldn't want to).

Notes / Conclusion

  • When you link to first job assignment, it updates the job assignment id number (if provided).

  • When you link using job assignment id number, if the matching job assignment id number exists then it is used as the link - it doesn't update the job assignment id number because it must, by definition, be the same already.

  • When you link using job assignment id number, if you change the job assignment id number in your source, the records will no longer link, so a new job assignment will be created.

  • When you change the data relating to a job assignment (e.g. if your job assignment had position DEV3, organisation SUPPORT, manager Rob, then changed to position DEV4, organisation R&D, manager Milly) then anywhere in Totara which was previously linked to this job assignment will still be linked to this job assignment. For example, if the user was doing an appraisal linked to this job assignment, then the appraisal will still be linked to this job assignment, but the manager who is participating in the appraisal will change (from Rob to Milly in the example).

  • Thew earlier example used PRIMARY and CONSULTANT as job assignment id numbers. Users can share the same job assignment id numbers, but they must be unique for each user, so two users can have CONSULTANT but one user cannot have two job assignments both with id number CONSULTANT. Also, there's no reason why you can't use something that is completely unique, such as a record id number from your external HR system's user - job assignment table.
On this page

The Totara Academy has a whole course dedicated to using Hierarchies and job assignments in Totara Learn. Here you can learn more on how to use hierarchies and job assignments, see best practice, and give it a go yourself.

Provide feedback about this page using the link in the bottom right of this page. 

Still have questions? Why not post them in the forums of the Totara Community?