Difference between revisions of "HUB Use Cases"

From Metadata-Registry
Jump to: navigation, search
(OAI Harvester Use Cases)
Line 147: Line 147:
 
===OAI Server Use Cases===
 
===OAI Server Use Cases===
  
 +
OAI Server
 +
 +
 +
*1 Built-in testing dataset
 +
** 1.1 Fixed number of records
 +
** 1.2 should contain at least one complete record for each supported metadata format
 +
*** 1.2.1 should contain one of all possible elements
 +
*** 1.2.2 should contain at least 2 of all repeatable elements
 +
*** 1.2.3 should contain one of each term in allowed VES
 +
** 1.3 Number of records should exceed 2 resumption tokens
 +
** 1.4 Number of sets should exceed 2 resumption tokens
 +
** 1.5 set resumption token chunk size at 5 records
 +
* 2 ListSets should support resumption tokens
 +
* 3 resumption tokens should include optional attributes
 +
** 3.1 cursor
 +
** 3.2 expirationDate
 +
** 3.3 completeListSize
 +
* 4 Support for all specified OAI error messages
 +
** 4.1 more informative error messages for server debugging
 +
** 4.2 Use http status codes whenever appropriate<br>(rarely need to use anything other than 200 or 503)
 +
* 5 Should be easy to set server-wide parameters
 +
** 5.1 contents of identify response
 +
** 5.2 chunk size
 +
*** 5.2.1 number of records per chunk
 +
*** 5.2.2 maximum chunk in bytes
 +
**** 5.2.2.1 stop sending after record that exceeds chunk size
 +
**** 5.2.2.2 generate warning if chunk is less than n records
 +
** 5.3 maximum simultaneous requests
 +
*** 5.3.1 generate a 503 response header
 +
** 5.4 expirationDate (time-to-live) of harvest requests
 +
* 6 configurable admin notifications
 +
** 6.1 notification type
 +
** 6.1.1 failure
 +
** 6.1.2 data error
 +
** 6.1.3 bad request
 +
** 6.1.4 warning
 +
** 6.2 notification method
 +
*** 6.2.1 email
 +
*** 6.2.2 rss
 +
*** 6.2.3 local log
 +
*** 6.2.4 apache log
 +
* 7 support for response compression
 +
** 7.1 requires header negotiation
 +
** 7.2 gzip
 +
** 7.3 compress
 +
* 8 all data provided by plugin data connectors
 +
** 8.1 common data request interface
 +
** 8.2 plugin translates request into query appropriate to data source
 +
** 8.3 provide several connectors
 +
*** 8.3.1 MySQL
 +
*** 8.3.2 XML files
 +
*** 8.4 Cache responses requiring resumption tokens
 +
*** 8.4.1 build a list of identifiers first
 +
**** 8.4.1.1 id
 +
**** 8.4.1.2 date
 +
**** 8.4.1.3 deleted flag
 +
**** 8.4.1.4 datasource
 +
*** 8.4.2 retrieve records as needed
 +
*** 8.4.3 problems
 +
**** 8.4.3.1 records in set may change
 +
**** 8.4.3.2 records in set may be deleted
 +
**** 8.4.3.3 assume dataset too large to buffer completely
 +
** 8.5 should return data properly formatted for server response:<br>Server should only have to compress and/or send
 +
* 9 suppot for http digest authentication to restrict access to protected resources
 +
* 10 Request handling
 +
** 10.1 Support both GET and POST
 +
** 10.2 Requests should not be case-sensitive
 +
** 10.3 an open ended date range in a request should default to now()
 +
* 11 Identifiers
 +
** 11.1 OAI Identifiers should be simple and must be unique
 +
** 11.2 Every record should include the URI of the resource the metadata is about
 +
** 11.3 records that are 'about' another metadata record should also include the identifier of that record
 +
* 12 Must support persistent deletions
  
  

Revision as of 16:34, 14 December 2007

XC HUB Use Cases

User Roles

