COAR Notify Integration Guide for TDR and DSpace
Purpose: This guide explains how COAR Notify enables event-driven notifications between Texas Data Repository (TDR – Dataverse) and DSpace. It covers concepts, user workflows, admin configuration, training exercises, troubleshooting, and governance so repository managers and curators can confidently adopt Notify.
What is COAR Notify?
COAR Notify is an interoperability framework that uses Linked Data Notification (LDN) to transmit machine-actionable events (notifications) between scholarly systems. In our context, it connects Dataverse (TDR) and DSpace to coordinate actions like deposit, linking related items, and status updates across repositories without manual re-entry.
TDR Dataverse can now be configured to exchange messages with other applications that indicate there is a relationship between a dataset and a resource hosted by the other repository. A primary example would be relationships between a Dataset in a Dataverse (TDR) and a paper hosted in a DSpace repository (such as TDL’s). If a user enters metadata in either platform indicating a relationship to an item hosted in the other, the applications can exchange messages to alert admins and/or users of the other application so that they can add a reverse relationship in the other item’s metadata (if a dataset is “Cited By” a paper, the paper should have metadata indicating it “Cites” the dataset, and vice versa.)
The sending of messages is automated. There are a variety of configuration options in both Dataverse and DSpace that specify which fields trigger messages, where messages are sent, who receives messages, etc. The following guidance is specific to how TDR and the TDL DSpace are configured.
TDR ↔ DSpace: Supported Use Cases
The following patterns are commonly implemented when integrating TDR (Dataverse) with DSpace via COAR Notify:
Cross-repository linkage: When an item in DSpace references a dataset in TDR (or vice versa), Notify sends an Announce Relationship Activity to create or update cross-system references.
Review and moderation loops: Notify enables lightweight handshakes for curatorial review (e.g., DSpace collection receives an Offer from TDR; a collection admin reviews and Accepts or Rejects with a reason).
Roles and Permissions
Repository Manager: Configures COAR Notify endpoints and keys, sets policies, and monitors logs.
User/Collection Admin: Initiates offers, reviews incoming requests, accepts/rejects, and maintains links between related resources.
Submitter/Depositor: Triggers automatic notifications (e.g., upon publishing) based on configured policies.
System Architecture Overview
At a high level, each system plays two roles:
Sender: Produces outbox activities when relevant events occur (publish, update, link).
Receiver: Listens on inbox for incoming activities; authorizes sender; executes mapped actions.
Endpoints, security keys, and trust policies determine which messages are accepted and how they are interpreted.
End-to-End User Workflows
Link a DSpace Item to a TDR Dataset
In TDR, publish or update a dataset and include a “related publication” metadata field that points to a DSpace item identifier (handle or DOI).
There are six possible relation types (a subset of the larger set of relations supported by the DataCite schema for DOIs) with “Is Referenced By” being the default if nothing is selected.
The minimal metadata required to trigger a message is to indicate the Identifier or URL. The recommended entries would include specifying the Relation Type and the Identifier Type and, for DSpace, using the type “handle” and using the URL form of the Handle for a given DSpace item. If the Identifier Type is not specified, (Dataverse will still look at the Identifier and URL fields and will try to recognize Handles, DOIs, and URLs in either field.) The Citation field is primarily for use in the display and can be anything from an informal title to a citation in some standard format.
Once the metadata is saved, other editing can be done and then the dataset should be published. When publication succeeds, TDR will send a message to TDL DSpace. DSpace processes messages in batches so there can be a few minute delay before a message is processed.
TDR emits an Announce activity with a Link describing the relationship to the DSpace item.
DSpace receives the activity, validates origin, and updates its item’s “related data” field to include the TDR dataset link and relation type (e.g., IsReferencedBy).
Result: Users browsing the DSpace item see an authoritative link to the TDR dataset; analytics and discovery improve with consistent cross-references.
A user in DSpace looking that the item mentioned in the message will see a COAR Notify message:
And, after clicking “View” will see an entry that shows that a given Dataverse instance (the “Actor”) suggests a link between the item (“Jim Test 1”) and a dataset (the “Link”). THe user can then choose to accept, ignore, or delete the suggested link.
If the suggestion is accepted, the new metadata can be seen on the full item page:
ADD SCREENSHOT
If, at some future date, the dataset is updated and a new version is published, no message will be sent to DSpace unless a Related Publication has been edited or a new one has been added.
Offer a DSpace item for Association with a TDR Dataset
In DSpace, a collection admin selects Offer to propose linking a item to a target dataset in TDR (selected by DOI/Handle).
Starting in DSpace, create a new “Item” and, as part of its metadata, add the DOI of a dataset in TDR:
DOIs of the form https://doi.org/… and doi:... will trigger a valid message. Using just the alphanumeric identifier, e.g. “10.5074/FKNOAHNQ” for the example above, will not. Using the URL of the dataset’s page, e.g. “https://dataverse-training.tdl.org/dataset.xhtml?persistentId=doi:10.33536/FK2/SM4VJS” will also not send a valid message (and would not be recommended at all as that URL may change over time, unlike the DOI itself).
Relation metadata entered in the field above is visible on the item’s “Full item page” in DSpace, e.g.:
An item can be saved to allow more editing at a later date. The message to TDR is triggered when the “Deposit” button is pressed to make the Item public. DSpace processes messages in batches so there can be a few minute delay before a message is processed.
TDR user receives a review task generated from the incoming Offer and examines metadata, provenance, and relation type.
Once the message is received by TDR, if it refers to a valid dataset DOI, users who can publish the dataset will see a notification on their account’s notification page that will indicate which item in DSpace is referencing the dataset. If the user decides that a reverse link is desirable, they can add an entry in the Related Publications field as above. Since DSpace does not indicate the Relation Type, it is up to the user to determine what to enter in that field. Once the metadata is saved, the user may have a choice as to how to republish the dataset.
Privileged users (currently “superusers” in the system, but probably a wider set in the future) have an “Update Current Version” publication option. This is intended for relatively minor metadata changes (such as adding a back-link to a paper) that don’t change the scientific content of a dataset and, when used, does not result in a new version / incremented version number. When using “Update Current Version” Dataverse will not send any message to DSpace.
Normal users would have to publish a new “Minor” version (“Major” is also possible) which would create a new version, e.g. v1.1 and send a message to DSpace. While the message to DSpace is a ~duplicate of the original metadata, it would have the Relation Type information from Dataverse. A user in DSpace could either ignore/delete the response (understanding it as indicating that action has been taken on the TDR side), or accept it, which would add the metadata using the correct inverse relationship based on what was sent from Dataverse. (TBD: verify that relation types are being used in TDL DSpace)
User Accepts or Rejects. On Accept, both systems create reciprocal related-item links; on Reject, DSpace records the reason and notifies the proposer.
In DSpace, messages are only sent when an item is initially deposited. Subsequent edits adding a relationship, will not result in a message. (TBD - I think this is true but have not confirmed.)
Propagate Embargo Lifted from TDR to DSpace
TDR lifts an embargo at dataset level; policy triggers an Announce Update activity to subscribers (including DSpace).
DSpace updates related item display to remove embargo indicators and, if configured, refreshes thumbnails/metadata caches.
Administrator Setup
Before you begin, ensure outbound HTTPS and inbound webhook endpoints are available, TLS certificates are valid, and time drift is minimal for signature validation.
Dataverse (TDR) Configuration
Enable COAR Notify integration in application settings, exposing an LDN inbox and outbox for the TDR actor (repository-level or per-collection actor, depending on policy).
Register trusted DSpace actors with their public keys and inbox URLs. Establish allowed activity types (Announce, Offer, Accept) and relation mappings.
Map internal events to Notify activities (e.g., dataset publish → Announce Create; metadata update → Announce Update; curator action → Accept/Reject).
DSpace Configuration
Enable the Notify/ActivityPub module. Configure repository actor(s), inbox/outbox endpoints, and HTTP signature keys (Ed25519 or RSA as supported).
Add TDR as a trusted remote actor with its public key, accepted activities, and rate limits. Configure authorization rules that determine which collections can receive Offers and who can Accept.
Define metadata crosswalks: map relation types (e.g., isSupplementedBy, references, isReferencedBy) and identifiers (Handle, DOI) to local fields and display labels.
Security and Trust Controls
HTTP Signatures: Validate signatures and dates; reject unsigned or stale requests.
Allowlist Actors: Only process activities from configured, verified actors (TDR ↔ DSpace).
Rate Limiting: Protect inbox from bursts; surface 429s in logs for tuning.
Operations: Monitoring and Support
Dashboards: Track counts of sent/received activities, success rates, and processing latency.
Logs: Capture activity type, actor, object IDs, response status, and validation outcomes; correlate with repository audit logs (login, actions performed, source IP).
Alerts: Notify repository managers on sustained failures, signature errors, or schema mismatches.
Training Exercises
Use a non-production TDR and DSpace environment with COAR Notify enabled. Assign roles to participants: Curator (TDR), Collection Admin (DSpace).
Exercise 1: Cross-link a Dataset and Item
Create a test dataset in TDR with a clear title and DOI; publish it.
Create a test item in DSpace with a related-item placeholder field.
In TDR, add the DSpace handle to related publication and save. Confirm an Announce Link is sent and that DSpace updates its related data field.
Exercise 2: Offer and Accept
In DSpace, initiate an Offer to associate a preprint with a TDR dataset (select relation type references).
In TDR, review the incoming Offer, verify identifiers, and Accept. Confirm reciprocal links are created.
Exercise 3: Status Update
In TDR, change a dataset’s visibility from restricted to public.
Verify an Announce Update is emitted and that DSpace removes restricted indicators on the related item.
Troubleshooting
Common issues and fixes:
No incoming activities: Check firewall/network routing to inbox URL, TLS certificate validity, and that the actor is allowlisted.
Signature validation failed: Verify time sync, correct public key, and header completeness (Date, Digest, Signature).
Rejected activity type: Confirm both sides enabled the same vocabulary actions and mapped them to repository events.
Metadata mapping mismatch: Review crosswalks for relation types and identifiers; ensure handle/DOI normalization.
Rate limiting: Look for HTTP 429 responses; tune limits or stagger batch notifications.
Policy and Governance
Define a lightweight policy that documents which events are shared, who can initiate offers, acceptable partners, and how disputes or erroneous links are resolved. Include retention for logs, audit requirements, and accessibility of automated messages to end-users.
Operational Checklist
Actors configured on both sides (inbox/outbox URLs, keys, trust rules).
Event-to-activity mappings reviewed and tested for publish, update, link, offer, accept, reject.
Metadata crosswalks for relation types and identifiers validated.
Monitoring/alerts in place; support runbook updated; staff trained.
Reference Mapping: Activities to Repository Actions
Activity (Notify) | Triggered By | TDR (Dataverse) Action | DSpace Action | Who Sees It |
|---|---|---|---|---|
Announce Create / Update | Publish or edit dataset/item | Emit activity with identifiers and summary of change | Refresh related metadata; update badges/labels | Repository users viewing the related item (both systems), depending on display config |
Announce Link | Add related item reference | Send relation with type and target ID | Create reciprocal relation if trusted; flag for review if required | Users/collection admins in recipient system; end users see the link once accepted |
Offer / Accept / Reject | Curator proposes association | Receive Offer; curator Accepts/Rejects | On Accept, create link and log provenance; on Reject, record reason | Users/collection admins (review queue); decision may notify proposer |
Change Management and Communication
Schedule configuration changes during established maintenance windows; announce to repository stakeholders via existing user groups and mailing lists. Document any policy updates and provide short screencasts or one-page quick-starts for curators.
FAQs
Next Steps
Pilot with a small set of collections and datasets; verify mappings and acceptance criteria.
Finalize policy and update user training; add links to internal runbooks and support contacts.
Developer integration notes: Dataverse (TDR) and DSpace can exchange COAR Notify messages to maintain reciprocal relationships between datasets and repository items. The following summarizes how to use this in practice and when messages are emitted.
Quick Reference: What Triggers a Message? | Trigger Condition | Identifier Format(s) |
|---|---|---|
TDR → DSpace: Related Publications saved, then dataset published | Automated on successful publish (batch processing may delay) | DSpace handle (URL form preferred), DOI, or resolvable URL; Relation Type recommended |
DSpace → TDR: Item deposited (initial Deposit) with TDR dataset DOI in metadata | Sent on Deposit (initial publication only; batch processed) | Valid: https://doi.org/... or doi:... • Not valid: bare DOI (e.g., 10.xxxx/xxxx), Dataverse landing-pa |