Introduction

 The Arcadia-funded COAR Notify Project is developing and accelerating community adoption of a standard, interoperable, and decentralised approach to linking research outputs hosted in the distributed network of repositories with resources from external services such as overlay-journals and open peer review services, using linked data notifications. As part of this project, COAR is funding the development of platforms and systems to support the exchange of linked data notifications across partner organisations and the workflows to manage notifications in those platforms and systems. As the largest adopted repository platform in the World one of the first platforms to be addressed is DSpace the implementation of which has been entrusted to 4Science.

The application can receive and send LDN messages concerning items with external systems. The LDN system is the protocol of message exchanging; the Quality Assurance system is the mechanism used to approve or reject item updates.

How to enable

Configuration properties involved:

Relation with the Quality Assurance Correction Service

The LDN system, as a message exchanging i/o system, has an inbox and an outbox. Every LDN message refers to a Notify Service: all the Notify Services are configured manually from the admin application form. A Notify Service is just like an authority labelled on LDN messages.

...

The match between LDN message type and the QAEvent topic (suddenly created by the evaluation of the ldn message from the queue) is configured onto ldn-coar-notify.xml spring file. Every Processor owns a list of actions. An action is often an email to be sent and an action to create the qa event. The LDN processor receives the QAEvent topic as a parameter and creates the relative QAEvent.

LDN Autodiscovery mechanism

Third party system can retrieve the location of the repository LDN InBox via the LDN autodiscovery mechanism, nevertheless to be able to interact with DSpace they need to be approved by a Repository Administrators and listed in the LDN Services Directory (see next paragraph); otherwise their messages will be flagged as untrusted and not processed at all.

LDN Services Directory (Registering Services)

...

LDN Inbox queueing

LDN incoming messages are stored into the ldn_message database table. As far as the property ldn.enabled  is true and the incoming json is valid, the LDN Message is stored on the table. Together with the storage of the record, the queue status of the message is initialized. The queue_status column of the table contains the status of the LDN message inside the queue. All the possible queue_status values are described into the java class org.dspace.app.ldn.LDNMessageEntity as integer constants.

...

Please consider that this means that the corresponding QAEvent is not automatically created as soon as the LDN Message is received.
The QA Event related to the LDN Notification will be created only once the notification is successfully processed by the extractor (LDN queue status set to QUEUE_STATUS_PROCESSED).

Notify status boxes

Considering these possible scenarios here at: COAR Notify Protocol: Example Scenarios

...

When Offer message has been followed by a related Announce incoming message, the box shown is blue! It is blue because receiving an Announce means - then the message is extracted - we produce a new QA Event. As every QA Event it is shown on Item Page and myDSpace page.

Configuring automatic QA evaluation using the Level of Trust

Score is a number 0 < # < 1.
If the proper configuration is enabled an automatic check for approval of QAEvents is run once the LDN message is extracted.
On qaevents.xml  file the bean qaScoreEvaluation we can configure three different boundaries to automatically approve/reject/ignore the level of trust:

...

This feature must not be confused with the automatic triggering for LDN Inbound pattern

Sending LDN Notifications during the submission of an item

In the example below it is shown the submission of an Item with a new section for COAR-Notify.
In this section we can manually choose ldn-services (which were not marked as automatic) in order to ask for Review, Endorsement and Ingest to external services.
If No (non-automatic) pattern has been configured for the LDN Service this service will not be displayed in any of the dropdown. 

Automatic Inbound pattern triggering

When adding new LDN Inbound pattern to a LDN Service we can select if a pattern has to be automatic or not.

...

• No action is required during the submission to select the LDN Service for a specific pattern
• The service in not even listed in the COAR notify step of the submission 

Item filters for Inbound pattern

When adding inbound pattern to a service we have the possibility to add an item-filter for each described pattern

...

• If the pattern is flagged as automatic the item filter is evaluated automatically
  • if the item filter is respected the LDN Notification is stored and queued for sending
  • if the item filter is not respected the LDN Notification is not even generated an nothing will be sent to the external service
• If the pattern is not flagged as automatic the item filter is evaluated when choosing the service from the dropdown for Notify in the submission
  • if the pattern is not respected an error message will be displayed saying the selected LDN service cannot be used for the current item
  • if the pattern is respected no error message is displayed 

