In DSpace-CRIS relationships between items are managed via the Authority Framework.

Below an example with a supposed new Job Entity.

Configure ItemAuthority

Configure ItemAuthority using the authority.cfg file, where you have to link the metadata person.jobTitle to the JobAuthority, which has to be linked to the Job Entity.

In the authority.cfg file you need to add the following ItemAuthority to plugin.named.org.dspace.content.authority.ChoiceAuthority

org.dspace.content.authority.ItemAuthority = JobAuthority


Next, you need to add to the same file the following lines:

cris.ItemAuthority.JobAuthority.relationshipType = Job

choices.plugin.person.jobTitle = JobAuthority

choices.presentation.person.jobTitle = suggest
authority.controlled.person.jobTitle = true


Add the new entity

Add the new entity in the cris.cfg file:

cris.entity-type = Job

When creating a new entity, it’s also necessary to add the new entity to the db (entity table), running the following script:

./bin/dspace initialize-only-entity-types -d

This script will create only new Entity type, and will not duplicate the existing ones (i.e. add the new entity to the cris.cfg, without removing the other entries).
If no issue are present, the script doesn’t have any output.

New entity and correction request

Add new Job entity to correction request: [dspace-install]/config/entities/correction-relationship-types.xml

    <type>
        <leftType>Job</leftType>
        <rightType>Job</rightType>
        <leftwardType>isCorrectionOfItem</leftwardType>
        <rightwardType>isCorrectedByItem</rightwardType>
        <leftCardinality>
            <min>0</min>
            <max>1</max>
        </leftCardinality>
        <rightCardinality>
            <min>0</min>
            <max>1</max>
        </rightCardinality>
    </type>

Save relation in the db

The relation should be saved into the database

/bin/dspace initialize-entities -f ../config/entities/correction-relationship-types.xml

Submission form

In submission-forms.xml add the form for the new Job entity → you should have already done this:

<form name="jobstep">
        <row>
            <field>
                <dc-schema>dc</dc-schema>
                <dc-element>title</dc-element>
                <label>Nom de la fonction</label>
                <input-type>onebox</input-type>
                <hint>Veuillez entrer le nom de la fonction</hint>
            </field>
        </row>
</form>

If you wanted, you could also add some other metadata to the new form. For instance, dc.description for a broader description of the job.

item-submission

In item-submission.xml :

  • add the step definition

    <step-definition id="jobstep" mandatory="true">
      <heading>submit.progressbar.describe.jobStep</heading>
      <processing-class>org.dspace.app.rest.submit.step.DescribeStep</processing-class>
      <type>submission-form</type>
</step-definition>
  • and the submission process
    <submission-process name="job">
         <step id="collection"/>
         <step id="jobstep"/>
</submission-process>

On the UI

Once you have done all of this, you can configure the collection for the new Job entity, even just from the UI → create new collection → select entity → select form.

As it is, a new Job entity can be created either by submission in the Job collection, or during submission in the Person collection.

Adding a new Entity Type inside the CRIS layout tool

Before following these steps, you must have successfully configured the new Entity Type via the Authority Framework as described above.

Prerequisites:

  1. CRIS layout tool: Ensure you have access to the cris-layout-configuration.xls to manage the visualization and access to the item data.

  2. Spreadsheet software: Any software that can edit XLS files, such as Microsoft Excel or Google Sheets.

  3. Entity Type data: Prepare all the necessary data about the new entity you wish to add.

Step-by-Step guide:

Here’s an example to configure the new Entity Type 'Job ’.

In this example, it has been added two tabs, one containing entity metadata and a second one, performed by a RELATION type box, which lists all the Person related to the given Job entity.

  1. First of all, the new Entity Type has to be added inside the first sheet ‘tab’ which contains the details about all the tabs that need to be created. Inside the cris-layout-configuration.xls file you can go over the sheet ‘tab’ to starting to set up the new Entity wanted

  • Simply adding a new row below the last one configured and write down all your new Entity Type data inside the new cells → ENTITY, SHORTNAME, LABEL, PRIORITY, LEADING and SECURITY.


