COAR Notify / Orchestrator use cases

In this document all the COAR Notify examples are listed as main sections with a short description of the use-cases annotated with possible local implementation notes.

In each main section is divided in subsections to provide examples how a Mellon/Orchestrator setup might respond to incoming and outgoing notification messages.

1. Scenario 1 : Author requests review with possible endorsement (via overlay journal)

From COAR: The corresponding author requests a review from an overlay journal for one of their papers, held in a repository. The overlay journal notifies the repository of any successful reviews and endorsements.

The repository is interpreted as the Data Pod in the examples below.

The journal is interpreted as the Certification Service in the examples below.

• The Maintainer starts a review process at a Certification Service

  • It is not specified how this process should be started

  • It is assumed that the certification service knows or discovers the location of the Scholarly inbox of the maintainer

• The Certification Service starts a review workflow and sends after a while an Announce AS2 notification to the (Scholarly) Inbox of the Data Pod

  • The Announce contains as object a link to the published review

  • The Announce contains as object a link to an artefact on the data pod

  • It is assumed that the data pod will respond with a HTTP 200 or 202 to inbox submission by the certification service

  • The scholarly inbox MAY be the main inbox of the data pod or a specialized inbox created for the orchestrator

  • The data pod may MAY shape validation mechanisms in place and return HTTP 4** codes when an unknown notification shape was submitted to the inbox

• The Certification Service starts an endorsement workflow and sends an Announce AS2 notification to the (Scholarly) Inbox

  • In the use cases below, it is assumed that the same assumptions can be made for any Announce notification that is send by a certification service

1.1. Orchestrator reads the inbox of a data pod and updates an event log

• The Orchestrator polls the (scholarly) Inbox of the Data Pod

• The Orchestrator lists incoming notifications

  • The orchestrator MAY filter the inbox list for resource shapes

  • The orchestrator MAY ignore untrusted , invalid notifications

  • The orchestrator MAY filter out notifications about resources that don’t exist (anymore) in the data pod

  • The orchestrator SHALL processes each notification only once

  • The orchestrator MAY only have read permission to the inbox

  • In a shared inbox scenario, multiple applications plus the maintainer MAY want to act on incoming notifications

• The Orchestrator selected the notification it wants to process

• The Orchestrator updates the Artefact Lifecycle Event Log with the notification

  • The orchestrator MAY store a processed version of the Announce notification in the event log

  • The stored notification @id MUST be unique in all event logs of the data pod

  • The event update time SHALL be the time of writing the event log resource

  • The artefact lifecycle event log SHALL be public readable

What are the requirement on the shape of the event log.

An orchestrator that is triggered by an update to the data pod artefacts by some other mechanism is left out of this discussion.

1.2. A client App reads the event log and updates the artefact

• The App polls the Artefact Lifecycle Event Log of the Data Pod

  • The app knows that the event log is a trusted append only resource for relevant notifications that should be processed

    • The app doesn’t need to redo the work of the orchestrator to clean the data pod (scholarly) inbox

  • The app MAY filter the event log for shapes

  • The app MAY filter out self-referencing notifications

    • This is for cases where any update to the data pod could trigger an event log update

• The App list new events events not yet processed

• The App discovers the Announce event

• The App is configured by the maintainer to automatically update the artefact metadata with a review link

  • The app MAY send a notification to the Scholarly inbox to update the orchestrator of this fact

1.3. A maintainer uses the dashboard to read the event log and updates the artefacts

• The Maintainer opens the (Scholarly) Dashboard and list new events

  • The dashboard knows that the event log is a trusted append only resource for relevant notifications that should be processed

    • The dashboard doesn’t need to redo the work of the orchestrator to clean the data pod (scholarly) inbox

  • The dashboard MAY filter the event log for shapes

  • The dashboard MAY filter out self-referencing notifications

    • This is for cases where any update to the data pod could trigger an event log update

• The Maintainer discovers the Announce event

• The Dashboard suggest to update the artefact metadata in the Data Pod with the review link

• The Maintainer approves and the Dashboard updates the artefact metadata

1.4. The orchstrator use policies to update service hubs

• The Orchestrator has a policy to update a range of Service Hubs

  • This can be the same Orchestrator that processes the inbox or an institutional orchestrator

  • The orchestrator uses the event log as a trusted append only resource for relevant Notifications that should be processed

• The Orchestrator can poll a local event log

• The Orchestrator discovers the Announce event

• The Orchestrator matches the notification to a set of policies and notifies relevant services

2. Scenario 2: Author requests review with possible endorsement (via repository)