The LDN Consumer

The LDN Consumer is the consume responsible for generating the outgoing LDN Notification.

Item Filter is a non-mandatory field. It activates a filter to be applied to the item during the submission. 
If the item matches the item filter condition the submission will be successful: otherwise the submission will fail with a talkative message.
Visible item filters are configured into a static list mapped into item-filters.xml file - on a bean named ldnItemFilters. We established for the following item filter to be shown:

Has one Bitstream = the item must have exactly one bundle named "ORIGINAL";
Item is public = anonymous user can see/read the item;
Title starts with pattern = the dc.title metadata of the item must start with 'Pattern';
Type equals dataset = the dc.type metadata of the item must be 'Dataset';
Type equals dataset = the dc.type metadata of the item must be 'Journal Article';

item-filter.xml has all item filters declarations: only the ones declared inside the ldnItemFilters map are shown.

Image Added

The LDN Consumer

The LDN Consumer is the consume responsible for generating the outgoing LDN Notification.

This consumer is triggered any time an Item is successfully installed and a check against the This consumer is triggered any time an Item is successfully installed and a check against the registered LDN Services/patterns is done to generate the appropriate LDN Notification

This consumer is responsible for the handling of both automatic a non-automatic patterns

Understanding the structure of the LDN Notification

The LDN Notification includes some important section many of these if improperly set might led to errors in evaluations on the notification

Let's take a deeper look at the LDN Notification structure

@context

The context section is the same for any LDN Notification 

  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://purl.org/coar/notify"
  ]

actor

This section describes the actor which performs the request
This is a descriptive section and doesn't include important information

  "actor": {
    "id": "https://review-service.com",
    "name": "Review Service",
    "type": "Service"
  }

context

This is one of the most important section.
In this section we have a description of the Item being involved in the LDN Notification

...

other fields are descriptive fields for the item

  "context": {
    "id": "https://research-organisation.org/repository/preprint/201203/421/",
    "ietf:cite-as": "https://doi.org/10.5555/12345680",
    "type": "sorg:AboutPage",
    "url": {
      "id": "https://research-organisation.org/repository/preprint/201203/421/content.pdf",
      "mediaType": "application/pdf",
      "type": [
        "Article",
        "sorg:ScholarlyArticle"
      ]
    }
  }

id

The identifier of the LDN notification (Each notification has a different id)

inReplyTo

This field is used to reply to other LDN notification so that the system knows if the current notification is a response

object

This is a descriptive section of the received Review, Endorsement etc..

• id → is the URL of the review/endorsement etc.

  "object": {
    "id": "https://review-service.com/review/geo/202103/0021",
    "ietf:cite-as": "https://doi.org/10.3214/987654",
    "type": [
      "Document",
      "sorg:Review"
    ]
  }

origin

This is an important section since it is used (for incoming notifications) to determine the service among the registered ones.
If the service is not recognized as registered the notification is untrusted

The field being used for this check is inbox

  "origin": {
    "id": "https://review-service.com/system",
    "inbox": "https://review-service.com/inbox/",
    "type": "Service"
  }

target

This section is used to describe the target system involved in the notification workflow 

  "target": {
    "id": "https://generic-service.com/system",
    "inbox": "https://generic-service.com/system/inbox/",
    "type": "Service"
  }

type

This type section is important since it's determining how to process/evaluate any received notification

  "type": [
    "Announce",
    "coar-notify:ReviewAction"
  ]

...

Testing

Request Endorsement (LDN Message on item submission)

Let's configure a new Notify Service such as:

and save.

(NOTE: If you plan to test with Docker, the "Service IP Range" should likely include 172.23.0.1 – this is the IP that your Host machine will likely appear as when running the backend in Docker.)

Testing Announce Review against current repository

Let's trigger an Request Review (see COAR official pattern documentation here).

...

See below the successful response:

This means the LDN Message has been received.
At this point there's not feedback if the notification has been stored & enqueued or just stored as untrusted.

...

Let's accept it with a click on the Green Check.
Go back to the item page to see the new Review metadata!

Postman Collection for testing COAR-Notify Feature

Here’s the Postman collection for all test scenarios: 

...