A category relationship lets you filter the values available in one category based on the value a contributor selects in another category. As a result, contributors only see the values that are relevant to their selection when they fill in a document.
For example, you can link a Country category to a City category so that, when a contributor selects France, the City drop-down list only shows French cities.
Category relationships – also known as category value mapping – are configured in the library administration. Learn more: What are categories and reference catalogs?
Note: Only library administrators can create, edit, and delete category relationships. Any user with access to the library benefits from the filtering when they edit a document. Learn more: What are roles?
This article explains how to:
Automatically generated table of contents
What is a category relationship?
A category relationship is a directed association between the values of two single-level categories in the same library:
- The source category – the category the contributor selects first, which determines which options are available (for example, Country).
- The target category – the category whose values are filtered based on the source selection (for example, City).
When you apply the relationship to a document class, selecting a value in the source field limits the values shown in the target field to those you mapped to it.
Category relationships support many-to-many associations: a source value can map to several target values, and the same target value can be mapped from several source values.
Tip: If you need a strict parent-child (one-to-many) hierarchy instead – for example, a single list where each value has its own sublevels – use category sublevels rather than a category relationship.
Before you begin
To create a category relationship, make sure that:
- both the source and target categories already exist in the same library – learn how to create and configure categories
- both categories are single-level categories (categories with sublevels can't be selected)
- the source and target are two different categories
- you have the library administrator role
Create a category relationship
1. Open the library administration.
2. Select Categories in the left panel.
3. Select the Category relationships tab.
4. Click Create relationship.
5. In the Create category relationship dialog, select the Source category – the category that determines which options are available – for example, Country.
6. Select the Target category – the category that shows options based on the source selection – for example, City.
7. Click Create and map values.
Note: Only single-level categories can be selected. The source and target categories can't be changed after you create the relationship – if you choose the wrong category, delete the relationship and create a new one.
Map source values to target values
When you create a relationship, the mapping wizard opens. Use it to choose which target values appear for each source value.
1. On the Map values step, select a source value in the left panel – for example, France.
2. In the right panel, select the target values to show when that source value is selected – for example, Paris and Lyon. Use Select all or Clear to help.
3. Repeat for each source value you want to map.
4. Click Continue to preview.
5. On the Preview mapping step, select a source value to preview the target options contributors will see in real time.
6. Click Save.
Note: You don't have to map every source value. Source values you leave unmapped won't filter the target field – contributors will see the full list of target values for them.
Apply a relationship to a document class
A relationship only affects documents once you enable it on the target category property in a document class.
1. Open the library administration and select Document class.
2. Open your document class and edit its layout.
3. Select the category property that uses your target category – for example, City. The property settings open in the right panel.
4. When a relationship exists between this property's category and another category in the class, the Category relationship detected dialog opens.
5. Choose how the relationship behaves in this document class:
- Use relationship – the target field is filtered based on the selected source value.
- Ignore relationship – the target field shows all available options in this class.
6. Click Apply.
7. Save the document class.
Note: You can change this choice at any time. In the property settings, go to the Category mapping section and select Change next to Relationship behavior.
How filtering works for contributors
Once a relationship is applied, contributors editing a document see the following behavior:
- When a contributor selects a value in the source field, the target field only shows the values mapped to that selection.
- When no value is selected in the source field, the target field isn't filtered and shows the full list of available values.
Note: Filtering is a guide, not a strict rule. Contributors can still set a target value before choosing a source value – in that case they don't benefit from filtering, but the document can still be saved. AODocs doesn't re-check existing documents whose values no longer match the relationship.
Edit or delete a relationship
To edit a relationship, open it from the Category relationships tab, adjust which target values are mapped to each source value, then click Save. You can't change the source or target category of an existing relationship.
To delete a relationship, select Delete next to it on the Category relationships tab, then confirm.
Important: You can't delete a relationship while it's still used by a category property in any document class. Set the property to Ignore relationship (or remove it) first, then delete the relationship.
How AODocs keeps your relationships consistent
AODocs automatically maintains your relationships when categories or fields change:
- Outdated values: If a category value is set as outdated, it's excluded from the filtered results, but its mapping is kept in case you reactivate the value later.
- Deleted values: If you delete a source value, its mapping is removed. If you delete a target value, it's removed from every relationship that used it.
- Deleted categories: You can't delete a category that's used as the source or target of a relationship. Delete the relationship first.
- Removed source field: If you remove the source property from a document class, the relationship settings on the target property are cleared automatically.
Limitations
- Only single-level categories can be linked.
- A relationship applies to single-value category fields.
- A relationship filters in one direction only, from the source category to the target category.
Troubleshooting
The target field isn't filtered when I select a source value. Check that the target property is set to Use relationship in the document class, and that you mapped at least one target value to the selected source value.
The target field is empty. The selected source value has no mapped target values. Open the relationship and map at least one target value to that source value.
I can't delete a category or a relationship. The category is still used by a relationship, or the relationship is still used by a document class. Remove these references first, then try again.