Jisc logoEquipment Data Service

Set up an integration

The following steps are for setting up an integration with:

  • Pure equipment module (Web services API and Pure API)
  • Kit-Catalogue (v2.3.4)

Pure equipment module integration

The service can integrate with Pure web service or the Pure API. When you log-on to the data management platform you will be able to choose which API you want to integrate with our service.

Prepare for integration

  • Whitelist/allowlist our service IP: Once you register, we will set you up as a PURE API user we will send you our IP address in the email notification. The Jisc IP address will also appear on the integration page when you log-in to the platform as a reminder

  • For the Pure web services API: Ensure you your endpoint is set up to allow read-only access. We currently only use the /equipments endpoint

  • For the Pure API: Ensure the following end points haves have been set up for read-only access:

    • /equipment
    • /persons
    • /projects
    • /awards
    • /research-outputs
    • /organisations
    • /external-organisations

Steps for integration

  • Login to the data management platform and go to the “Manage your API integration” tile on the dashboard
  • Once on the API integration page where you will be able to see the status of the integration, add your API key, domain URL and choose frequency of harvest to set up the integration You will need to select which API you want to integrate with (the Web services API or Pure API)
  • Add your API key: typically, a mix of letter and numbers
  • Add your domain URL: the URL at which we can make the endpoint requests:
    • Pure web services API: https://pure.yourinstitution/ws/api/524 (the last three numbers indicate the API version)
    • Pure API: https//pure.yourinstitution/ws/api
  • Then set up the harvest frequency: e.g. daily, weekly, monthly etc
  • Then set up the preferred day for the harvest: e.g. Sunday, Monday etc
  • The click the “Enable connection” button at the bottom of the page
    • If you enable the integration for the first time and your institution had previously provided the service with data through a spreadsheet, once a connection is established with the API, these existing records will be deleted to avoid duplication
    • If the connection with the API is unsuccessful your records will not be deleted
    • You also have the option at this point to download the current records and cancel or proceed to the integration workflow
  • Once you proceed, this will bring up pop-up notification: “Establishing connection and harvesting records. Ensure you keep this window open – the harvesting will likely take a few minutes”
  • Successful connection: you will get a notification pop-up to say the connection has been successful and a link to the page to view your records, manually add metadata to non-harvested fields and make DOI requests
  • Unsuccessful connection: you will get a notification to say the connection has been unsuccessful. Please check your credentials and try again and if this doesn’t work, please notify us at help@jisc.ac.uk with “Equipment Data Service” in the subject line
  • Once you have a successful notification you will see the connection and harvest status on the left-hand side of the integration page and the status toggle will be turned to ‘active’ and appear green
  • Your records will have been harvested and published
  • To view your records: you can either click “View records” from the integration page or navigate to the dashboard on the home page and view records from “View records” tile
  • Note that on the ‘View Records Page’ you may not instantly see the harvested records. There is a notification to say that: ‘A harvest is currently underway. Check back again or refresh the page in a few minutes. If no records are showing by the time you try again, get in touch at help@jisc.ac.uk with ‘Equipment Data Service’ in the subject line.’
  • Once the records have been harvested on the “View records” page, you can view your published records from the API harvest and follow the request DOI workflow for those records which meet the mandatory fields. Go to the “Manage records” section for information on request DOI workflow
  • You can now also add metadata to the non-harvested fields which will not get overwritten with the next scheduled harvest

Kit-Catalogue integration

Prepare for integration

To integrate your Kit-Catalogue instance with the Equipment Data Management Platform you will need ensure you have updated your software to the latest version: Kit-Catalogue v2.3.4 https://github.com/kitcatalogue/Kit-Catalogue

Before you login to the data management platform you will need to configure your Json feed on your local Kit-Catalogue instance.

  • Kit-Catalogue Json feed now also provides an extended data feed with more information on public items: https://your-site/api/public/jisc.json
  • This new Json feed is compatible with the new data model for the Equipment Data service upgrade
  • This will allow the Equipment data service to import your items and include them in the national equipment search and allow you to also request DOIs for equipment on the data management platform (if mandatory fields have been met). See our data model in detail and requirement for mandatory fields
  • Because this API exposes more fields than the usual item listings, it is controlled by an additional configuration option
  • To enable the API, use the following local config setting:
    • $config['api.jisc.enabled'] = true;

Steps for integration

Steps for integration:

  • Login to the platform and go to the “Manage your API integration” tile on the dashboard
  • Once on the integration page where you will be able to see the status of the integration, add your configured Json feed and choose frequency of the harvest to set up the integration
  • Add your domain URL: the URL at which we can make the endpoint requests, usually: https://your-site/api/public/jisc.json
  • Then set up the harvest frequency: e.g. daily, weekly, monthly etc
  • Then set up the preferred day for the harvest: e.g. Sunday, Monday etc
  • Then click the “Enable connection” button at the bottom of the page
    • If you are logging in for the first time to the data management platform and your institution had previously provided the service with data through an existing Json feed, once a new connection is established with the new API, these existing records will be deleted to avoid duplication
    • If the connection with the API is unsuccessful your records will not be deleted
    • You also have the option at this point to download the current records and cancel or proceed to the integration workflow
  • Once you proceed, this will bring up pop-up notification: “Establishing connection and harvesting records. Ensure you keep this window open – the harvesting will likely take a few minutes”
  • Successful connection: you will get a notification pop-up to say the connection has been successful and a link to the page to view your records and make DOI requests
  • Unsuccessful connection: you will get a notification to say the connection has been unsuccessful. Please check your credentials and try again and if this doesn’t work, please notify us at help@jisc.ac.uk with “Equipment Data Service” in the subject line
  • Once you have a successful notification you will see the connection and harvest status on the left-hand side of the integration page and the status toggle will be turned to ‘active’ and appear green
  • Your records will have been harvested and published on data management platform
  • To view your records: you can either click “View records” from the integration page or navigate to the dashboard on the home page and view records from “View records” tile
  • Once on the “View records” page, you can view your published records from the API harvest to follow the request DOI workflow for those records which meet the mandatory fields. Go to the “Manage records” section for information on request DOI workflow
  • Note that on the ‘View Records Page’ you may not instantly see the harvested records. There is a notification to say that: ‘A harvest is currently underway. Check back again or refresh the page in a few minutes. If no records are showing by the time you try again, get in touch at help@jisc.ac.uk with ‘Equipment Data Service’ in the subject line.’
  • Once the records have been harvested on the ‘View records’ page, you can view your published records from the API harvest and follow the request DOI workflow for those records which meet the mandatory fields. Go to the “Manage records” section for information on request DOI workflow
  • You can now also add metadata to the non-harvested fields which will not get overwritten with the next scheduled harvest