Page History

...

• DSpace comes with sample submission forms for each Entity type.
  • The sample <submission-process> is defined in item-submission.xml and named based on the Entity type (e.g. Publication, Person, Project, etc).
  • The metadata fields captured for each Entity are defined in a custom step in submission-forms.xml, and named in the format "[entityType]Step" (where the entity type is camelcased).  For example: "publicationStep", "personStep", "projectStep".
• Optionally, modify those sample submission forms. See Submission User Interface for hints/tips on customizing the item-submission.xml or submission-forms.xml files

• Now, in As of 7.6, you can simply map each Entity Type to a specific submission form as follows in your item-submission.xml (This section already exists, map your Collection's handle (findable on the Collection homepage) to the submission form you want it to use.   In the below example, we've mapped a single Collection to each of the out-of-the-box Entity types.just uncomment it)

  Code Block
  <name-map collection-entity-type="Publication" submission-name="Publication"/>
  Code Block
  <name-map collection-handleentity-type="123456789/5Person" submission-name="PublicationPerson"/> <name-map collection-entity-handletype="123456789/6Project" submission-name="PersonProject"/> <name-map collection-handleentity-type="123456789/7OrgUnit" submission-name="ProjectOrgUnit"/> <name-map collection-entity-handletype="123456789/8Journal" submission-name="OrgUnitJournal"/> <name-map collection-handle="123456789/28" submission-nameentity-type="Journal"/> <name-map collection-handle="123456789/29" JournalVolume" submission-name="JournalVolume"/> <name-map collection-entity-handletype="123456789/30JournalIssue" submission-name="JournalIssue"/>

Once your modifications to the submission process are complete, you will need to quickly reboot Tomcat (or your servlet container) to reload the current settings.

5. Configure Workflow for each Entity type (optionally)

The DSpace workflow can be used for reviewing all objects in the Object Model since these objects are all Items, and separate collections can be used. The workflow used for e.g. a Person Object can be configured to be identical to a publication, different from a publication, or use no workflow at all.

See Configurable Workflow for more information on configuring workflows per Collection.

6. Configure Virtual Metadata to display for related Entities (optionally)

"Virtual Metadata" is metadata that is dynamically determined (at the time of access) based on an Entity's relationship to other Entities.  A basic example is displaying a Person Entity's name in the "dc.contributor.author" field of a related Publication Entity.  That "dc.contributor.author" field doesn't actually exist on the Publication, but is dynamically added as "virtual metadata" simply because the Publication is linked to the Person (via a relationship).

Virtual Metadata is configurable for all Entities and all relationships.  DSpace comes with default settings for its default Entity model, and those can be found in [dspace]/config/spring/api/virtual-metadata.xml. In that Spring Bean configuration file, you'll find a map of each relationship type to a metadata field & its value.  Here's a summary of how it works:

The "org.dspace.content.virtual.VirtualMetadataPopulator" bean maps every Relationship type (from relationship-types.xml) to a <util:map> definition (of a given ID) also in the virtual-metadata.xml

<!-- For example, the isAuthorOfPublication relationship is linked to a map of ID "isAuthorOfPublicationMap" -->
<entry key="isAuthorOfPublication" value-ref="isAuthorOfPublicationMap"/>

That <util:map> defintion defines which DSpace metadata field will store the virtual metadata. It also links to the bean which will dynamically define the value of this metadata field.

<!-- In this example, isAuthorOfPublication will be displayed in the "dc.contributor.author" field -->
<!-- The *value* of that field will be defined by the "publicationAuthor_author" bean -->
<util:map id="isAuthorOfPublicationMap">
    <entry key="dc.contributor.author" value-ref="publicationAuthor_author"/>
</util:map>

• 
  

  • WARNING: If you create a new Collection using a specific Entity Type, you must currently restart your servlet container (e.g. Tomcat) for the submission form configuration to take effect for the new Collection.  This is the result of a known bug where the Submission forms are cached until the servlet container is restarted.  See this issue ticket: https://github.com/DSpace/DSpace/issues/7985

  • In 7.5 and earlier, you needed to map each Collection's handle one by one to a Submission form in item-submission.xml. Map your Collection's handle (findable on the Collection homepage) to the submission form you want it to use.   In the below example, we've mapped a single Collection to each of the out-of-the-box Entity types.

    Code Block

    <name-map collection-handle="123456789/5" submission-name="Publication"/> <name-map collection-handle="123456789/6" submission-name="Person"/> <name-map collection-handle="123456789/7" submission-name="Project"/> <name-map collection-handle="123456789/8" submission-name="OrgUnit"/> <name-map collection-handle="123456789/28" submission-name="Journal"/> <name-map collection-handle="123456789/29" submission-name="JournalVolume"/> <name-map collection-handle="123456789/30" submission-name="JournalIssue"/>

    
    

