Contents
About
This feature is available in version 2.0-MS1.11 and later.
In order to avoid unnecessary duplication of data across institutions, increase standardization, and ease as much of the burden of data entry on users as possible we have introduced a new concept known as Commonly Used Resources. This concept has been internally referenced as 'globals' and this is reflected in the choice of property names. These resources will reside in a central repository that is maintained by the eagle-i team, although all institutions will have read-access to it. We strongly encourage users to select from Commonly Used Resources wherever appropriate when entering data in SWEET.
As of the 2.0-MS1.11 release, only resources that have the following resource types are eligible to be Commonly Used Resources:
Application effect
SWEET - background effect
Once the SWEET application has been configured to use Commonly Used Resources, the application will periodically query the Commonly Used Resources data repository for a minimal set (label and URI) of information from the published data. SWEET will then place a local copy of this minimal set of information in its own data repository, in a specialized graph (NG_GlobalProxy
). Subsequent uses of SWEET will present selections for the user from this specialized graph as well as the default and published graphs.
SWEET - entering data
In fields which have one of the above mentioned types as a range, users will now see a new group of listings at the top:
Resources that are not Commonly Used Resources will be listed at the bottom:
All other applications
From the perspective of the other eagle-i applications (search, dissemination pages), there is no visible effect. The triples containing the Commonly Used Resources will be resolved as the triple that it is.
Use
- This section documents how institutions/clients can use Commonly Used Resources in their applications. This section does not detail how to set up the Commonly Used Resources data repository itself.
- This section requires administrative access to the institution's data repository.
To start using this feature in your institution's installation, please follow these steps:
- Create a new user to the data repository
In order for the SWEET application to locally cache the minimal information about Commonly Used Resources in the institution's data repository, a new user needs to be created that has the ability to add, remove and read theNG_GlobalProxy
graph in the institution's data repository. See creating repository users for details on how to create a new user.
- Create a new user with a role of
Automated Agent
. In this example the username for the new user isGlobalUser
and the password isGlobalPw
. We will be referring to this new user in other parts of this section.
- Create a new user with a role of
- Edit configuration files
The next step is to edit the configuration files to tell the applications what credentials SWEET should use to cache the Commonly Used Resources data locally, how often should SWEET update its Commonly Used Resources data and where to find the Commonly Used Resources. For this step, we will be editing the configuration files that are located in the eagle-i home directory,${EAGLE_I_HOME
}, in theconf
directory and in the.config
directory.
eagle-i-apps-credentials.properties
To let the SWEET application know the credentials for this new user, a new set of properties needs to be added to the credentialed property file. This file is located in the.config
directory of the${EAGLE_I_HOME
} directory, i.e./opt/eaglei/.config/eagle-i-apps-credentials.properties
.
Add the following lines to theeagle-i-apps-credentials.properties
file:# GLOBAL SERVICE eaglei.datatools.globals.user=GlobalUser eaglei.datatools.globals.password=GlobalPw
Please substitute the username and password that you have created for the example ones.
eagle-i-apps.properties
This file is located in theconf
directory of the${EAGLE_I_HOME
} direcory, i.e./opt/eaglei/conf/eagle-i-apps.properties
.- To let the applications know to use Commonly Used Resources data repository and where that repository is, add the following lines to the
eagle-i-apps.properties
file:## -- GLOBALS -- # True if datatools needs to reach out to a global repository; Default is FALSE. # NB: If setting this to true, be sure to add the other properties that are needed # for configuring the global repository communication eaglei.datatools.uses.globals=true # the URL where the global data repository resides eaglei.datatools.globalRepository.url=https://global.eagle-i.net
- To let SWEET know how often it should update its
NG_GlobalProxy
with data from Commonly Used Resources repository, add the following lines to theeagle-i-apps.properties
file:You can tweak the frequency as you see fit, however we recommend 12 hours as the polling frequency.# the frequency to perform the polling for global information eaglei.datatools.globalPolling.frequency=12 # the time unit for the frequency, *must* be one of java.util.concurrent.TimeUnit # [DAYS, HOURS, MINUTES, SECONDS, MILLISECONDS, MICROSECONDS, NANOSECONDS] eaglei.datatools.globalPolling.unit=HOURS ## -- END GLOBALS --
- To let the applications know to use Commonly Used Resources data repository and where that repository is, add the following lines to the
whoami.xml
Insert the following snippet at the beginning of yourwhoami.xml
file, after the<local>
tag:Here is an example of a complete<global url="http://global.eagle-i.net"> <institutionList> <institution URI="http://purl.org/eagle-i/app-ext/#ERO_0000065_29" graphURI="test29"> <namespace>global.eagle-i.net</namespace> <logoSrc>images/logo_global.png</logoSrc> </institution> </institutionList> </global>
whoami.xml
file with the new information about the Commonly Used Resources:<?xml version="1.0" encoding="UTF-8"?> <local> <global url="http://global.eagle-i.net"> <institutionList> <institution URI="http://purl.org/eagle-i/app-ext/#ERO_0000065_29"> <namespace>global.eagle-i.net</namespace> <logoSrc>images/logo_global.png</logoSrc> </institution> </institutionList> </global> <node url="http://foo.bar.edu"> <institutionList> <institution URI="http://purl.org/eagle-i/app-ext/#ERO_0000065_3" graphURI="test3"> <namespace>foo.bar.edu</namespace> <label>Furry Object Orientation University</label> <logoSrc>images/logo_foo.png</logoSrc> </institution> </institutionList> </node> </local>
Activation
To activate this feature, the following must take place:
Client / Institution:
- Create a user for the repository which has the role of 'Automated Agent', i.e. iAmGlobalUser
- The Automated Agent role has add, remove, read access to the GlobalProxy graph.
- Add the following properties to the non-credentialed properties file:
- eaglei.datatools.uses.globals
- eaglei.datatools.globalRepository
[TODO] Optional properties
[TODO] Update properties document
- Add the following properties to the credentialed properties file:
[TODO]
- Add a new / edit whoami.xml file
[TODO: <global></global>]
Data Migration
[TODO] How to migrate existing data to use the globals
Advanced Topics
[TODO] Details about the implementation
[TODO] global annotation on type
[TODO] Use of the proxy ng
[TODO] Global instances are not searchable as a resource themselves
[TODO] NB: Tomcat will appear to take a little bit longer to shut down. This is expected because of the code for the global harvesting.
Troubleshooting
- I can't see any commonly used resources as options for Private Company and Funding Organization in my SWEET.
- Verify that your repository successfully harvested the globals
[TODO] expected logs for successful global harvest
- Verify that your properties have been configured
[TODO] expected logs for correct configuration
[TODO] example logs of incorrect configurations
- Verify that your repository successfully harvested the globals