Skip to main content

Link an entity to another entity


As an administrator, you add a ControlledVocabulary field to a form definition to enable users to link record resources, instantiations, and locations with agents, places, or concepts, providing a well-defined context for the archived materials.


Links are created using a RiC Relation entity. Only a restricted set of such relations is defined, but this set can be easily extended with only a minor implementation effort.


You add a link by adding a new JSON object for a field of type ControlledVocabulary to a form definition.

Field options​

  • label: A user-friendly label for the field that will be displayed on the form. Supports multiple languages.
  • name: A unique name or key for the field inside the form.
  • property: The property associated with the field to link with entities such as agents, places, or concepts (see "Values for property" below).
  • relator: The type of link between the entities. It can be a single value or an enumeration defined under "Administration/Lists". Use either this option or relatorEnumeration, never both.
  • relatorEnumeration: The name of a list containing several types of links. The list must be defined as enumeration, available under "Administration/Lists". Use either this option or relator, never both.
  • inScheme (optional): Filters entities available for linking based on their scheme. Only entities with a scheme set to the attribute's value can be linked to. Only a single scheme name is supported.
  • notInScheme (optional): Filters entities available for linking based on their scheme. Only entities with a scheme NOT set to the attribute's value can be linked to. As with inScheme, only a single scheme name is supported here.
  • preview (optional): Lists the properties of the target entity to show in a preview to help the user to pick the right entity. The properties are shown in the order given. If this option is missing, the field attempts to show a title property of the target entity. If that fails, its first property is shown instead.
  • repeatable (optional): If "true", the field allows multiple links to different entities.

Values for property​

The "property" option currently only supports the following three values:

  • hasAgent links with agents.
  • hasPlace links with places.
  • hasConcept links with concepts.
  • hasRule links with rules.

The underlying implementation can be adapted to link to additional entities with a moderate implementation effort.

Examples​

This field definition links to a single Agent entity.

The relator "origination" marks it as being the author of presumably a record resource. As no preview option is given, the title property of the agent is shown as a preview. If that is missing, the first property will be shown.

{
  "type": "ControlledVocabulary",
  "label": { "de": "Author angeben", "en": "Specify author", "fr": "Indiquer l'auteur" },
  "name": "linkToOriginationAgent",
  "options": {
    "property": "hasAgent",
    "relator": "origination",
  }
}

This field definition, again, links to a single Agent entity, but uses filters to only allow a user to link to specific agents.


The inScheme option contains the name of a single scheme, an agent needs to be part of in order to be eligible as target for the link. Similarly, notInScheme names a scheme, the agent must not be part of. As a result, agents that refer to persons, but not organisations, can be named as archivists here.

{
  "type": "ControlledVocabulary",
  "label": { "de": "Archivar:in angeben", "en": "Specify archivist", "fr": "Indiquer l'archiviste" },
  "name": "linkToArchivist",
  "options": {
    "property": "hasAgent",
    "inScheme": "persons",
    "notInScheme": "organisations",
    "relator": "processInfoArchivist",
  }
}

TODO: Show how the entity has its inScheme set:

{
    "sections": [
        {
            "content": [
                {
                    "property": "agentName"
                },
                {
                    "relation": "inScheme",
                    "readonly": true,
                    "defaultValue": {
                        "property": "conceptSchemeName",
                        "value": "Persons"
                    }
                }
            ]
        }
    ]
}

This field definition links with multiple Concept entities.


Each link uses the "subjectGeneral" relator. The name and description properties of a concept are shown in a preview.

{
  "type": "ControlledVocabulary",
  "label": { "de": "Inhalte angeben", "en": "List content", "fr": "Indiquer le contenu" },
  "name": "content",
  "options": {
    "property": "hasConcept",
    "relator": "subjectGeneral",
    "preview": ["name", "description"],
    "repeatable": true
  }
}

This field definition links with multiple places.


Instead of using a specific relator for every link, specified using the relator option, it refers to the relatorEnumeration option. This option mentions a list called "placeTypes", which presumably contains a set of types of places (e.g. box, rack, room). The user has to pick a value from the list as the relator of the link in addition of a place as a target entity.


The preview shows the name, ZIP code and location of each place.

{
  "type": "ControlledVocabulary",
  "label": { "de": "Erwähnte Orte angeben", "en": "List named places", "fr": "Indiquer les endroits mentionnés" },
  "name": "namedPlaces",
  "options": {
    "property": "hasPlace",
    "relatorEnumeration": "placeTypes",
    "preview": ["name", "zipCode", "location"],
    "repeatable": true
  }
}

Known limitations​

⚠️ Only a single relation of a given type may exist between two entities.

This also applies to two relations with the same property, but with different relators. This restriction is due to a technical limitation in neo4j-ogm, a library mapping neo4j graphs to objects - the neo4j database itself does not know any such limitation. Apart from fixing or extending the library, there are several ideas for how to overcome this, but no solution has been implemented yet.

  • inScheme and notInScheme only accept a single value. You currently can't name several schemes to include or exclude.
  • You can't just link any entity with any other entity. The list of available relations is limited, but can be extended, most of the time with only a small implementation effort.