Difference between revisions of "HUB Use Cases"

From Metadata-Registry
Jump to: navigation, search
Line 12: Line 12:
 
*'''HUB Manager'''
 
*'''HUB Manager'''
 
**One or more persons responsible for the administrative tasks involved in the management of a HUB instance
 
**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]
+
**Authorizations:  
**Only role authorized to Delete Services, Users, and Collections
+
***Service Administrator for all registered Service Providers
 +
**Only role authorized to Delete Service Providers, Services, and Users
  
*'''Service Administrator'''
+
*'''Service Provider 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
+
**One or more persons authorized to maintain Service Provider records. The user who registers a Service Provider becomes the Service Administrator for that Service Provider
 
**Authorizations:  
 
**Authorizations:  
***Service Administrator for all Services owned by that Agent
+
***Service Manager for all Services owned by that Service Provider
 +
***Edit Service Provider Record
 
***Edit/Delete Service Records  
 
***Edit/Delete Service Records  
***Designate other Registered Users as Service Contacts
+
***Register Users and designate Users as Service Contacts, Service Managers, or Service Administrators
***Register Contacts and designate them as: Service Administrators for that Agent or Technical Contacts for that Agent
+
  
*'''Service Primary Contact'''
+
*'''Service Manager'''
**One or more persons acting on behalf of a Service, to whom notifications to the Service may be sent.
+
**One or more persons authorized to maintain one or more Service records. A Service Manager must be authorized by the Service Administrator of the Service provider for that Service
 +
**Authorizations:
 +
***Edit Service Records
 +
***Register Users and designate Users as Service Contacts
 +
 
 +
*'''Service Contact'''
 +
**Person, other than the Service Manager, acting on behalf of a Service, to whom service-related notifications may be sent.
 
**Domain of email address must match the domain registered to that Service
 
**Domain of email address must match the domain registered to that Service
 
+
**May have more specific roles with the same authorizations but different default notifications:
*'''Service Technical Contact'''
+
***Primary Contact
**One or more persons acting on behalf of a service, to whom technical notifications to the Service may be sent.
+
***Technical Contact
 +
***(Others as needed)
  
 
*'''User'''  
 
*'''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.  
+
**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====
 
====Non-Human Actors====
Line 37: Line 45:
 
*'''OAI Harvester'''
 
*'''OAI Harvester'''
 
*'''OAI Server'''
 
*'''OAI Server'''
*'''HUB Database'''
+
*'''Registry'''
*'''Scheduler (Lenny)'''
+
*'''Service'''
 +
*'''Service Provider'''
 +
 
 +
[Jon Note: We should probably try to be somewhat specific about the metadata being registered for each thing: users (at each level), services, service providers.]
 +
 
 
----
 
----
  
Line 48: Line 60:
 
;Prerequisites:Service must be registered  
 
;Prerequisites:Service must be registered  
 
<b>Sequence</b>
 
<b>Sequence</b>
#An Validation is initiated by human or automated process
+
#A Validation is initiated by human or automated process
 
#The validation proceeds and finds no errors  
 
#The validation proceeds and finds no errors  
 
#Notification of successful validation is posted to the administrative interface.  
 
#Notification of successful validation is posted to the administrative interface.  
Line 231: Line 243:
 
;Prerequisites:User must be associated with the organization providing the service
 
;Prerequisites:User must be associated with the organization providing the service
 
<b>Sequence</b>
 
<b>Sequence</b>
#User accesses the Service Registry and initiates Registration in one of two ways:  
+
#User accesses the Service Registry and initiates Registration:  
#* by entering the URI of the OAI server for the service
+
#* User provides 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.
+
#* OAI Harvester sends 'identify' request to OAI Server
 +
#* If request IS NOT successful then:
 +
#** User is immediately notified and may re-enter URL or abort registration
 +
#* If request IS successful then:
 +
#** The OAI identify data provides basic information about the Service Provider -- Name, address, phone, domain (if available), URL, description -- and additional data describing the Service. This data becomes the initial data in the registration forms.
 +
#** If the Service Provider URL and domain is new to the Registry:
 +
