Institutional ORCID Integration (IOI)

Institutional ORCID Integration (IOI) provides a way for institutions to support the use of ORCID iDs by their researchers and students.

It is designed for use in conjunction with a DSpace repository (currently supporting DSpace versions 5 and 6). It expects the DSpace expanded-ORCID-support patch to already have been applied.

It interacts with ORCID using version 3.0 of the ORCID API. For full functionality ORCID membership and access to the ORCID member API are needed. It can also be used with the ORCID public API, but with limited functionality.

Prerequisites

IOI has been tested on Ubuntu using PHP 7 and a MySQL 5.7.27 database. It is also recommended to install phpmyadmin to interact with the database.

Then, it is time to create the database structure. Available in the ioi.sql file.

To automatically run syncronizations between IOI and either DSpace or ORCID crontab tasks need to be set up separately. When running the scripts in the shell you can also provide a date argument to only syncronize items with changes after a certain date by using php-cgi.

Installing

After finishing the prerequisites, download the IOI code by clicking on the "Clone or download button" or by using this command line in the terminal:

cd YourFolderPath
git clone git@github.com:kaust-library/ioi.git

To set the constants, including the MySQL database, DSpace REST API, and ORCID API credentials, fill constants.php. The path of the file is:

config/constants.php

The database connection is set in database.php, using the credentials previously set in constants.php, the path of the file is:

config/database.php

Usage Scenarios

The configuration options in constants.php support several usage scenarios with different levels of functionality, summarized below:

	Scenario 1: ORCID Member Institution with DSpace Repository	Scenario 2: Non-ORCID Member Institution with DSpace Repository	Scenario 3: ORCID Member Institution without DSpace Repository
Collect authenticated ORCID iDs?	Yes	Yes	Yes
Add ORCID iDs to publication records in DSpace?	Yes	Yes	No
Add works to ORCID records?	Yes	No	No
Add institutional affiliation to ORCID records?	Yes	No	Yes

Settings Demo

Watch the settings demo video to see a demonstration of the setup of the application.

Interfaces

The public directory contains three interface endpoints. Your web server should be set up to point and provide access only to the public directory.

User Interface

public/orcid.php

orcid.php is the primary user interface. It allows users to connect to ORCID, grant permissions to the IOI application and review the information to be transferred.

Admin Interface

public/admin.php

admin.php is accessible to users listed as admin in the users table. It provides a dashboard of usage statistics for the application, as well as forms for sending emails to designated groups, updating the name attached to an ORCID iD in DSpace, and uploading organizational and persons information to the database.

Query Interface

public/query.php

query.php provides a basic endpoint for another university system to retrieve information as JSON or CSV about the ORCID iDs and works recorded in the application. You should define your own method of restricting access to this endpoint

Deployment

Production usage of the tool requires setting tasks to run periodically that synchronize information between the application, ORCID and DSpace. The task files are located in the tasks folder. To set the crontab tasks, open the terminal and sign in to your server. You can open the list of crontasks for your user by entering this command:

crontab -e

A file will open.

Each crontab task starts with five fields that define the frequency that the task will be run:

Below are sample crontab entries for the IOI tasks:

Harvest new and modified repository records from DSpace to the metadata table. This task is responsible for adding new or modified metadata records to the metadata table in the database. This is how you keep track of new works added to your institutional repository.

To run it every 10 minutes, add this line to the crontab:
```
*/10 * * * * /usr/bin/php YourFolderPath/ioi/tasks/harvestRepository.php
```
If you want to do an initial harvest or test harvest only for items added or modified after a certain date, and have installed php-cgi, you could also do the below:
```
*/10 * * * * /usr/bin/php-cgi YourFolderPath/ioi/tasks/harvestRepository.php fromDate=YYYY-MM-DD
```

Synchronizing works from IOI to ORCID. This task is responsible for updating the user records in ORCID with new works harvested to IOI from the repository, based on the permissions the users have already given the system.

To run it every day at 3 AM, add this line to the crontab:
```
0 3 * * * /usr/bin/php YourFolderPath/ioi/tasks/syncWorksToORCID.php
```
Send updated ORCID metadata into DSpace. This task will check that ORCID iDs are added to the DSpace record for each work that the user has selected as their own:

To run it every 30 minutes, add this line to the crontab:
```
*/30 * * * * /usr/bin/php YourFolderPath/ioi/tasks/updateORCIDiDsInDSpace.php
```

Synchronizing affiliations from IOI to ORCID ( optional task ). This task is responsible for updating affiliations in user records in ORCID based on the permission they gave to the system before. It only needs to be run if you are uploading new job titles, end dates, etc. for your users to IOI.
```
0 3 * * * /usr/bin/php YourFolderPath/ioi/tasks/syncAffiliationsToORCID.php
```

Institutional Branding

For the logo, please insert your institutional logo as an image (PNG, GIF, JPEG, etc. should all work ) inside the images folder :

../ioi/public/images

Use the name "logo" for your logo image.

For the icon, please replace favicon.ico with your institution's icon in the public folder:

../ioi/public

Use the name "favicon" for the icon and the extension must be .ico .

In constants.php you can also customize the color scheme used in the admin dashboard by changing the colors listed in LOCAL_COLORS to match your institution's colors.

Built With

PHP 7 - Primary coding language
phpmyadmin - Database Management Application
Bootstrap - CSS Framework
Jquery - JavaScript Library
Zing Chart - JavaScript Chart Framework

Authors

Daryl Grenz - Digital Repository Lead
Yasmeen Alsaedi - Repository Coordinator/Architect

Acknowledgments

We would like to thank Atmire for developing the DSpace expanded-ORCID-support patch, and the ORCID team for their feedback.

ezajko / ioi_orcid_dspace