Entity: it is the label of the Entity Type to which the tab belong.

Shortname: it is a name assigned to the tab, used to refer to it in the other sheets and configuration. A tab’s shortname must be unique for a specific entity.

Label: it is the human readable name of the tab or the i18n key configured in the Angular application.

Priority: the tabs are sorted by priority in ascending order.

Leading: It can be y (yes) or n (no). If set to yes the tab is shown on the top of the item’s page and remains there even if the user browse the other tabs. In order for the profile details tab to always remain visible even when you scroll through the other tabs.
If set to no tab will all be placed at the bottom and a navbar will be displayed containing a menu entry of the configured Tab. Even if only a tab is configured the navbar is shown.

Security: it defines who has access to the tab

2. After the first sheet is set-up, you can move on to the second one → ‘tab2box’ that contains the details about all the boxes that need to be displayed within a specific tab.

  • Again, adding a new row below the last one configured and write down all your new Entity Type data inside the new cells → ENTITY, TAB, ROW, ROW_STYLE, CELL_STYLE and BOXES.

  • Entity: it is the label of the Entity Type to which the tab and boxes belong.

  • Tab: is the shortname of the tab. Entity and Tab columns are used to lookup in the tab sheet (Tab -> Shortname).

  • Row: The row of the tab where place the given boxes. If the same row is specified for the same tab, the boxes are placed in a new cell with the given cell style

  • Row_style: The row's style where the boxes are placed. Same row must have the same style (or at least empty)

  • Cell_style: The cell's style where the boxes are placed in the given row.

  • Boxes: is the shortname of the box. Entity and Boxes columns are used to lookup in the box sheet (Box -> Shortname). The Boxes column can be a comma separated list of boxes name.


3. Moving on to the third sheet → ' box ', all details about boxes that need to be created for the Entity Type will be specified over here.

The order in which they are listed will be respected for each entity type in the UI.

  • Adding a new row below the last one configured and write down all your new Entity Type data inside the new cells → ENTITY, COLLAPSED, TYPE, SHORTNAME, LABEL, CONTAINER, MINOR, SECURITY and STYLE.

  • Entity: it is the label of the Entity Type to which the box belong.

  • Collapsed. It can be y (yes) or n (no). When collapsed is y the box is shown as a closed panel in the default theme

  • Container. It can be y (yes) or n (no). When container is y the outline of the box is shown, including the section at the top with the name.

  • Type. It is the box’s type available options are listed in the utilsdata sheet

  • Shortname: it is a name assigned to the box, used to refer to it in the other sheets and configuration. A box’s shortname must be unique for a specific entity.

  • Label: it is the human readable name of the box or the i18n key

  • Minor. It can be y (yes) or n (no). Minor box are not used to determine if a tab actually has content to show to the user.

  • Security: it defines who has access to the box

  • Style. It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the box panel and can be used to bind the box to the bootstrap grid (i.e. col-md-6 to size the box to half page)

Notice that here as we mentioned before, it has been set up a box which is type ‘RELATION’.

Discovery queries are configured via discovery.xml file inside the following bean:

  • org.dspace.discovery.configuration.DiscoveryConfigurationService (config/spring/api/discovery.xml)

A map’s entry for each relation is provided, standard pattern for key is:

  • RELATION.<Entity>.<relationName>

Entity and relationName must match to what reported in xls file, box sheet, ‘ENTITY’ and ‘SHORTNAME’ entries for each relation.

For this example, RELATION.Job.personslinked identifies the relation that will be used to populate personslinked box configured in excel file for entity 'Job'.

  • Here a full example of how this RELATION is configured (fragments of code inside discovery.xml file):