From COAR: Initiated by the corresponding author, a repository requests a review for one of its resources from a trusted review service. No acknowledgement is sent by the overlay journal, but it notifies the repository of any successful reviews and endorsements.

The repository is interpreted as the Data Pod in the examples below.

The journal is interpreted as the Certification Service in the examples below.

• In the Dashboard a Maintainer initiated a request for review using an Offer AS2 notification to the inbox of the Certification Service

  • The certification service SHALL respond with a HTTP 200 or 202 to the Offer

  • The certification service MAY validate the Offer and return 4** error messages

  • The Offer MUST contain the location of the (Scholarly) Inbox at the Data Pod

  • The Dashboard MAY send a carbon copy of the Offer to the (Scholarly) Inbox

  • The AS2 notifications MAY need signatures or other security measures that establish a trusted communication between the Dashboard and the Certificaton Service

• The Certification Service starts a review workflow and sends after a while an Announce AS2 notification to the (Scholarly) Inbox of the Data Pod

  • The Announce contains as object a link to the published review

  • The Announce contains as object a link to an artefact on the data pod

  • It is assumed that the data pod will respond with a HTTP 200 or 202 to inbox submission by the certification service

  • The scholarly inbox MAY be the main inbox of the data pod or a specialized inbox created for the orchestrator

  • The data pod may MAY shape validation mechanisms in place and return HTTP 4** codes when an unknown notification shape was submitted to the inbox

• The Certification Service starts an endorsement workflow and sends an Announce AS2 notification to the (Scholarly) Inbox

  • In the use cases below, it is assumed that the same assumptions can be made for any Announce notification that is send by a certification service

2.1. Orchestrator reads the inbox of a data pod and updates an event log

• The Dashoard sends a trigger to the Orchestrator to send an Offer AS2 Notification to the Certification Service

• The Orchestrator polls the (scholarly) Inbox of the Data Pod

• The Orchestrator lists incoming notifications

  • The orchestrator MAY filter the inbox list for resource shapes

  • The orchestrator MAY ignore untrusted , invalid notifications

  • The orchestrator MAY filter out notifications about resources that don’t exist (anymore) in the data pod

  • The orchestrator SHALL processes each notification only once

  • The orchestrator MAY only have read permission to the inbox

  • In a shared inbox scenario, multiple applications plus the maintainer MAY want to act on incoming notifications

• The Orchestrator selected the notification it wants to process

  • The orchstrator MAY ignore Offer notifications if they are found in the inbox

    • It MAY be a policy of the maintainer not to add local Offer requests to the event log

• The Orchestrator updates the Artefact Lifecycle Event Log with the notification

  • The orchestrator MAY store a processed version of the Announce notification in the event log

  • The stored notification @id MUST be unique in all event logs of the data pod

  • The event update time SHALL be the time of writing the event log resource

  • The artefact lifecycle event log SHALL be public readable

• The Orchestrator can poll a local event log

• The Orchestrator discovers the Announce event

• The Orchestrator matches the notification to a set of policies and notifies relevant services

3. Scenario 3 : Overlay Journal Announces Review and Endorsement of Pre-print to Aggregator

From COAR: An overlay journal announces that it has reviewed and endorsed a pre-print to a downstream aggregation service.

The journal is interpreted as the Certification Service in the examples below.

The aggregator is interpreted as the Awareness Service in the examples below.

• The Certification Service completes a review workflow and sends an Announce AS2 notification to the inbox of the Awareness Service

• The Certification Service completes a endorsement workflow and sends an Announce AS2 notification to the inbox of the Awareness Service

3.1. Pod doesn’t receive a notification

• The Orchestrator stays idle

4. Scenario 4 : Overlay Journal Endorses Pre-print (Initiated by Author)

From COAR: An author initiates a process for review and endorsement of their pre-print by filling in a form on the journal system. The information submitted includes the repository URI of the pre-print, a citeable PID (if available) and a link to the file.

The repository is interpreted as the Data Pod in the examples below.

The journal is interpreted as the Certification Service in the examples below.

• The Maintainer starts a endorsement process at a Certification Service

  • It is not specified how this process should be started

  • It is assumed that the certification service knows or discovers the location of the (Scholarly) inbox of the maintainer

• The Certification Service starts a endorsement workflow and sends after a while an Announce AS2 notification to the (Scholarly) Inbox of the Data Pod

  • The Announce contains as object a link to the published review

  • The Announce contains as object a link to an artefact on the data pod

  • It is assumed that the data pod will respond with a HTTP 200 or 202 to inbox submission by the certification service

  • The scholarly inbox MAY be the main inbox of the data pod or a specialized inbox created for the orchestrator

  • The data pod may MAY shape validation mechanisms in place and return HTTP 4** codes when an unknown notification shape was submitted to the inbox