Once your modifications to the submission process are complete, you will need to quickly reboot Tomcat (or your servlet container) to reload the current settings.

4.1 Use of collection-entity-type attribute for default Submission forms per Entity Type

Alternatively to a collection's Handle, Entities Types can be used as an attribute. So, instead of specifying the collection handle, you will need to use the collection-entity-type attribute and what Entity Type to use (like: Person, Project). Please mind that your Collections with Entity Type need to be previously created.

<name-map collection-entity-type="Publication" submission-name="Publication"/>
<name-map collection-entity-type="Person" submission-name="Person"/>
<name-map collection-entity-type="Project" submission-name="Project"/>
<name-map collection-entity-type="OrgUnit" submission-name="OrgUnit"/>
<name-map collection-entity-type="Journal" submission-name="Journal"/>
<name-map collection-entity-type="JournalVolume" submission-name="JournalVolume"/>
<name-map collection-entity-type="JournalIssue" submission-name="JournalIssue"/>

Once your modifications to the submission process are complete, you will need to quickly reboot Tomcat (or your servlet container) to reload the current settings.

5. Configure Workflow for each Entity type (optionally)

The DSpace workflow can be used for reviewing all objects in the Object Model since these objects are all Items, and separate collections can be used. The workflow used for e.g. a Person Object can be configured to be identical to a publication, different from a publication, or use no workflow at all.

See Configurable Workflow for more information on configuring workflows per Collection.

6. Configure Virtual Metadata to display for related Entities (optionally)

"Virtual Metadata" is metadata that is dynamically determined (at the time of access) based on an Entity's relationship to other Entities.  A basic example is displaying a Person Entity's name in the "dc.contributor.author" field of a related Publication Entity.  That "dc.contributor.author" field doesn't actually exist on the Publication, but is dynamically added as "virtual metadata" simply because the Publication is linked to the Person (via a relationship).

Virtual Metadata is configurable for all Entities and all relationships.  DSpace comes with default settings for its default Entity model, and those can be found in [dspace]/config/spring/api/virtual-metadata.xml. In that Spring Bean configuration file, you'll find a map of each relationship type to a metadata field & its value.  Here's a summary of how it works:

• The "org.dspace.content.virtual.VirtualMetadataPopulator" bean maps every Relationship type (from relationship-types.xml) to a <util:map> definition (of a given ID) also in the virtual-metadata.xml

  Code Block
  <!-- For example, the isAuthorOfPublication relationship is linked to a map of ID "isAuthorOfPublicationMap" --> <entry key="isAuthorOfPublication" value-ref="isAuthorOfPublicationMap"/>

  
  

• That <util:map> defintion defines which DSpace metadata field will store the virtual metadata. It also links to the bean which will dynamically define the value of this metadata field.

  Code Block
  <!-- In this example, isAuthorOfPublication will be displayed in the "dc.contributor.author" field --> <!-- The *value* of that field will be defined by the "publicationAuthor_author" bean --> <util:map id="isAuthorOfPublicationMap"> <entry key="dc.contributor.author" value-ref="publicationAuthor_author"/> </util:map>

  
  

• A bean of that ID then defines the value of the field, based on the related Entity. In this example, these fields are pulled from the related Person entity and concatenated.  If the Person has "person.familyName=Jones" and "person.givenName=Jane", then the value of "dc.contributor.author" on the related Publication will be dynamically set to "Jones, Jane.

  Code Block

  <bean class="org.dspace.content.virtual.Concatenate" id="publicationAuthor_author"> <property name="fields"> <util:list> <value>person.familyName</value> <value>person.givenName</value> <value>organization.legalName</value> </util:list> </property> <property name="separator"> <value>, </value> </property> <property name="useForPlace" value="true"/> <property name="populateWithNameVariant" value="true"/> </bean>

  
  

