Hierarchy data format

This article is useful for both new implementations and users new to the hierarchy upload processes and documents what the hierarchy update file needs to contain. Once you have read this article, you can see the full process documented in Hierarchy - upload full process.


As part of implementing the basic Talis Aspire tenancy, you will be guided through getting the data for your hierarchy upload, usually from your Learning Management System or Student registry, wherever you deem the modules or unit information to be a true reflection of your current offerings. If your hierarchy is established, but the process is new to you simply raise a support case and we can arrange a call to discuss the process with you too.

The hierarchy data format provides a simple to construct data format which will allow either incremental or bulk updates to your reading list hierarchy for typical activities such as:

  • Additions (including full hierarchy loads).
  • Deletions.
  • Restructuring - Moving of nodes (Departments, Schools, Modules, Courses) within the hierarchy.
  • Re-coding – code changes to modules, courses etc.
  • Hierarchy metadata updates – e.g. change of module name, descriptions, etc.
  • Node Merges – merging of multiple modules into one new module.


We recognise that some customers will want to have some more specific support in order to effect a hierarchy change using the hierarchy update. Therefore we are able to offer a consultancy which can be tailored to suit your needs. The package would consist of some or all of the following services as appropriate to your needs:

  • Conversion of your source registry hierarchy data into the appropriate format for reading list to then use.
  • Validation of hierarchy files.
  • Running and reporting on progress of the hierarchy change.
  • Advice on planning a hierarchy change within your organisational context.

File Data Structure

The file should be encoded as UTF-8. Failure to use characters from the UTF-8 character set will result in the file being rejected by the hierarchy update.

Prepare a file for each level in your hierarchy, starting from the top down e.g. Top Level - Faculty, Middle Level - School or Department, and then Bottom Level - Modules or Units, this is so the parents can be linked to correctly.

Position Header Data Type Validation Column Mandatory
1 Old Code Unique Alphanumeric code which may include hyphens”-“ or underscores “_” with no spaces yes
2 New Code Unique Alphanumeric code which may include hyphens”-“ or underscores “_” with no spaces yes
3 Node Type Type must exist in Reading List (e.g. Faculty, School, Module etc) yes
4 Name Free text - If the Name contains commas, the entry must be enclosed in quotation marks (“ “). If no commas, there is no need to add quotation marks. yes
5 Description Free text -If the Description contains commas, the entry must be enclosed in quotation marks (“ “). If no commas, there is no need to add quotation marks. no
6 JACS Code Alphanumeric consisting of a letter and three digits e.g. B143 no
7 Parents Alphanumeric code which may include hyphens”-“ or underscores “_” with no spaces no
8 Student Numbers Integer - maximum 9999 no

Please note

  1. Existing quotation marks should be changed to single quotation marks (‘ ‘).
  2. Each row of the CSV file should start on a new line.
  3. The Parents column as shown in the table relates to the parent code/s that the node will link to from a higher part of the hierarchy.

Data Verification Rules

Mandatory Columns

Mandatory columns must be included in the file:

  • Old Code
  • New Code
  • Node Type
  • Name

Valid node types

The currently supported set of Node types are (in alphabetical order):

  • Course
  • Center
  • College
  • Division
  • Department
  • Faculty
  • Field
  • Institution
  • Institute
  • Level
  • Module
  • Pathway
  • Programme
  • School
  • Subject
  • Unit


To ensure the performance of the hierarchy update as a background job, each line must be able to be processed individually. Therefore the following rules apply:

  1. File must be a CSV file, encoded as UTF-8.
  2. File should be limited to 8000 lines, over this may be subject to the job timing out so you may wish to split very large files.
  3. At least one of "Old Code", or "New Code" must be populated.
    • Old Code and New Code must be unique within the file i.e. must appear only once within the file in that column
    • Old Code may contain multiple, space-separated, unique codes where a merge is occurring
    • Old Code must exist in Talis Aspire
    • New Code must not exist in Aspire if creating a new node
  4. Node Type column is mandatory, for additions and changes must always be included and populated in the file (List of supported Node Types)
    • The node type of “Institution” cannot be included within the file but can be referenced as a parent using INSTITUTION.
    • Node Type can only include node types defined in Talis Aspire
  5. Name column is mandatory and must always be included and populated in the file.
  6. Mandatory columns (except for Old Code) can be left unpopulated when performing a delete.
  7. JACS Code may contain multiple, space separated JACS codes where there are multiple JACS codes
  8. Parent Code may contain multiple, space separated codes where there are multiple parents, by separating with a space. 
    • Parent Code must exist in Talis Aspire Reading Lists.
  9. Non-mandatory columns which require no changes can be excluded from the file. This will ensure that any existing data for that column is not overwritten.
  10. Including a column in the file implies an update (whatever is populated for a column will update the system).
  11. All lines in the file must represent the new hierarchy data.
  12. Where a re-coding occurs, any children of the re-coded nodes will have their parent references automatically updated.
    • Where re-coding is included within a file, updates cannot be made to children of re-coded nodes within the same file.
  13. Where new codes are being added, the new parent and related new children nodes cannot be uploaded in the same file. If in doubt upload a separate file for each level in the hierarchy working in the order of top-down (example: School, then Department, and then Module).

Valid File Entry Types

Key: yes - Cell populated; no - Cell not populated; opt - Optional

Hierarchy Metadata = Description, JACS Code, Parents, Student Numbers

  Old Code New Code Name Node Type Hierarchy
(All other fields)
Addition no yes yes yes yes No old code to update
Deletion yes no no no no Metadata leave clear
Updates yes yes yes yes yes All other fields must be present and any changes in value will be updated.
Code changes only yes yes yes yes opt Non-mandatory columns not required
Merges yes yes yes yes opt Old Code may contain more than one code
No changes yes yes yes yes opt If existing data included in the file, no changes will be visible but will be treated as an update

Note: The ‘updates’ action above will also add new nodes if they do not exist. This allows you to effectively assume that a hierarchy node will be updated if it exists and added if it does not exist.

Invalid File Entry Types

Old Code New Code Name Node Type Hierarchy Metadata
no no yes yes yes No Old Code or New Code
yes no no no yes Missing mandatory columns/fields
yes no yes yes yes Deletion where metadata is still populated

Next Steps

So your file is now ready, please move onto Hierarchy upload - Full process.

It’s important to remember we are here to support you through understanding the process of uploading your hierarchy.  If you are unsure on what to do please ask.

Have more questions? Submit a request


Please sign in to leave a comment.