Page History

...

Custom presentation & dynamic components

Statistics

Network

Metrics

Integration with the basic DSpace data model

Please note that Discovery is the default search provider since DSpace 4.0, whereas in previous releases of DSpace it needs to be manually enabled.

The DSpace-CRIS build of DSpace enables it by default also in 1.8.x, 3.x. it MUST NOT be turned off

Browse 

DSpace-CRIS extends the DSpace browse system to all the CRIS entities.

This means that the user is able to configure browsing on researchers, organization units, projects and second level dynamic objects such as Journals, Events, Laboratories, and so on for any entity that the user has defined.

The configuration syntax follows the same rules of the standard DSpace configuration.

There are two types of browse:

1.      Full, single level browse, which just list in a specific order the instances of an Entity class: Researchers, OrgUnits, etc.

2.      Metadata, two levels browse, that provide a first page listing the values of a configured metadata leading to a second page where the instances that have the clicked value for that metadata are listed

Full, single level browse 

The syntax to configure full browse (single level) is

index-name is used to refer to further configurations as the list of columns to show and generate the i18n keys for the navigation (menu links, page header, etc.)

display-type can be anything except metadata and metadataAuthority that are reserved word for the two level browse. It is recommended to use the prefix the shortname of the Class with the word cris

i.e. crisrp for researchers, crisou for orgunits, crispj for project and finally cris<shortname of the dynamic object>; again, this is just a convention to make the configuration more readable but any word than metadata or metadataAuthority can be used to define a full browse. A general name is useful when you want create several browse on the same entity (for example org unit) that explore different subsets (i.e. internal structure, external organization, etc.). Indeed, using the browse name it is possible to define filter to apply to the general SOLR query, see “Apply filters to the browse indexes”

sort-name is used to refer to the sorting configuration described below

DESC if used make the descending order the default for that browse

metadata to give access to the properties of the cris objects using a DSpace like metadata syntax you need to prefix the shortname of the PropertiesDefinition with the shortname of the entity class (same of above, crisrp, crisou, etc.). So if you want to use for sorting the property defined with shortname “myproperty” in researcher entity you need to write crisrp.myproperty

When the property that you are referring to is a pointer you can use the qualifier to access to property of the pointed object, i.e. crisrp.dept.name will be the name of the orgunit assuming that dept is the shortname of a property that keep the relation between the researcher and the orgunits. You can also use virtual metadata, see “ItemEnhancer: virtual metadata”.

value-type: can be one of title, text, date or any other alias used to configure a Sort Plugin, see https://wiki.duraspace.org/display/DSDOC3x/Configuration#Configuration-OtherBrowseOptions 

To configure which information/columns are displayed for any objects is possible to use the following configuration property

for example:

the configuration defined for a specific entity (crisrp, item, etc.) can be overridden for a specific browse using the following configuration

Metadata, two levels browse 

As for the DSpace item it is possible to define browse over a metadata (i.e. authors of an item). In this way the system will produce a two levels browse, the first level will show in a paginated way all the values of the metadata (i.e., all the authors) clicking on a single value will show the list of items that match the selection. Applying this concept to the CRIS entities, you can for example build a two level browse showing all the departments of the researchers and for any department the list of researchers affiliated

for example

index-name is used as reference in the column definition configuration to apply specific configuration for that browse

schema.element.qualifier defines the field upon which the browse is build

text|date specify if the values must be interpreted as String or Dates for sorting

Apply filters to the browse indexes 

It could be useful to restrict the set of objects for a specific browse applying additional SOLR filter query. To configure a filter for a specific browse you can define the following configuration property

display-type is the value of the second part of the browse configuration. It is metatadata or metadataAuthority for two levels browse or something else for the configuration of a full browse index.

For example

It will limit the browse to the items published after the 2000,

It will limit the browse to the OrgUnits that have the field “relationwith” valorized with a pointer to the OrgUnit ou00001.

ItemEnhancer: virtual metadata 

The enhancers allow to access information not immediately available in an object (item or cris object) as it was a direct metadata/field of the object. In this way is for example possible to access the item author’s affiliation as it was an item metadata.

There are three type of enhancer:

-          org.dspace.app.cris.discovery.CrisItemEnhancer, used to add dynamically to the item information from linked CRIS entities as it was metadata of the item

-          org.dspace.app.cris.discovery.CrisEnhancer, used to add dynamically to the CRIS entity information from linked CRIS entities as it was metadata of the current CRIS entity

-          org.dspace.app.cris.discovery.CrisNestedEnhancer, used to add dynamically to the CRIS entity information from the nested CRIS entities as it was metadata of the current CRIS entity

The enhancers are configured in the spring file [installDir]/config/spring/cris/cris-metadata-enhancers.xml

Below are included the snipped of an CrisItemEnhancer in the default configuration