If the default Virtual Metadata looks good to you, no changes are needed.  If you make any changes, be sure to restart Tomcat to update the bean definitions.

Designing your own Entity model

When using a different entities model, the new model has to be configured an loaded into your repository

Thinking about the object model

First step: identify the entity types

• Which types of objects would you want to create items for: e.g. Person, Publication, JournalVolume
• Be careful not to confuse a type with a relationship. A Person is a type, an author is a relationship between the publication and the person

Second step: identify the relationship types

• Which relationship types would you want to create between the entity items from the previous step: e.g. isAuthorOfPublication, isEditorOfPublication, isProjectOfPublication, isOrgUnitOfPerson, isJournalIssueOfPublication
• Multiple relationships between the same 2 types can be created: isAuthorOfPublication, isEditorOfPublication
• Relationships are automatically bidirectional, so no need to worry about whether you want to display the authors in a publication or the publications of an author

Third step: visualize your model

• By creating a drawing of your model, you’ll be able to quickly verify whether anything is missing

Configuring the object model

Configure the model in relationship-types.xml

• Similar to the default relationship-types.xml, configure a relationship type per connection between 2 entity types
• Include the 2 entity type names which are being connected.
• Determine a clear an unambiguous name for the relation in both directions
• Optionally: determine the cardinality (min/max occurrences) for the relationships
• Optionally: determine default behavior for copying metadata if the relationship is deleted

Configuring the metadata fields

Determining the metadata fields to use

• Dublin Core works for publications, but not for a Person, JournalVolume, …
• There are many standards which can be easily configured: schema.org, eurocris, datacite, …
• Pick a schema which suits your needs

Configure the submission forms

• Add a form in submission-forms.xml for each entity type, containing the relevant metadata fields
• See also Submission User Interface documentation.
• Configure which relationships to create

Configuring the item display pages

• The metadata configuration is not specific to configurable entities.
• Similar to other customizations to the item display pages, configure in Angular which metadata fields to display and their label. A template per entity type can be created
• The relationship display is similar to the metadata configuration
• Similar to the metadata configuration: configure in Angular which relationship to display and their label

Configuring virtual metadata

• The isAuthorOfPublication relationship can be displayed for the Publication item as dc.contributor.author
• The isOrgUnitOfPerson relationship can be displayed for the Person item as organization.legalName
• This can be configured in virtual-metadata.xml

Configuring discovery

• Configure the discovery facets, filters, sort options, …
• The facets for a Person can be job title, organization, project, …
• The filters for a Person can be person.familyName, person.givenName, …

Additional Technical Details

The original Entities design document is available in Google Docs at: https://docs.google.com/document/d/1wEmHirFzrY3qgGtRr2YBQwGOvH1IuTVGmxDIdnqvwxM/edit

We are working on pulling that information into this Wiki space as a final home, but currently some technical details exist only in that document.

A talk on Configurable Entities was also presented at DSpace 7 at OR2021

Versioning Support

DSpace entities fully support versioning. For the most part, this works like any other item. For example, when creating a new version of an item, a new item is created and all metadata values of the preceding item are copied over to the new item. Special care was taken to version relationships between entities.

Example of the latest status of a relationship (technical details)

To understand how versioning between entities with relationships works, let's walk through the following example:

Image Added

Consider Volume 1.1 (left side) and Issue 1.1 (right side). Both are archived and both are the first version. Note that on the arrow, representing the relation between the volume and the issue, two booleans and two numbers are indicated.

• The boolean on side (v) is true if and only if volume 1.1 is the latest version that is relevant to issue 1 (even though it may be possible that volume 1.2, the second version of volume 1, exists). This means that on the item page of issue 1.1, a link to the item page of volume 1.1 should be displayed. It also means that searching for (the uuid of) issue 1.1 should yield volume 1.1.
• The boolean on side (i) is true if and only if issue 1.1 is the latest version that is relevant to volume 1.1 (even though it may be possible that issue 1.1, the second version of issue 1, exists). This means that on the item page of volume 1.1, a link to the item page of issue 1.1 should be displayed. It also means that searching for (the uuid of) volume 1.1 should yield issue 1.1.
• The number on side (v) indicates the place at which the virtual metadata representing this relationship (if any) will appear on volume 1.1. E.g. using the out-of-the-box configuration in virtual-metadata.xml, metadata field publicationissue.issueNumber of issue 1.1 would appear as metadata field publicationissue.issueNumber on volume 1.1 on place 0 (i.e. as the first metadata value).
• The number on side (i) indicates the place at which the virtual metadata representing this relationship (if any) will appear on issue 1.1. E.g. using the out-of-the-box configuration in virtual-metadata.xml, metadata field publicationvolume.volumeNumber of volume 1.1 would appear as metadata field publicationvolume.volumeNumber on issue 1.1 on place 0 (i.e. as the first metadata value).

