HandshakingUseCases

This page provides the use cases governing the TreeBASE submission integration process.

Use Case: Submit Dryad Data Package to TreeBASE
Scope: Dryad Repository, TreeBASE Repository

Level: User goal

Primary actor: Dryad submitter

Stakeholders and interests:

Minimal guarantee: Dryad logs how far it got
 * Dryad submitter: wants to publish data package in TreeBASE
 * TreeBASE: wants data package which has already been entered into Dryad
 * Dryad: wants to share submitted data package with TreeBASE

Success guarantee: data package is published in TreeBASE

Preconditions: Trigger: User instructs Dryad to submit data package to TreeBASE
 * 1) User is logged in to Dryad
 * 2) User has completed Dryad submission process

Main success scenario: Extensions:
 * 1) User instructs Dryad to submit data package to TreeBASE.
 * 2) Dryad creates SWORD package and forwards to TreeBASE.
 * 3) User is instructed to log in to TreeBASE to complete the submission.
 * 4) User logs in to TreeBASE and completes the submitted records.
 * 5) TreeBASE publishes item.
 * 6) Dryad adds TreeBASE item to repository.
 * 2.1 Dryad encounters an error while creating the SWORD package.
 * 2.1.a) Dryad informs user of the error and instructs them to try again later.
 * 2.1.b) Use case terminated.
 * 2.2 TreeBASE submission process does not complete successfully.
 * 2.2.a) Dryad informs user of the error and instructs them to try again later.
 * 2.2.b) Use case terminated.
 * 4.1 User does not complete submission process.
 * 4.1.a) Dryad curator is notified of items submitted to TreeBASE which have not appeared in TreeBASE OAI feed.
 * 6.1 The item never shows up in the TreeBASE OAI feed.
 * 6.1.a) Dryad curator is notified of items submitted to TreeBASE which have not appeared in TreeBASE OAI feed.
 * 6.2 Dryad encounters an error adding TreeBASE item to repository.
 * 6.2.a) System administrator is notified of the problem.
 * 6.2.b) Return to main success scenario step 6.

Note: The Dryad curator may not have approved the entry before this use case is initiated.

Use Case: Submit SWORD Package to TreeBASE
Scope: Dryad repository, TreeBASE repository

Level: Subfunction goal

Primary actor: Dryad repository

Stakeholders and interests: Minimal guarantee: Dryad logs how far it got
 * Dryad: wants to receive a 201 Created response from the TreeBASE SWORD server
 * TreeBASE: wants to successfully process a POST request from Dryad SWORD client

Success guarantee: Dryad receives a 201 Created response from the TreeBASE SWORD server

Preconditions: Trigger: Step 1 of Submit Dryad data package to TreeBASE use case
 * 1) None.

Main success scenario: Extensions:
 * 1) Dryad creates SWORD package for specified data package (see SWORD package details).
 * 2) Dryad submits a POST request to TreeBASE SWORD server with ORE resource map describing data package as payload.
 * 3) TreeBASE begins processing ORE resource map.
 * 4) TreeBASE encounters aggregated data file resource.
 * 5) TreeBASE initiates GET request for data file URI and compares checksum of file with checksum in response header.
 * 6) TreeBASE adds data file and associated metadata to repository.
 * 7) TreeBASE reaches end of ORE resource map.
 * 8) Dryad receives   response from TreeBASE.
 * 1.1 Dryad encounters error creating SWORD package.
 * 1.1.a) Dryad generates error message and terminates use case.
 * 2.1 POST request times out.
 * 2.1.a) Dryad generates error message and terminates use case.
 * 7.1 TreeBASE finds another data file in resource map.
 * 7.1.a) Return to step 5 of main success scenario.
 * 3-8 A number of different errors could occur during the processing of the SWORD package. I've made a list of errors that seem reasonably possible along with each error's associated HTTP response code. It should be noted that any response other than a  received by Dryad from the TreeBASE SWORD server during these steps should be considered an error. In these cases, Dryad will generate an error message and terminate the use case. TreeBASE should include a detailed error document in the response as outlined in section 5 of the SWORD specification.
 * TreeBASE encounters an error processing the resource map: generates a  response.
 * TreeBASE does not receive a  response from Dryad when GETting data file: generates a   response.
 * Checksum header is missing from Dryad response to GET request, or does not match checksum generated by TreeBASE for data file: generates  response.
 * TreeBASE encounters error adding data package to repository: generates  response.