The properties have the following meaning

-          alias, is the “element” of the virtual field

-          qualifiers2path, is a map whose key are the “qualifier” of the virtual field and the value the path, evaluated as EL, in the target object

-          metadata, is the list of item metadata to consider that linkage the item with the CRIS object

-          clazz, is the canonical name of the linked CRIS Entity class

The previous example will create the virtual metadata crisitem.author.dept that will be evaluated as valorized with the department of the researcher linked to the item through the metadata dc.contributor.author.

The following snippet show a CRISEnhancer and a CRISNestedEnhancer

The first one allow to use crispj.dept instead of cripj.coinvestigators.dept in this way the field of the target OrgUnit are available for indexing when working on the Project.

The second one allows access to the agencies (the value) of the nested object named grant (the alias) using the metadata crispj.agencies where agencies is the key of the qualifiers2path map.

Search configuration: indexes, facets 

The discovery module used by DSpace-CRIS has been extended to be able to manage also CRIS Entities. In the [installDir]/config/spring/api/discovery-solr.xml file a new implementation of the SearchService/ IndexingService has been defined

New special entries can be used in the definition of the DiscoveryConfigurationService in the [installDir]/config/spring/api/discovery.xml file to allow specific configuration for entity type:

The map containing all the settings, the key is used to refer to the page/scope of the search, the "site", a community/collection handle or an entity type, the value-ref is a reference to a spring bean that actually define the DiscoveryConfiguration format.

default is the configuration key used if a not more specific one exist for the current search/indexing scope

dspacebasic is the fallback configuration key for all the standard DSpace Objects: Items, Collections and Community

crisrp is the configuration key used searching/indexing a ResearcherPage

crispj is the configuration key used searching/indexing a Project

crisou is the configuration key used searching/indexing an OrgUnit

cris<shortname> is the configuration key used searching/indexing a Dynamic Object with <shortname>, for example journal

The searching scope is defined by the UI implicitly when the search is performed from a “specific page” as a community or collection home page or explicitly when the user choose to restrict the search to a specific subset.

During the indexing phase the scope/configuration key is defined as follow

Standard DSpace objects such Items, Collections and Communities, the configuration key is the handle of the object if not found the parent object handle will be used as fallback until to the dspacebasic or default key

CRIS Objects such ResearcherPages, OrgUnits, Projects, Dynamic Objects, the configuration key is dedined the by the entity type with fallback to the default key

To configure a DiscoverySearchFilter, DiscoverySearchFilterFacet, DiscoverySortFieldConfiguration the “DSpace like metadata syntax” previously explained, see metadata in the Browse customization.

Custom Indexer Plugins

The following IndexerPlugins has been added in the [installDir]/config/spring/api/discovery.xml file

Additional indexing plugin to implement the CRIS browse system via SOLR

Additional indexing plugin to implement CRIS relations preferences, see “Relation Preference Management”, via SOLR

Additional indexing plugin to add bitstream identifier to item SOLR document, this is used by the extended statistics functionalities as bitstream download are associated to the item using SOLR join query, see “Statistics configuration” for further details

Additional indexing plugin to add resource type in human format readable to SOLR document

Additional indexing plugin to add cris authoritylookup for authority framework works with dynamic resource type to SOLR document

Global search

What is it? How is it configured[BA2] ? 

Custom JSPs 

To customize the presentation of the data of a CRIS entity other than rearranging the order of the data inside a box and deciding positioning, see “Group Metadata, aka boxes”, the system allow you to define your custom JSPs used instead of the out-of-box layout.

You can use custom JSPs for example to add javascripts both in the visualization mode than in edit mode, show content retrieved from external systems, add static or dynamic content implementing the components or processors extension points (see below).

CRIS Components & processors[BA3]  

The system allows extension thought the use of component that can extends the presentation, tools and functionalities available for any entities.

The components are registered in the [installDir]/config/spring/cris/cris-components.xml spring file. For any CRIS entity type has been defined a service where that manage the components, these services need to be named rpComponentsService, pjComponentsService, ouComponentsService and doComponentsService. The first two letters of the service name refer to the short name of the related CRIS Entity: ResearcherPage (rp), Project (pj), OrgUnit (ou), Dynamic Object (do).

The snippet below show the default configuration for the Researcher Page components Service

Out-of-box the system include configurable components to explore inverse relationship between a CRIS object and DSpace items and a CRIS object and other CRIS objects. This approach other than be time saving make also the data model more consistent avoiding the creation of wrong unilateral relationship. For example: if a researcher belongs to a department it has to be set up a pointer field via UI (see “Field Definition”). However, the OrgUnit entity not need a pointer to track the relationships between the department and all its researchers. The component executes the appropriate SOLR query to retrieve the referencing objects. The snippet below show the configuration of the publicationList component for the ResearcherPage