With the groundwork out of the way, let's see what happens when we create a new version of volume 1.1. The new version is not yet archived, because it still has to be edited in the submission UI.

Image Added

At this moment, when viewing the item page of issue 1.1, the user should only see volume 1.1 (as volume 1.2 is not yet archived). When viewing the item page of volume 1.1, nothing has changed: only a link to issue 1.1 will appear. When viewing the item page of volume 1.2 (e.g. as an admin), a link to issue 1.1 will appear as well.

Image Added

As soon as volume 1.2 is deposited (archived), the "latest status" of both volume 1.1 and volume 1.2 are updated. When viewing the item page of issue 1.1, volume 1.2 should be visible. When viewing the item pages of the volumes, nothing has changed.

Let's create another version of the volume (not archived):

Image Added

And after archiving volume 1.3:

Image Added

What happens if we create a new version of issue 1.1?

Image Added

Only the relationship with volume 1.3 is copied. For issue 1.1, no relationship was displayed with volume 1.1 and 1.2. (The relationships still exist in the database, but are not visible in the UI.). For volume 1.1, a relationship to issue 1.1 remains present, but it should not be updated to issue 1.2. For issue 1.2, these relationships are longer relevant, so they are not copied.

On the item pages of volume 1.1, volume 1.2 and volume 1.3, you should see issue 1.1 (as 1.2 is not archived yet)

Because issue 1.2 is not yet archived, all volumes are still pointing to issue 1.1. Let's archive it:

Image Added

Now on the item pages of volume 1.1 and volume 1.2, you should see issue 1.1; it's the latest issue at the time that those volumes were superseded by volume 1.3. On the item page of volume 1.3, you'll see issue 1.3. On the item page of issue 1.1 you'll still see volume 1.3 as well.

Metadata fields that represent relations

If you have a closer look at items with relationships, you'll notice two categories of metadata fields that are controlled by DSpace:

• relation.* fields, for example relation.isIssueOfJournalVolume on volume items
• relation.*.latestForDiscovery fields, for example relation.isIssueOfJournalVolume.latestForDiscovery on volume items

Metadata fields of the first category (relation.*) contain all uuids of related items that the current item can see. I.e. a relationship has to exist between the current item and the other item, and the other item needs to have "latest status" for that specific relationship.

As an example take the following state of the previous section:

Image Added

Item issue 1.1 will contain metadata field relation.isJournalVolumeOfIssue with as value the uuid of volume 1.3. Volume 1.1 and 1.2 are not included because they don't have "latest status" on the relevant relationships.

Metadata fields of the second category (relation.*.latestForDiscovery) contain all uuids of the items for which the current item is visible. I.e. a relationship has to exist between the current item and the other item, and the current item needs to have "latest status" for that specific relationship. These fields are particularly important for indexing and search, because they allow to us to surface all the items that a particular item is referring to.

Continuing on the example above, issue 1.1 will have metadata field relation.isJournalVolumeOfIssue.latestForDiscovery containing the uuids of volume 1.1 and 1.2.

With issue 1.1 containing volume 1.1 and 1.2 in relation.isJournalVolumeOfIssue.latestForDiscovery, a search on the volume 1.1 page for all issues containing volume 1.1 will display issue 1.1 thanks to this setup.

Configure versioning for an entity type

DSpace contains a bunch of example entity types that support versioning out of the box. What follows is an overview of the requirements to make entity versioning work.