Use Case: Harvest TreeBASE OAI Feed
Scope: Dryad repository, TreeBASE repository

Level: User goal

Primary actor: Dryad repository

Stakeholders and interests: Minimal guarantee: Dryad logs how far it got
 * Dryad: wants to add items from TreeBASE to its repository
 * TreeBASE: wants to share items with Dryad

Success guarantee: TreeBASE items are added to Dryad

Trigger: System initiates via cron job or similar.

Main success scenario: Extensions:
 * 1) Dryad retrieves TreeBASE OAI feed, requesting items published since last retrieval.
 * 2) Dryad begins processing OAI feed.
 * 3) Dryad encounters item in OAI feed.
 * 4) Dryad adds TreeBASE item to the repository.
 * 5) Dryad reaches end of the OAI feed.
 * 1.1 Dryad encounters an error retrieving OAI feed.
 * 1.1.a) Dryad generates error message and terminates use case.
 * 2.1 Dryad determines the OAI feed is invalid.
 * 2.1.a) Dryad generates error message and terminates use case.
 * 4.1 Dryad encounters an error adding item to repository.
 * 4.1.a) Dryad generates an error message and continues to step 5 of the main success scenario.
 * 5.1 Dryad encounters another item in the OAI feed.
 * 5.1.a) Return to step 4 of the main success scenario.

Use Case: Add TreeBASE Item to Dryad
Scope: Dryad repository, TreeBASE repository

Level: Subfunction goal

Primary actor: Dryad repository

Stakeholders and interests: Minimal guarantee: Dryad logs how far it got
 * Dryad: wants to add TreeBASE item to repository
 * TreeBASE: wants to share item with Dryad

Success guarantee: TreeBASE item is added to Dryad

Preconditions: Trigger: Dryad encounters an item in TreeBASE OAI feed.
 * 1) Dryad has successfully harvested TreeBASE OAI feed.

Main success scenario: Extensions:
 * 1) Dryad matches TreeBASE item to Dryad item.
 * 2) Dryad updates item's dc:relation element in its repository with TreeBASE ID and adds any missing metadata.
 * 1.1 Dryad is unable to match TreeBASE item to Dryad item.
 * 1.1.a) Dryad creates a new item in the repository and marks it as uncurated.
 * 2.1 Dryad encounters error updating item in repository.
 * 2.1.a) Dryad generates error message and terminates use case.

Use Case: Link Dryad Item with TreeBASE Item
Scope: Dryad repository, TreeBASE repository

Level: User goal

Primary actor: Dryad user

Stakeholders and interests: Minimal guarantee: User will be informed of status of link
 * Dryad user: wants to create a link from a Dryad data package to an existing TreeBASE item
 * Dryad: wants items in repository linked to items in TreeBASE

Success guarantee: User will see the link to TreeBASE item show up in Dryad.

Preconditions: Trigger: user instructs Dryad to create a link to a specific TreeBASE item.
 * 1) User knows the ID of the already published TreeBASE item.
 * 2) User has completed Dryad submission process.

Main success scenario: Extensions:
 * 1) User instructs Dryad to create a link to the specified TreeBASE ID.
 * 2) Dryad uses the ID to fetch a minimal amount of metadata from TreeBASE and displays this to the user.
 * 3) User confirms this is the correct record.
 * 4) Dryad updates the data package's dc:relation element with the associated TreeBASE ID.
 * 2.1 Dryad encounters error communicating with TreeBASE.
 * 2.1.a) Dryad generates error message and terminates use case.
 * 2.2 TreeBASE reports not having a record with that ID.
 * 2.2.a) Dryad instructs the user to verify ID and returns to step 1 of the main success scenario.
 * 3.1 User indicates the ID entered is incorrect.
 * 3.1.a) Return to step 1 of the main success scenario.
 * 3.2 User indicates the retrieved record does not match the record for the ID entered.
 * 3.2.a) Dryad generates an error message and terminates use case.
 * 4.1 Dryad encounters an error updating the repository.
 * 4.1.a) Dryad generates an error message and terminates use case.