#*** User is notified immediately and is presented with the Service Provider registration form
 +
#*** User becomes the Administrator for that Service Provider
 +
#*** User submits Service provider registration form
 +
#** User is presented with Service Registry form
 +
#** User completes the Service registry form
 +
#** User may enter self (and may register other Users) as Primary Contact or Technical Contact by including name and email. If User is neither Primary nor Technical Contact, another role may be entered.
 
#User submits form and Registry sends confirmation email to all contact(s) as well as the Hub Manager.
 
#User submits form and Registry sends confirmation email to all contact(s) as well as the Hub Manager.
 
#User and contact(s) respond to confirmation email, verifying email address(es)
 
#User and contact(s) respond to confirmation email, verifying email address(es)
 
#Registry notifies HUB Manager(s) that Service has been added
 
#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.
 
;Result: Service is registered. User is now a Registered User and an organization contact associated with the registered service.
 +
 +
[Jon Note: probably should have a separate Service Provider registration use case.]
  
 
====Use Case 2/SR: A Contact wishes to modify a Service registration====
 
====Use Case 2/SR: A Contact wishes to modify a Service registration====
Line 253: Line 278:
 
#Registry notifies HUB Manager(s) that Service registration has changed
 
#Registry notifies HUB Manager(s) that Service registration has changed
 
;Result: Service registration is updated.
 
;Result: Service registration is updated.
 +
 +
[Jon Note: I think the actor here needs to be an admin or manager. Contacts can't edit service records]
  
 
====Use Case 3/SR: A HUB Manager wishes to modify a Service registration====
 
====Use Case 3/SR: A HUB Manager wishes to modify a Service registration====
Line 268: Line 295:
 
#Registry notifies HUB Manager(s) that Service registration has changed  
 
#Registry notifies HUB Manager(s) that Service registration has changed  
 
;Result: Service registration is updated.
 
;Result: Service registration is updated.
 +
 +
[Jon Note: I think the prerequisites are wrong here.]

Revision as of 16:17, 17 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 Service Providers
    • Only role authorized to Delete Service Providers, Services, and Users
  • Service Provider Administrator
    • One or more persons authorized to maintain Service Provider records. The user who registers a Service Provider becomes the Service Administrator for that Service Provider
    • Authorizations:
      • Service Manager for all Services owned by that Service Provider
      • Edit Service Provider Record
      • Edit/Delete Service Records
      • Register Users and designate Users as Service Contacts, Service Managers, or Service Administrators
  • Service Manager
    • One or more persons authorized to maintain one or more Service records. A Service Manager must be authorized by the Service Administrator of the Service provider for that Service
    • Authorizations:
      • Edit Service Records
      • Register Users and designate Users as Service Contacts
  • Service Contact
    • Person, other than the Service Manager, acting on behalf of a Service, to whom service-related notifications may be sent.
    • Domain of email address must match the domain registered to that Service
    • May have more specific roles with the same authorizations but different default notifications:
      • Primary Contact
      • Technical Contact
      • (Others as needed)
  • 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
  • Registry
  • Service
  • Service Provider

[Jon Note: We should probably try to be somewhat specific about the metadata being registered for each thing: users (at each level), services, service providers.]


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. A 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:
    • User provides the URI of the OAI Server for the service
    • OAI Harvester sends 'identify' request to OAI Server
    • If request IS NOT successful then:
      • User is immediately notified and may re-enter URL or abort registration
    • If request IS successful then:
      • The OAI identify data provides basic information about the Service Provider -- Name, address, phone, domain (if available), URL, description -- and additional data describing the Service. This data becomes the initial data in the registration forms.
      • If the Service Provider URL and domain is new to the Registry:
        • User is notified immediately and is presented with the Service Provider registration form
        • User becomes the Administrator for that Service Provider
        • User submits Service provider registration form
      • User is presented with Service Registry form
      • User completes the Service registry form
      • User may enter self (and may register other Users) 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.

[Jon Note: probably should have a separate Service Provider registration use case.]

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.

[Jon Note: I think the actor here needs to be an admin or manager. Contacts can't edit service records]

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.

[Jon Note: I think the prerequisites are wrong here.]