1. when introducing a relationship type, make sure to add four new metadata fields to config/registries/relationship-formats.xml. E.g. relation.isAuthorOfPublication, relation.isAuthorOfPublication.latestForDiscovery, relation.isPublicationOfAuthor and relation.isPublicationOfAuthor.latestForDiscovery
2. when introducing an entity type, filter items on latestVersion:true in discovery.xml. This will be the default search, which ensures older versions are not shown
   • If you want to show all related items, including older versions, you can create another discovery config without latestVersion:true. This should be used for item pages displaying the related items to the current item using the discovery search.
   • The entity types configured out-of-the-box have discovery config <entity-type> and discovery config <entity-type>Relationships for that purpose.

Note that versioning support is enabled by default, but can be turned off by setting versioning.enabled = false in versioning.cfg or local.cfg. For more details on item versioning, see: https://wiki.lyrasis.org/display/DSDOC7x/Item+Level+Versioning.

A bean of that ID then defines the value of the field, based on the related Entity. In this example, these fields are pulled from the related Person entity and concatenated.  If the Person has "person.familyName=Jones" and "person.givenName=Jane", then the value of "dc.contributor.author" on the related Publication will be dynamically set to "Jones, Jane.

 <bean class="org.dspace.content.virtual.Concatenate" id="publicationAuthor_author">
    <property name="fields">
        <util:list>
            <value>person.familyName</value>
            <value>person.givenName</value>
            <value>organization.legalName</value>
        </util:list>
    </property>
    <property name="separator">
        <value>, </value>
    </property>
    <property name="useForPlace" value="true"/>
    <property name="populateWithNameVariant" value="true"/>
</bean>

If the default Virtual Metadata looks good to you, no changes are needed.  If you make any changes, be sure to restart Tomcat to update the bean definitions.

Designing your own Entity model

When using a different entities model, the new model has to be configured an loaded into your repository

Thinking about the object model

First step: identify the entity types

• Which types of objects would you want to create items for: e.g. Person, Publication, JournalVolume
• Be careful not to confuse a type with a relationship. A Person is a type, an author is a relationship between the publication and the person

Second step: identify the relationship types

• Which relationship types would you want to create between the entity items from the previous step: e.g. isAuthorOfPublication, isEditorOfPublication, isProjectOfPublication, isOrgUnitOfPerson, isJournalIssueOfPublication
• Multiple relationships between the same 2 types can be created: isAuthorOfPublication, isEditorOfPublication
• Relationships are automatically bidirectional, so no need to worry about whether you want to display the authors in a publication or the publications of an author

Third step: visualize your model

• By creating a drawing of your model, you’ll be able to quickly verify whether anything is missing

Configuring the object model

Configure the model in relationship-types.xml

• Similar to the default relationship-types.xml, configure a relationship type per connection between 2 entity types
• Include the 2 entity type names which are being connected.
• Determine a clear an unambiguous name for the relation in both directions
• Optionally: determine the cardinality (min/max occurrences) for the relationships
• Optionally: determine default behavior for copying metadata if the relationship is deleted

Configuring the metadata fields

Determining the metadata fields to use

• Dublin Core works for publications, but not for a Person, JournalVolume, …
• There are many standards which can be easily configured: schema.org, eurocris, datacite, …
• Pick a schema which suits your needs

Configure the submission forms

• Add a form in submission-forms.xml for each entity type, containing the relevant metadata fields
• See also Submission User Interface documentation.
• Configure which relationships to create

Configuring the item display pages

• The metadata configuration is not specific to configurable entities.
• Similar to other customizations to the item display pages, configure in Angular which metadata fields to display and their label. A template per entity type can be created
• The relationship display is similar to the metadata configuration
• Similar to the metadata configuration: configure in Angular which relationship to display and their label

Configuring virtual metadata

• The isAuthorOfPublication relationship can be displayed for the Publication item as dc.contributor.author
• The isOrgUnitOfPerson relationship can be displayed for the Person item as organization.legalName
• This can be configured in virtual-metadata.xml

Configuring discovery

• Configure the discovery facets, filters, sort options, …
• The facets for a Person can be job title, organization, project, …
• The filters for a Person can be person.familyName, person.givenName, …

Additional Technical Details

The original Entities design document is available in Google Docs at: https://docs.google.com/document/d/1wEmHirFzrY3qgGtRr2YBQwGOvH1IuTVGmxDIdnqvwxM/edit

We are working on pulling that information into this Wiki space as a final home, but currently some technical details exist only in that document.

A talk on Configurable Entities was also presented at DSpace 7 at OR2021