Reference relationships

Overview

Reference relationships functionally relate two existing entities. One of them is the referenced, and one is referencing.

Example
  • In an EmployeeHasCostCenter reference, the referenced entity is CostCenter, and the referencing entity is Employee.

  • In a CostCenterHasParentCostCenter reference, the referenced entity is CostCenter, and the referencing entity is also CostCenter. This is a self-reference.

Reference relationships usage

Reference relationships are used for:

  • Organizing records into hierarchies. For example, to build a hierarchy of cost centers using a self-reference called CostCenterHasParentCostCenter, which links the CostCenter entity to itself.

  • Displaying lists of child records referencing a given record. For example, to display a cost center with a list of employees belonging to this cost center according to an EmployeeHasCostCenter relationship.

  • Navigating to records referenced through a relationship. For example, to navigate from an Employee record to the cost center they belong to.

  • Referential integrity purposes. Referential integrity is enforced as part of the golden data certification process. References can be used as constraints on records. For example, to check that an employee is attached to an existing cost center, or a contact is attached to an existing customer.

  • Propagating or preventing deletion. For example, to define that a customer with existing contracts cannot be deleted, or that when a product is deleted, all its items should also be deleted.

A reference is expressed in the model in the form of a foreign attribute that is added to the referencing entity.

Create reference relationships

To create a reference relationship:

  1. Right-click the Reference Relationships node in the model and select Add Reference. The Create New Reference Relationship wizard opens.

  2. In the Create New Reference Relationship wizard, check the Auto Fill option and then enter the following values:

    • Name: Internal name of the object.

    • Physical Name: Name of the database indexes created for optimizing access via this reference.

    • Label: User-friendly label for this object. Note that as the Auto Fill box is checked, the Label is automatically filled in. Modifying this label is optional.

    • Validation Scope: Select whether the referential integrity should be checked pre and/or post-consolidation.

      Due to a legacy constraint based on the maximum object name length in certain relational database management systems, physical data object names that are generated during model deployment are truncated to 25 characters. Designers should plan accordingly when choosing logical data object names.

    • Physical Name: name of the database indexes created for optimizing access via this reference.

    • Label: user-friendly label for this object. Note that as the Auto Fill box is checked, the Label is automatically filled in. Modifying this label is optional.

    • Validation Scope: select whether the referential integrity should be checked pre- or post-consolidation, or both.

  3. In the Referencing [0..*] group, enter the following values:

    • Referencing Entity: Select the entity which references the referenced (parent) entity. For example, in an EmployeeHasCostCenter relationship, it is the Employee entity.

    • Referencing Role Name: Name used to refer to this entity from the referenced entity. For example, in an EmployeeHasCostCenter relationship, it is the Employees.

    • Referencing Role Label: User-friendly label to refer to one record of this entity from the referenced entity. For example, in an EmployeeHasCostCenter relationship, it is the Reporting Employee .

    • Referencing Role Plural Label: User-friendly label to refer to a list of records of this entity from the referenced entity. For example, in an EmployeeHasCostCenter relationship, it is the Reporting Employees (plural).

    • Referencing Entity: select the entity which references the referenced (parent) entity. For example, in an EmployeeHasCostCenter relationship, it is the Employee entity.

    • Referencing Role Name: name used to refer to this entity from the referenced entity. For example, in an EmployeeHasCostCenter relationship, it is the Employees.

    • Referencing Role Label: user-friendly label to refer to one record of this entity from the referenced entity. For example, in an EmployeeHasCostCenter relationship, it is the Reporting Employee.

    • Referencing Role Plural Label: user-friendly label to refer to a list of records of this entity from the referenced entity. For example, in an EmployeeHasCostCenter relationship, it is the Reporting Employees (plural).

  4. In the Referenced [0..1] group, enter the following values:

    • Referenced Entity: select the entity which is referenced. For example, in an EmployeeHasCostCenter relationship, it is the CostCenter entity.

    • Referenced Role Name: name used to refer to this entity from the referencing entity (subject to the above-mentioned 25-character limit). For example, in an EmployeeHasCostCenter relationship, it is the CostCenter. This name is also the name given to the foreign attribute added to the referencing entity to express this relationship.

    • Referenced Role Label: User-friendly label to refer to this entity from the referencing entity. For example, in an EmployeeHasCostCenter relationship, it is the Cost Center.

    • Mandatory: define whether the reference to this entity is mandatory for the child. For example, in an EmployeeHasCostCenter relationship, this option must be checked as an employee always belongs to a cost center. For a CostCenterHasParentCostCenter reference, the option should not be checked as some cost centers may be at the root of my organization chart.

    • Physical Name: name of the physical column created for the foreign attribute in the tables representing the referencing entity.

  5. Click Finish to close the wizard. The Reference Relationship editor opens.

  6. In the Description field, optionally enter a description for the Reference Relationship. This description is intended for the model designers.

  7. Define the user-facing Documentation describing the reference. Use plain text or the Markdown syntax for rich text. This text provides detailed documentation for the reference and appears in the documentation side nav. You can also define a description and documentation in the Referenced Entity (From) and Referencing Entity (To) tabs to provide more detailed information about the roles of the parent and child entities in that relationship.

  8. For a mandatory (one-to-many) reference, optionally define a custom Error Message (Mandatory). This message appears instead of a default message when this reference is left empty.

  9. Optionally define a custom Error Message (Broken Reference). This message appears instead of a default message when this reference points to a parent record that does not exist.

  10. With the Delete Propagation property, define how this reference affects deletion. The possible values are:

    • Restrict: prevents referenced record deletion if a referencing record exists. If a child is found through this relationship while attempting to delete the parent (or an ancestor), the whole delete operation will be aborted or not allowed.

    • Nullify: sets the reference to null on the referencing record when the referenced record is deleted. If a child is found through this relationship while attempting to delete the parent, its relationship to the parent is set to null. This value cannot be selected for mandatory relationships.

      Upon model validation, an error message displays indicating that the model is not valid if the survivorship rule for the referenced entity is set to No Override. You are prevented from deploying this model.

      If the survivorship rule for the referenced entity is set to Override - until consolidated value changes, a warning displays to inform you that this configuration can lead to reuse of master record values still referencing the removed golden record after a reconsolidation. You can still deploy the model.

    • Cascade: delete referencing records when the referenced record is deleted. If a child is found through this relationship while attempting to delete the parent, an attempt to delete this child and all its children recursively will be made, until all children are finally deleted. If any of the child relationships—​at any level—​are preventing deletion, neither the record nor any of its children are deleted.

  11. With the Split Duplicates Propagation property, define how splitting records in the referenced entity affects the referencing records. This property applies when both the referenced and referencing entities are fuzzy-matched. The possible values are:

    • None: with this configuration, when records in the referenced entity are split by a user in a duplicate manager, the records in the referencing entity remain unchanged.

    • Reset Matching: with this configuration, when records in the referenced entity are split by a user in a duplicate manager, the records referencing the split records are re-matched, ignoring their previous match groups and user decisions. The resulting golden records are re-distributed under their respective parent records. When re-matched, the referencing records are all re-merged into new golden records with new Golden IDs, and lose all their value overrides.

  12. Press Control+S (or Command+S on macOS) to save the editor.

  13. Close the editor.