org.dspace.app.webui.cris.components.ItemsConfigurerComponent is the implementation of the abstract class org.dspace.app.webui.cris.components.ASolrConfigurerComponent<T extends DSpaceObject, IBC extends ICrisBeanComponent> able to manage relationship between CRIS objects and DSpace Items. The following class provide similar functionalities for the other kinds of relationship

·         org.dspace.app.webui.cris.components.CRISDOConfigurerComponent able to explore relationship with Dynamic Object

·         org.dspace.app.webui.cris.components.CRISOUConfigurerComponent able to explore relationship with OrgUnit

·         org.dspace.app.webui.cris.components.CRISPJConfigurerComponent able to explore relationship with Project

·         org.dspace.app.webui.cris.components.CRISRPConfigurerComponent able to explore relationship with ResearcherPage

The following attributes define the behavior of such classes

·         relationConfiguration defines a relation between two Entity Class (CRIS Objects or DSpace Item), see the dedicated paragraph for further details

·         commonFilter defines an additional SOLR filter query to apply to the relationship

·         target must match the class canonical name of the target Entity in the relationship, i.e. if the relationship is Item – ResearcherPage (author) the target class is the ResearcherPage

·         types is a map that allow clustering of the relationship under user-defined category (facet query), see the dedicated paragraph for further details

Relationship definition 

The relationships are defined in the [installDir]/config/spring/cris/cris-relationpreference.xml

A relationConfiguration is shown in the snippet below

It is defined by

·         relationName, an unique name that characterize the relationship

·         relationClass, the class canonical name of the Entity Class that holds the main direction of the relationship

·         query, the solr query that can be used to retrieve the objects linked to the “current” object. {0} will be replaced with the authority key of the current object

Relation Preference Management 

The relationConfiguration are used other than by the components by the RelationPreferenceService that can be enabled over one or more relationship so to allow the user to hide some relationship of make a selected list. The RelationPreferenceService is configured through the definition of a spring bean for the class org.dspace.app.cris.configuration.RelationPreferenceServiceConfiguration the default configuration is shown below

The RelationPreferenceServiceConfiguration keeps a list of RelationPreferenceConfiguration that defines for a specific relationConfiguration which actions (select, hide, unhide, unlink[1]) are available and to whom (researcher and/or system administrators). Finally, the columnsVisualizationConfiguration allows to define which columns show in the relation management functionality (see ) and the extraAction allows to inject the business logic needed to manage the preference changes (from a standard relationship to a selected one, from an hide relationship to a standard one and so on).

Relation Clustering 

The configuration of the clustering categories are done using spring beans. The snippet below show the default configuration for a “journal article” category applied to the publication list

The facetQuery property is evaluated replacing {0} with the authority key of current object and {1} with the uuid.

Statistics configuration 

The SOLR Statistics system of DSpace has been extended in several aspects. It is now able to collect and visualize statistics about the CRIS Entities as allow further extension using StatsIndexPlugin in a similar way than the IndexerPlugin for the Search system.

The extended implementation is configured in the [installDir]/config/spring/statistics-solr.xml file

The [installDir]/config/spring/statistics.xml file contains the spring beans definition to configure the extra indexers to invoke collecting statistics and most of the UI aspects of the statistics functionalities (number of  “top relation”, “top country” to show, timeline, etc.)

Allow the indexing of the unique key of the SOLR search document in the statistics document so to allow the use of SOLR join query to retrieve statistics of related objects (i.e. number of visualization over time of all researcher’s items, top visualized items for researcher, etc.)

The configuration of the statistics functionalities for the DSpace standard entities (Items, Collections and Communities) are done through spring beans. The following snippet show the default configuration for the DSpace Items

Most of the properties are self-explained; the one that need further details is components. A map of referring beans that describe the sections available in the statistics UI for DSpace Items.

There are two sections:

-          selectedObject, is the reserved word to define the StatComponent “section” used to visualize the statistics of the current object

-          bitstream, it defines a “section” where the top bitstream visualization are shown

Also the configuration of the statistics functionalities for the CRIS entities (ResearcherPage, OrgUnit, Project and DynamicObject) are done through spring beans. The following snippet show the default configuration for the ResearcherPages

The bean definition is very similar to the definition used for standard DSpace Entities except for the components management. For the CRIS Entities the components are derived by the definitions done in the CrisComponentService, see “CRIS Components”.

This mean that the user defined categories for clustering the relationship, for example the researcher’s publication list by publication type, are used also in the statistics functionality so to show view and download of all the researcher’s publication over time by publication type.

The current object is specified as direct property of the CrisStatComponent bean

These settings are injected in the UI using spring beans definition in [webapp-JSPUI]/WEB-INF/springmvc-rp-servlet.xml, the following snippet show the injection of the rpStatsComponets

