Skip to content

Using Taxonomies

A taxonomy is a reusable list of options a user can choose from when answering an information of type 'List'. Instead of typing a free answer, the user selects one or more predefined values. Defining the options once as a taxonomy and reusing it keeps answers consistent and avoids typos.

When to use a taxonomy

Use a taxonomy whenever the same set of options is, or could be, used by more than one piece of information. For example, a 'Countries' taxonomy can be the option list for both 'Country of Residence' and 'Nationality'. If a list of options is only ever used in one single place, a taxonomy still works, but the benefit of reuse is what makes them worthwhile.

Keys and labels

Every value in a taxonomy has a key and a label. The key is what Atfinity stores and what you get when you reference the value in RuLa (for example category_b). The label is the readable text shown to the user (for example 'Category B - Elevated Risk').

When you reference a taxonomy value in a calculated field or a document, you receive the key by default. Put a $ in front of the reference to get the label instead:

cr.risk_classification    # returns the key,  e.g. category_b
cr.$risk_classification   # returns the label, e.g. Category B - Elevated Risk

See The value of my calculated field has a strange format for more on this.

Controlling which values appear in a dropdown

An information does not have to offer every value of its taxonomy. In the information's 'General' tab, the 'Options' section has a 'Show all values' setting:

  • When set to Yes, the dropdown offers every value of the taxonomy.
  • When set to No, you specify exactly which values are shown.

This lets several pieces of information share one taxonomy while each offers a different subset of its values. If you add a value to a taxonomy and it does not appear in a dropdown, this setting is the first thing to check, see Why are some options missing in a dropdown?.

Tip

Because a taxonomy is shared, editing its values affects every information that uses it. Before removing or renaming a value, check where the taxonomy is used so you do not break another part of the configuration.

Sub-taxonomies

A sub-taxonomy is a taxonomy whose values are a subset of a parent taxonomy's values. You do not add new values to it, you choose which of the parent's values it includes, so each value keeps the same key and label wherever it appears. A sub-taxonomy has its own key, and an information can use it as its option list just like any taxonomy. A taxonomy is divided only one level deep: a sub-taxonomy cannot have sub-taxonomies of its own.

Use a sub-taxonomy to offer a narrower set of the parent's values in a particular context, without duplicating the parent taxonomy or the information, rules and documents that rely on it.

Selecting a sub-taxonomy with a rule

Info

New in Atfinity 17.

A List information normally offers every value the 'Show all values' setting leaves available. Turning on Rule for sub-taxonomies lets you narrow that set per case with a Sub-Taxonomy Rule, a RuLa formula that returns the key of a sub-taxonomy of the referenced taxonomy.

The formula is evaluated in each case:

  • When it returns the key of a sub-taxonomy, only that sub-taxonomy's values can be selected.
  • When it does not return a valid sub-taxonomy key, for example when no condition matches, the full taxonomy is offered, exactly as with the rule off.

To switch between sub-taxonomies, return a different key depending on the case:

if self.domicile = ch then SWISS_BANKS else FOREIGN_BANKS end

The rule and the 'Show all values' setting have to agree. The sub-taxonomy is applied only when every one of its values is also among the values the information shows. If the sub-taxonomy contains a value that 'Show all values' hides, the rule is ignored and the full list of shown values is offered.

If the rule resolves to a sub-taxonomy that no longer allows an answer the user already gave, that answer is cleared, including an answer typed into 'Allow free text'. For a List (multiple answers), only the values the new sub-taxonomy still allows are kept, and the answer is cleared when none remain.

The rule restricts what a user can pick in a case. Documents and exports still work against the full taxonomy.

With the rule turned on, the formula cannot be left empty: put live reports it as an inconsistency.