<!-- Job -->
<entry key="RELATION.Job.personslinked" value-ref="relationJobPersonConfiguration"/>
<bean id="relationJobPersonConfiguration" class="org.dspace.discovery.configuration.DiscoveryRelatedItemConfiguration">
    <property name="indexAlways" value="true"/>
    <!--Which sidebar facets are to be displayed-->
    <property name="sidebarFacets">
        <list>
            <ref bean="searchFilterEntityType" />
        </list>
    </property>
    <!--The search filters which can be used on the discovery search page-->
    <property name="searchFilters">
        <list>
            <ref bean="searchFilterEntityType" />
        </list>
    </property>
    <!--The sort filters for the discovery search-->
    <property name="searchSortConfiguration">
        <bean class="org.dspace.discovery.configuration.DiscoverySortConfiguration">
            <!--DefaultSortOrder can either be desc or asc (desc is default)-->
            <property name="sortFields">
                <list>
                    <ref bean="sortTitleAsc" />
                </list>
            </property>
        </bean>
    </property>
    <!--Any default filter queries, these filter queries will be used for all
            queries done by discovery for this configuration -->
    <property name="defaultFilterQueries">
        <list>
            <!--Only find related items. The placeholder {0} will be replaced with scope (UUID of item)-->
            <value>person.jobTitle_authority:{0} AND entityType_keyword:Person</value>
            <value>-withdrawn:true AND -discoverable:false</value>
        </list>
    </property>
    <!--Default result per page  -->
    <property name="defaultRpp" value="10" />
    <property name="hitHighlightingConfiguration">
        <bean class="org.dspace.discovery.configuration.DiscoveryHitHighlightingConfiguration">
            <property name="metadataFields">
                <list>
                    <bean class="org.dspace.discovery.configuration.DiscoveryHitHighlightFieldConfiguration">
                        <property name="field" value="dspace.entity.type"/>
                        <property name="snippets" value="5"/>
                    </bean>
                </list>
            </property>
        </bean>
    </property>
</bean>


4. As a last step, If we have configured a metadata box, we need to go over the sheet 'box2metada' that is responsible to provide extra configuration details for metadata box such as the list of metadata to show within the box.

In this example we only have the dc.title metadata for this Entity Type.

  • Again we add a new row below the last one configured and write down all your new Entity Type data inside the new cells → ENTITY, BOX, ROW, CELL, FIELDTYPE, METADATA, VALUE, BUNDLE, LABEL, LABEL_AS_HEADING, RENDERING, VALUES_INLINE, ROW_STYLE, CELL_STYLE, STYLE_LABEL and STYLE_VALUE

  • Entity: it is the label of the Entity Type to which the box belong.

  • Boxes: is the shortname of the box.Entity and Box colums are used to lookup in the box sheet (Box → Shortname).

  • Row. The number of the row where the field will be added.

  • Cell. The number of the cell where the field will be added.

  • Row_style. The style of the row where the field will be added.

  • Cell_style. The style of the cell where the field will be added.

  • FieldType. The field’s type such as METADATA or BITSTREAM or METADATAGROUP

  • Metadata. The metadata key of the field

  • Value. For bitstream field only, limit the bitstream to list to the one where the metadata has such value

  • Bundle. Required for bitstream field only, limit the bitstream to list to the one that belong to a bundle with the specified name

  • Label: it is the human readable name of the field or the i18n key

  • Rendering. A custom display strategy to apply to the field

  • Style. It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the field container.

  • Style_label: It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the label.

  • Style_value: It defines extra information that can be used by the UI to personalize the view. In the default theme the style is added as extra CSS classes to the value.

  • Label_as_heading: It can be y (yes) or n (no). If yes the label is shown above the value rather than to the left

  • Values_inline: It can be y (yes) or n (no). If yes the values of the same metadata field are shown inline, if no are shown in column

Once the cris-layout-configuration.xls sheets have been correctly updated with the new Entity Type data, the file can be saved and imported via UI process.

Here’s the outcome result described in the previous steps:


  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.