Defining Instance Tree Branches¶
Info
New in Atfinity 17.
Before an instance tree page can show anything around an instance, it needs branches. A branch is one named step away from the instance a user opened, for example from a customer to the people who hold a power of attorney for them. Every branch starts at that instance, so branches are never nested, and each one becomes a source that a list of cards can be built on.
Choose what the branch follows¶
- Role: a role you select. The branch leads to the instances connected to the opened instance through that role.
- Relationship: a single or multiple instance field of the page ontology. The branch leads to the instances that field points at.
- Structure: a structure field of the page ontology. The branch leads to the occurrences of that structure, which are not instances, so less can be shown from them and nothing can be filtered.
Choose the direction¶
Role and relationship branches have a direction, and it means something different for each of them.
On a role branch, forward lists the instances that hold the role for the opened instance, so from a customer you get the people who have a power of attorney for them. Backward lists the instances the opened instance holds the role for, so from a power of attorney you get the customers they represent.
On a relationship branch, forward follows the value stored on the opened instance. Backward finds the instances whose value of that field points back at it.
Structure branches have no direction, since occurrences belong to the instance they are on.
Decide how many instances a role branch leads to¶
A role branch resolves either to one target or to many. One gives the most recently created target, and suits a relationship that is conceptually singular, for example the current employer, so a list of cards shows one card rather than a history.
Name the branch¶
A branch key is written in snake case, is at most 128 characters, and cannot be a reserved word of the
rule language. role and case are both reserved, which rules out
the first key most people try, so name a branch after what it leads to: power_of_attorney, accounts.
Check what the branch will find¶
Three rules decide what ends up at the end of a branch, and between them they explain most of what looks like missing data:
- Roles are read from approved cases only, so a role granted in a case that is still in progress does not appear yet.
- A relationship branch reads the value stored on the instance itself, not the value a running case holds.
- Cases, the one source a list of cards can use without a branch, is the exception to the first rule: it covers every case the opened instance is attached to, whatever its status and whether or not it is the outcome of that case.
Change a branch later¶
Changing the type of a branch, or deleting it, clears the fields and the filters of every list of cards built on it, since neither carries over to a different source. Settling the branches before you build the detail view saves that work. See Building an Instance Tree Detail View.