Maintenance required - Friday January 22nd 12pm (PT)

Support Central will be briefly offline on Friday January 22nd from 12:00 pm (PT) while we make improvements and upgrades to this site.

You are here

Using Cascading Metadata with your project

If your Project is using Cascading Metadata, follow these steps.

Cascading Metadata lets the project owner set relationships between certain document tags, so they show only after others are selected. Each attribute choice the user makes restricts the related attributes to relevant options. This gives users fewer and more relevant options to choose from with each selection. It also minimizes the risk that they’ll choose an inappropriate tag for the documents they’re uploading.

You must be a project administrator of the Aconex project owning organization to apply and update cascading metadata.

Which fields can I use in Cascading Metadata?

Currently, 14 fields are available for inclusion in the Cascading Metadata schema: Type, Discipline, VDR Code, Category and Select List 1 – 10.
Document Status cannot be used in a hierarchy.

You must use the database field name for column headings. If you have re-labeled some of your document fields, then be sure to use the original database field names in the import file. 
Document Type = doctype
Discipline = discipline
VDR Code = vdrcode
Select List 1 = selectList1

Database names are case sensitive!

Required User Role Permissions

  • Edit project settings
  • Cascading Metadata

Your Organization Administrator may need to grant these permissions to your user role. Also confirm your organization owns the project.


To use Cascading Metadata on your project, you’ll need to create a hierarchy template: a spreadsheet saved in .csv format. The column headers in the csv file reflect the document fields that you want to use in Cascading Metadata. The rows show the values that will become available with each attribute selection the user makes.

In the example csv file below, if you chose Certificate in the doctype field, you'll be able to choose Electrical or Environmental as the Discipline.

cascading metadata example

An example upload screen with the above cascading metadata applied:

upload screen example animation

Setup Cascading Metadata

  1. Work out how you want a user’s selection in each document attribute field to impact the options available in other fields.
  2. Create a spreadsheet like the one shown above, with a column for each field. Enter the values that will be available in each field in the rows.
  3. Make sure the spelling and formatting exactly matches the values entered in Aconex.
  4. Save the spreadsheet in .csv format. Click on File > Save As... and in the Format field choose Comma Separated Values (.csv).

Make sure:

  • the values you enter into your template match the values in use on the project exactly.
  • you repeat the parent values (shown on the left in the image above) for every child value (shown on the right) in the template.
  • you configure one import file for each hierarchy.
  • you do not use the same field in more than one hierarchy.

Upload and apply Cascading Metadata to your project

  1. From the navigation menu click Setup, and select  Project Settings.
  2. Click Documents and select Cascading Metadata.
  3. If cascading metadata is already applied to your project you need to remove it.  Click Remove Hierarchies.
  4. Now click, Choose File and select the .csv file for your cascading metadata.
  5. Click Save.
  6. You’ll see a confirmation that your file uploaded successfully. If you receive an error you’ll need to correct it and try again. See resolving errors with cascading metadata below.

Repeat steps 4 and 5 to upload multiple hierarchies to your project as required. Note if you are uploading multiple hierarchies, you do not need to remove the existing ones.

project settings screen

Make sure you retain copies of all your cascading metatadata files somewhere safe. 

Update Cascading Metadata on your project

  1. Before you update your file make sure you keep a backup of it. You may need to revert to a backup file if the new file fails to upload.
  2. Update the values in your existing cascading metadata file, and values in your project Document Fields (make sure the spelling and formatting is an exact match). 
  3. Save the spreadsheet in .csv format. Click on File > Save As... and in the Format field choose Comma Separated Values (.csv).
  4. Follow the steps above to upload and apply the cascading metadata to your project. Note that you will need to first remove ALL hierarchies, so if your project is using multiple cascades, make sure you apply ALL of them back again, one by one.

Whenever you add values to your document fields, you'll also need to update your cascading metadata, otherwise your new value will not be visible to use on the project.

Resolve errors with cascading metadata

Example ErrorSolution
File upload failed. Field SelectList9 cannot be used in a hierarchy because it is not enabled on the project. Please amend the import file and try againEnable SelectList9 on your project, or confiugre your hierarchy with a document field that is enabled.
File upload failed. Value6, Value5, Value4 not found for this projectMake sure the values you have entered in your csv file have also been added to Aconex under the correct document field in Project Settings. The values are case sensitive. 

Check and remove any trailing spaces from your values.

Make sure the csv is saved as standard .csv and not anything else such as 'UTF8 with BOM'.
File upload failed. Field doctype has already been used in a hierarchy. Please amend the import file or delete all existing hierarchies and try againThis error means your hierarchy contains a doc field which is already in use in an existing hierarchy. If you are trying to update an existing hierarchy you first have to Remove Hierarchies before you can upload the updated file.
File upload failed. Field doctyp cannot be used in a hierarchy. Please amend the import file and try againCorrect the typo in your csv file and try again.
File upload failed. Row 6 – Parent field doctype is not populated. Please amend the import file and try againCheck your csv file for any empty cells and enter a value.  The file cannot contain any blank values.
File upload failed. Field selectlist 10 cannot be used in a hierarchy. Please amend the import file and try againMake sure you are using the correct database field names for the document fields. The database names do not contain spaces and are case sensitive. In this example the field name should be selectList1.


  • If there’s an existing hierarchy you want to update, you’ll need to remove it before uploading a new file.
  • If there are multiple hierarchies defined and you only want to update one, you’ll need to remove all of them first, before uploading the updated and remaining hierarchies back into the system.

Non-English characters and Unicode UTF-8

  • Using commas as a decimal separator may result in errors with your cascading upload. We recommend your CSV file uses a dot (.) as a decimal separator.
  • If your project contains values with accents, eg ü, ñ, the file can be saved as CSV UTF-8 (comma delimited) (*.csv). Otherwise the upload will result in errors. Example: The value Düsseldorf may be recognised as Düsseldorf.
  • To check your csv is in the correct format, open it in notepad, and make sure the Status Bar is enabled (View > Status Bar). Check the bottom right corner where it should say UTF-8. If not, you can Save As, and select UTF-8 from the encoding dropdown.

Was this article helpful?

Thanks. A ticket has been opened with the Support Central team.