[

Human Actors

  • System Administrator
    • Overall system administrator. Responsible for system-level software and hardware maintenance
  • HUB Manager
    • One or more persons responsible for the administrative tasks involved in the management of a HUB instance
    • Authorizations: Service Administrator for all registered Services Editor for all Collections and Metadata [not sure about this one]
    • Only role authorized to Delete Services, Users, and Collections
  • Service Administrator
    • One or more persons authorized to maintain one or more Service records. The user who registers a Service becomes the Service Administrator for that Service
    • Authorizations:
      • Service Administrator for all Services owned by that Agent
      • Edit/Delete Service Records
      • Designate other Registered Users as Service Contacts
      • Register Contacts and designate them as: Service Administrators for that Agent or Technical Contacts for that Agent
  • Service Primary Contact
    • One or more persons acting on behalf of a Service, to whom notifications to the Service may be sent.
    • Domain of email address must match the domain registered to that Service
  • Service Technical Contact
    • One or more persons acting on behalf of a service, to whom technical notifications to the Service may be sent.
  • User
    • A User is a visitor who has an intent to register a service. A User may assume an additional role while registering a service.

Non-Human Actors

  • OAI Harvester
  • OAI Server
  • HUB Database
  • Scheduler (Lenny)

OAI Harvester Use Cases

Use Case 1/OH: OAI Validation succeeds

Purpose
An XC project attempts to validate a new service
Primary Actor
OAI Harvester
Prerequisites
Service must be registered

Sequence

  1. An Validation is initiated by human or automated process
  2. The validation proceeds and finds no errors
  3. Notification of successful validation is posted to the administrative interface.
  4. Notification of successful validation is posted in an email message to the Primary contact for the service.
Result
The service is ready to be harvested.

Use Case 2/OH: OAI Validation fails

Purpose
An XC project attempts to validate a new service
Primary Actor
OAI Harvester
Prerequisites
Service must be registered

Sequence

  1. An Validation is initiated by human or automated process
  2. The validation proceeds and finds errors
  3. Notification of failed validation is posted to the administrative interface.
  4. Notification of failed validation is posted in an email message to the HUB Manager and the Primary contact for the service. Notification includes link to validation log and helpdesk.
Result
The service cannot be harvested until the errors are corrected.

Use Case 3/OH: Data Validation succeeds

Purpose
An XC project attempts to validate a new data set
Primary Actor
OAI Harvester
Prerequisites
Service must be registered and have passed service validation

Sequence

  1. A test harvest is initiated by human or automated process
  2. The test harvest proceeds and finds no errors
  3. Notification of successful data validation is posted to the administrative interface.
  4. Notification of successful data validation is posted in an email message to the Primary contact for the service.
Result
The service is ready to be harvested.

Use Case 4/OH: Data Validation fails

Purpose
An XC project attempts to validate a new data set
Primary Actor
OAI Harvester
Prerequisites
Service must be registered and have passed service validation

Sequence

  1. A test harvest is initiated by human or automated process
  2. The test harvest proceeds and finds errors
  3. Notification of failed data validation is posted to the administrative interface with a link to the log.
  4. Notification of failed data validation is posted in an email message to the HUB Manager and the Primary contact for the service. Notifications include links to the log and to the helpdesk with embedded errors sufficient to create a ticket.
Result
The service is ready to be harvested except for the records with data errors.

Use Case 5/OH: A Harvest succeeds

Purpose
An XC project harvests a new record set successfully.
Primary Actor
OAI Harvester
Prerequisites
Service must be registered and have passed a test validation

Sequence

  1. An OAI Harvest is initiated by human or automated process
  2. The harvest proceeds and finds no data errors
  3. Notification of successful harvest is posted to the administrative interface. Notifications include:
    • record counts
    • link to harvest log
    • link to csv file of harvested records
  4. Notification of successful harvest is posted in an email message to the HUB Manager and the Primary contact for the service. Notifications include:
    • record counts
    • link to harvest log
    • link to csv file of harvested records
    • link to helpdesk with embedded harvest information
Result
HUB is updated successfully with new data.

Use Case 6/OH: A Harvest fails for system reasons

Purpose
An XC project attempts to harvest a new record set but is unsuccessful.
Primary Actor
OAI Harvester
Prerequisites
Service must be registered and have passed a test validation

Sequence

  1. An OAI Harvest is initiated by human or automated process
  2. The harvest fails for reasons having to do with the data provider:
    • the server is down temporarily
    • the server address has changed and no notice was given to the HUB service registrar
    • the server software has changed and no longer complies with the OAI protocol. In this case the Harvester will initiate a test procedure (see Use Cases on server validation)
  3. Notification of an unsuccessful harvest is posted to the administrative interface. Notifications include:
    • indication of whether the server was available
    • indication of whether a validation test was initiated
    • results of the validation test
  4. Notification of successful harvest is posted in an email message to the HUB Manager and the Primary contact for the service. Notifications include:
    • indication of whether the server was available
    • indication of whether a validation test was initiated
    • results of the validation test
    • link to helpdesk with embedded harvest information sufficient to create a ticket
Result
HUB is not updated with new data.

Use Case /OH: A Harvest fails (or fails partially) for data reasons

Purpose
An XC project attempts to harvest a new record set but is only partially successful.
Primary Actor
OAI Harvester
Prerequisites
OAI Harvester must be registered as a service and passed a test validation at some point

Sequence

  1. An OAI Harvest is initiated by human or automated process
  2. The harvest proceeds and finds data errors
  3. Notification of a partially successful harvest is posted to the administrative interface. Notifications include:
    • record counts (successes and errors)
    • link to harvest log with data errors
    • link to csv file of successfully harvested records
  4. Notification of partially successful harvest is posted in an email message to the HUB Manager and the Primary contact for the service. Notifications include:
    • record counts (successes and errors)
    • link to harvest log with data errors
    • link to csv file of successfully harvested records
    • link to helpdesk with embedded harvest and log information sufficient to create a ticket
Result
HUB is updated successfully with new data; records with data errors not included.

OAI Server Use Cases

OAI Server


  • 1 Built-in testing dataset
    • 1.1 Fixed number of records
    • 1.2 should contain at least one complete record for each supported metadata format
      • 1.2.1 should contain one of all possible elements
      • 1.2.2 should contain at least 2 of all repeatable elements
      • 1.2.3 should contain one of each term in allowed VES
    • 1.3 Number of records should exceed 2 resumption tokens
    • 1.4 Number of sets should exceed 2 resumption tokens
    • 1.5 set resumption token chunk size at 5 records
  • 2 ListSets should support resumption tokens
  • 3 resumption tokens should include optional attributes
    • 3.1 cursor
    • 3.2 expirationDate
    • 3.3 completeListSize
  • 4 Support for all specified OAI error messages
    • 4.1 more informative error messages for server debugging
    • 4.2 Use http status codes whenever appropriate
      (rarely need to use anything other than 200 or 503)
  • 5 Should be easy to set server-wide parameters
    • 5.1 contents of identify response
    • 5.2 chunk size
      • 5.2.1 number of records per chunk
      • 5.2.2 maximum chunk in bytes
        • 5.2.2.1 stop sending after record that exceeds chunk size
        • 5.2.2.2 generate warning if chunk is less than n records
    • 5.3 maximum simultaneous requests
      • 5.3.1 generate a 503 response header
    • 5.4 expirationDate (time-to-live) of harvest requests
  • 6 configurable admin notifications
    • 6.1 notification type
    • 6.1.1 failure
    • 6.1.2 data error
    • 6.1.3 bad request
    • 6.1.4 warning
    • 6.2 notification method
      • 6.2.1 email
      • 6.2.2 rss
      • 6.2.3 local log
      • 6.2.4 apache log
  • 7 support for response compression
    • 7.1 requires header negotiation
    • 7.2 gzip
    • 7.3 compress
  • 8 all data provided by plugin data connectors
    • 8.1 common data request interface
    • 8.2 plugin translates request into query appropriate to data source
    • 8.3 provide several connectors
      • 8.3.1 MySQL
      • 8.3.2 XML files
      • 8.4 Cache responses requiring resumption tokens
      • 8.4.1 build a list of identifiers first
        • 8.4.1.1 id
        • 8.4.1.2 date
        • 8.4.1.3 deleted flag
        • 8.4.1.4 datasource
      • 8.4.2 retrieve records as needed
      • 8.4.3 problems
        • 8.4.3.1 records in set may change
        • 8.4.3.2 records in set may be deleted
        • 8.4.3.3 assume dataset too large to buffer completely
    • 8.5 should return data properly formatted for server response:
      Server should only have to compress and/or send
  • 9 suppot for http digest authentication to restrict access to protected resources
  • 10 Request handling
    • 10.1 Support both GET and POST
    • 10.2 Requests should not be case-sensitive
    • 10.3 an open ended date range in a request should default to now()
  • 11 Identifiers
    • 11.1 OAI Identifiers should be simple and must be unique
    • 11.2 Every record should include the URI of the resource the metadata is about
    • 11.3 records that are 'about' another metadata record should also include the identifier of that record
  • 12 Must support persistent deletions



Service Registry Use Cases

Use Case 1/SR: A User wishes to register a Service

Purpose
An XC project has a service that they wish to register.
Primary Actor
User
Prerequisites
User must be associated with the organization providing the service

Sequence

  1. User accesses the Service Registry and initiates Registration in one of two ways:
    • by entering the URI of the OAI server for the service
    • by entering basic information about the organization providing the service -- Name, address, phone, domain (if available), URL, description. User may then enter self (and may designate others in addition) as Primary Contact or Technical Contact by including name and email. If User is neither Primary nor Technical Contact, another role may be entered.
  2. User submits form and Registry sends confirmation email to all contact(s) as well as the Hub Manager.
  3. User and contact(s) respond to confirmation email, verifying email address(es)
  4. Registry notifies HUB Manager(s) that Service has been added
Result
Service is registered. User is now a Registered User and an organization contact associated with the registered service.

Use Case 2/SR: A Contact wishes to modify a Service registration

Purpose
An XC project has service registration that they wish to modify.
Primary Actor
Primary Contact or Technical Contact
Prerequisites
Primary Contact or Technical Contact must be associated with the organization providing the service within the service registration.

Sequence

  1. Contact accesses the Service Registry and chooses to edit the service registration:
    • if the OAI server address has changed, the harvester will initiate a test harvest to:
      • refresh the information provided by the server
      • test the server conformance with OAI (given that more than the server address might have changed behind the scenes)
    • if contact details for registered contacts are changed (or new contacts are designated) the verification of email addresses will be done for any new or changed addresses.
  2. Contact submits form and Registry sends confirmation email to all contact(s) as well as the Hub Manager.
  3. Contact(s) respond to confirmation email, verifying email address(es)
  4. Registry notifies HUB Manager(s) that Service registration has changed
Result
Service registration is updated.

Use Case 3/SR: A HUB Manager wishes to modify a Service registration

Purpose
An HUB Manager wishes to modify a service registration.
Primary Actor
HUB Manager
Prerequisites
In general it is preferable for a Primary Contact or Technical Contact to modify a service registration, but in some cases (when the registered Primary Contact and/or Technical Contact are no longer associated with the service organization, or when those contacts will not make the modifications themselves).

Sequence

  1. HUB Manager accesses the Service Registry and chooses to edit the service registration:
    • if the OAI server address has changed, the harvester will initiate a test harvest to:
      • refresh the information provided by the server
      • test the server conformance with OAI (given that more than the server address might have changed behind the scenes)
    • if contact details for registered contacts are changed (or new contacts are designated) the verification of email addresses will be done for any new or changed addresses.
  2. HUB Manager submits form and Registry sends confirmation email to all contact(s) as well as the Hub Manager.
  3. Contact(s) respond to confirmation email, verifying email address(es)
  4. Registry notifies HUB Manager(s) that Service registration has changed
Result
Service registration is updated.