Relationship Rules¶

The validity of a relationship between any two items is enforced by rules that ensure that each item has the right Type and Subject for the relationship. For example, only a person can captain a boat. Therefore, in the captain of relationship, the first item must be a person and the second must be a vessel. When the direction of this relationship is applied in reverse, the first item must be a vessel which is captained by a person.

Though archivists are careful to properly enter data into the collection, it’s easy to make mistakes and so the Digital Archive software catches and prevents them whenever possible. When an archivist adds a relationship between two items, the software checks the rules for that particular relationship type and only allows the relationship to be added if both items satisfy the relationship type’s rules. If the validation fails, the software tells the archivist what is wrong and what correction is necessary.

Rules help ensure data integrity by preventing unintended relationships from creeping into the collection by mistake or due to improper understanding of how two items relate to each other. While use of rules is not required, they make the archivist’s life easier and provide end users with more reliable information.

This page explains relationship rules and how you define them.

---

Rule editor¶

To add or edit a relationship rule:

• Click the Relationships button in the left admin menu
• On the Relationships page, click the Edit Relationship Rules button
• You will see a page similar to the one shown below

Rules appear in alphabetical order to make them easier to find in the list. That’s why the rule Id numbers are not in numerical order.

Add, edit, or remove a relationship rule¶

To add a new relationship rule, click the Add Relationship Rule button located at the bottom of the Edit Relationship Rules page (the button is not shown in the screenshot above). To edit an existing relationship rule, click the arrow icon to the far right of the rule. This opens a panel that lets you make changes. If the relationship rule is not in use, a Remove button will appear in the panel. You can only remove a relationship rule that is not in use.

The screenshot below shows what you see when you edit a rule.

Rule description¶

The description is a concise statement that summarizes the rule so that you’ll know what the rule is for when choosing to use it as part of the definition of a relationship type. The description also appears in error messages when rule validation fails. When adding or editing a rule’s description, make sure the words you choose are consistent with the descriptions for existing rules.

Rule syntax and semantics¶

Specifying a rule can be a bit tricky because you must do so precisely using the proper metadata field names like Type and Subject as well as the correct syntax for Regular Expressions as explained below; however, if you look at existing rules, you’ll notice that they all follow the same pattern and so you should be able to or create a new rule, by carefully following the pattern carefully used in existing rules.

This section explains relationship rules in detail. The screenshot from above is repeated below for convenience while reading this section.

In the example above, the rule is saying that the item to which the rule applies must have a Type field value that starts with Reference and a Subject field value that starts with either Businesses or Organizations or People.

The pattern for a rule has the following syntax and semantics:

• A rule consists of a semicolon-separated list of name/pattern pairs. The example above has these two pairs:
  • Type:^Reference
  • Subject:^(Businesses|Organizations|People)
• Each pair consists of metadata field name followed by a colon followed by a pattern (with no spaces in between). In the example above:
  • The 1st pair's field name is Type and the pattern is ^Reference
  • The 2nd pair's field name is Subject and the pattern is ^(Businesses|Organizations|People)
• The pattern is a MySQL Regular Expression (REGEX).
  • The ^ means match the beginning of a string.
  • The vertical-bar-separated list in parenthesis means match any of the values.
• The name/pattern pairs are ANDed together and the vertical-bar-separated values are ORed together. Thus the rule in the example means that the item to which the rule applies must have:
  • A Type field value that starts with the word Reference AND it must have
  • A Subject field value that starts with Businesses OR Organizations OR People
• The AvantRelationships plugin will translate this example into a SQL WHERE clause like this: (_advanced_0.text REGEXP '^Reference' AND _advanced_1.text REGEXP '^People')
• In the WHERE clause, _advanced_0.text is the value of the item’s Type field value and _advanced_1.text is the value of the item’s Subject field value.
• The SQL for a rule gets executed when you add a relationship to an item, or update an existing relationship. This is done to ensure that the relationship is valid between that item and the related item. The Digital Archive software validates all of an item’s relationships whenever you save the item. This protects against the situation where a relationship becomes invalid because you edited one of the item’s fields, e.g. its Type or Subject, in a way that no longer satisfies a relationship’s rules. That's why you'll sometimes get an error when you save an item that previously had no errors when saved.

Regular Expression syntax¶

For a detailed explanation and examples of Regular Expression syntax, see the Regular Expression Syntax section of the MySQL documentation. The most commonly used syntax for rules is:

^

Match the beginning of a string.
Example: ^Reference matches any string that starts with Reference.

$

Match the end of a string/
Example: Postcard$ matches any string that ends with Postcard. It would match
Object, Writing, Postcard or Image, Photograph, Picture Postcard, but not
Document, Memorabilia, Album, Postcard Album.

de|abc

Alternation; match either of the sequences de or abc.
Example: Businesses|Organizations|People