The rpStatisticRequestsManager is indeed defined in

[webapp-JSPUI]/WEB-INF/spring/applicationContext-rp.xml 

where the factory bean researcher is only used to access the upper level “dspace-api” Spring Context.

Network configuration 

The system is able to draw graph about network collaborations, see “Network visualization”, between Researchers using data in the RPs, Projects, OrgUnits, Dynamic Objects and DSpace Items.

The system use the Jit javascript library (http://thejit.org/ ) to draw the graphs. A customized version of the RGraph layout has been developed. This customization changes the positioning algorithm of the nodes. Nodes are equally positioned in the “circle” corresponding to the degree of the relationship and not limited to the area of circle “assigned” to the intermediate node at the previous level. Below there is a comparison between the DSpace-CRIS customization (on the left) and the standard RGraph layout.

The relationships that are used by the system to build the network are defined as plugin in the network.cfg file

all the connection-type needs to implement the it.cilea.surplus.oa.network.NetworkPlugin

A special, single plugin implementation is used to provide the “Department network: visualization & metrics”

The network.connection property define the exact order used to list the network in the UI

The UI load the graph data asynchronous via JSON. In the JSP UI there is a single servlet able to produce JSON for different purpose using plugins, these plugins are configured in the dspace.cfg file with the following names: collaborationnetwork, departmentnetwork

The colors used by a specific connection-type is defined as follow

As the number of nodes and connections in the graph grow, the graph will become more and more unreadable and less useful so the system allows to set some configuration properties that limiting the visualized data to the most important and will keep the graph more clear and fast to load.

Limiting the number of nodes shown could produce some unexpected behavior. For example, if you limit the display to the first 10 top co-authors  than, in the case that, the 11th co-author of the focus RP is also in the top ten list of co-authors for one or more 1st level co-author this 11th co-author will be show as 2nd level relationship. But, when the user click on it, the system will report that the relationship with the focus RP is a first level relationship and the strength of the relationship will be shown.

For some relationship it is useful introduce some limit also during the indexing phase for both performance and meaning reasons. Looking for co-keywords relationship including all the keywords used in any publication is a no sense because some keywords are really general and widely used. Look to these keywords will produce a network of all the RPs and external authors in the repository. A better strategy is to only assign a keyword to an RP or external author if these people have used the keyword more than other. We look for all the keywords used in the repository and we assign any keyword to the top X authors that use it.

This limitation could be applied to the co-interest, co-discipline, co-keywords in grant, etc. as well.

The batch script 

org.dspace.app.cris.batch.ScriptIndexNetwork (you can use the –a option to elaborate any connection-type or –s <alias> to elaborate a single connection-type) is used to build a dedicated SOLR core where network information are pre-assembled.

Network metrics 

For any network the system is able to calculate four metrics

-          Numbers of collaboration

-          Max strength of the collaboration in the network

-          Average strength of the collaboration network

-          Quadratic variance of the collaboration network

These metrics are calculated by the batch script:

These values are stored in the RP data so that, if desired, you can also show them in the public RP visualization

The SOLR network core 

The SOLR core used by the network visualization is defined as follow

In the network core a SOLR document represent a connection between two nodes (RP, external or department), the document includes the following fields:

-          connection-type: the network alias (coauthors, interests, etc.)

-          node A: text value, authority (rp key), rp department

-          node B: text value, authority (rp key), rp department

-          connection-value: the publication in common (co-authorship), the keyword (co-keywords), the interest (co-interest) etc.

-          focus: these fields (values, authority) are automatically copied from the node fields to get fast response to some queries

-          dept: this field contains the concatenation of the node A department and node B department field separated by a |||. It is used to get fast response to some queries 

Use DSpace-CRIS entities as DSpace authority 

All the DSpace-CRIS Entities can be used as authority for Item’s metadata. The system provides the following ChoiseAuthority plugins

the following snippet from the default configuration show how to configure the ResearcherPages as authority for the dc.contributor.author metadata, the Projects as authority for the dc.relation metadata, the OrgUnits as authority for the dc.description.sponsorship and a DynamicObject “Journals” as authority for the dc.relation.ispartof metadata.

It must be noted that the DOAuthority allows to define a SOLR query filter to limit the set of objects available as authority for example to only a specific Dynamic Object type.

resourcetype_filter is a SOLR field that contains the human-readable translation of the resource type (item, researcher, orgunit, etc.) it is configured in the [installDir/config/modules/cris.cfg] file as follow

If you have used the ItemEnhancer to add virtual metadata to the DSpace Item exploring the relationship with CRIS objects for the search and/or the browse system, see “ItemEnhancer: virtual metadata”, you need to define an authority also for that virtual metadata to allow proper indexing of the authority key, variants and label.