4.1. See Scenario 1

• The possible use cases for the Orchestrator in Scenario 4 are equivalent to Scenario 1

5. Scenario 5: Repository requests review (on behalf of corresponding author)

From COAR: Initiated by the corresponding author, a repository requests a review for one of its resources from a trusted review service.

The repository is interpreted as the Data Pod in the examples below.

The journal is interpreted as the Certification Service in the examples below.

• The Maintainer starts via the Dashboard a review process by sending an Offer AS2 notification to a Certification Service

• The Certification Service review workflow evaluates the offer and sends an Accept AS2 to the Inbox of the Data Pod

• The Certification Service review workflows creates a review and sends an Announce AS2 to the Inbox of the Data Pod

5.1. See Scenario 2

• The possible use cases for the Orchestrator in Scenario 2 are functionally equivalent to Scenario 2

6. Scenario 6: Author submits to overlay journal using repository to host resource and reviews

From COAR: The corresponding author submits a paper to an overlay journal. The journal deposits the paper in a repository and arranges reviews. The reviews are deposited in the repository.

In the examples below the repository is interpreted as Registration Service.

The repository MAY request from a Maintainer a review for a manuscript.

The journal is interpreted as the Certification Service in the examples below.

• The Certification Service request that a Registration Service ingests a manuscript by sending an Offer AS2 notification

• The Registration Servic ingest workflow accepts the manuscript and sends an Accounce AS2 notification to the Certification Service

• Reviewers are invited to submit reviews to the Registration Service

  • How this is done is not specified

• The Registration Service notifies the Certification Service of a new review by sending an Announce AS2 notification

• The Certification Service starts an endorsement workflow and notifies the Registration Service with an Announce AS notification on success

6.1. Registration Service request review from maintainer. Orchestrator is triggered to send out AS2 notifications

• The Registration Service discovers the (Scholarly) Inbox of a Maintainer

• The Registration Service invites a Maintainer to submit a review by sending an Offer AS2 notification

• The Maintainer is notified about the offer

  • This can be done in many ways:

    • The orchestrator does actions to notify the maintainer about the offer (e.g. sending an email)

    • The dashboard polls the (scholarly)inbox and presents tasks to the maintainer

• The Maintainer accepts the task in the Dashboard

• The Dashboard sends a trigger to the Orchestrator to accept the Offer

• The Orchestrator updates the Event Log

• The Orchestrator sends an Accept AS2 notification to the Registration Service

• The Maintainer submits via the Dashboard a review

• The Dashboard send a trigger to the Orchestrator to announce the review

• The Orchestrator updates the Event Log

• The Orchestrator sends an Announce AS2 notification to the Registration Service

7. Scenario 7: Review Service Announces Review of Pre-print to Aggregator

From COAR: A review service announces that it has reviewed and endorsed a pre-print to a downstream aggregation service.

The review service is interpreted as the Certification Service in the examples below.

The aggregator is interpreted as the Awareness Service in the examples below.

• A Certification Service* publishes a review and endorsement

• A Certification Service* sends an Announce AS2 notification to an Awareness Service

7.1. Pod doesn’t receive a notification

• The Orchestrator stays idle

8. Scenario 8: Review Service Announces Review of Pre-print to Repository

From COAR: A review service announces that it has reviewed and endorsed a pre-print to the repository.

The review service is interpreted as the Certification Service in the examples below.

• A Certification Service publishes a review and endorsement

• A Certification Service sends an Announce AS2 notification to (Scholarly) Inbox of the Data Pod

8.1. See Scenario 1

• The possible use cases for the Orchestrator in Scenario 8 are functionally equivalent to Scenario 1

9. Scenario 9: Author requests reviews from review service, via repository

From COAR: A review service announces that it has reviewed and endorsed a pre-print to the repository.

The repository is interpreted as the Data Pod in the examples below.

The review service is interpreted as the Certification Service in the examples below.

• In the Dashboard a Maintainer initiated a request for review using an Offer AS2 notification to the inbox of the Certification Service

• The Certification Service starts a review workflow and sends after a while an Announce AS2 notification to the (Scholarly) Inbox of the Data Pod

• The Certification Service starts an endorsement workflow and sends an Announce AS2 notification to the (Scholarly) Inbox

9.1. See Scenario 2

• The possible use cases for the Orchestrator in Scenario 9 are functionally equivalent to Scenario 2

10. Acknowledgement

We thank Herbert Van de Sompel, DANS + Ghent University, hvdesomp@gmail.com for the valuable input during this project.