Difference between revisions of "NSDL Registry Use Case Documentation (Vocabularies)"

From Metadata-Registry
Jump to: navigation, search
(Use Case 2a: Maintainer Registers a Description of a Top-Level Vocabulary Only)
(Use Case 7: Maintainer Changes Status of Term)
Line 172: Line 172:
  
 
==Use Case 7: Maintainer Changes Status of Term==
 
==Use Case 7: Maintainer Changes Status of Term==
 +
;Purpose:A Maintainer wishes to change the status of an existing registered term
 +
;Primary Actor:Maintainer
 +
;Prerequisites:Must be registered as a Maintainer for the relevant vocabulary and logged in
 +
<b>Sequence</b>
 +
#User searches for the term he/she wishes to update
 +
#The Registry associates the user with the Vocabulary, and presents a menu of choices for updating
 +
#The user chooses the appropriate task ('Change status'), and is presented with a form with a pull-down list with available statuses
 +
#The user chooses a new status and submits the form, sending the update through validation and reporting back to the user
 +
#The user okays the transaction, and it goes to the queue of the Registry Manager or the Editor/Reviewer
 +
#Registry Manager or Editor/Reviewer approves the transaction
 +
;Result:Term appears in the Registry with a different term status
  
 
==Use Case 8: Registry Software Validates Inputs and Uploads==
 
==Use Case 8: Registry Software Validates Inputs and Uploads==

Revision as of 10:48, 6 October 2005

Actors

Human Actors

System Administrator
Overall system administrator. Responsible for system-level software and hardware maintenance
Registry Manager
Person (or persons) responsible for the administrative tasks involved in the management of a registry
Vocabulary Editor/Reviewer
Person (or persons) responsible for editorial functions related to submitted vocabularies
Visitor
Anyone viewing or browsing the site who is not logged in, including registered Maintainers who have not yet logged in.
Registered User
A Vistor who has registered himself/herself for the purpose of registering an organization or vocabulary. A Registered User may assume an additional role (Maintainer, Organization Contact) while registering an organization or vocabulary.
Organization Contact
Person acting on behalf of an organization, to whom notifications to the Organization may be sent.
Maintainer
Person responsible for maintaining a vocabulary

Non-human Actors

Registry
The registry software, including user interfaces, processing systems, and services
Service
An interface intended to be used by machines that provides data in response to a request
Service Consumer
Machine requesting data from a service
Organization
Basically a term for for group of persons or an educational or business unit rather than an individual. For instance, an NSDL Project is an organization. In the current context the organization is also the entity responsible for the vocabulary. Vocabularies are associated with an Organization and maintained by a Maintainer who is authorized by the Organization. (Policy question?)

Terms

Vocabulary
[Merriam-Webster] "a list or collection of words or of words and phrases usually alphabetically arranged and explained or defined" ; [In the context of this project] "A set of concepts, represented by words and word relationships, presented in a structured manner." [NOTE: the DC Abstract Model uses the term Vocabulary Encoding Scheme, defined as "A vocabulary encoding scheme is a class that indicates that the value of a property is taken from a controlled vocabulary (or concept-space), such as the Library of Congress Subject Headings"]
Hosted Vocabulary
A vocabulary whose canonical (official) version resides, or is "hosted" in the Registry.
Non-hosted Vocabulary
A vocabulary that is published (exposed) through the Registry but that is created and maintained by its promulgating agency in a separate registry or as a Web-addressable file in its own namespace.
Terms
DC Abstract Model "The generic name for a property (i.e. element or element refinement), vocabulary encoding scheme, syntax encoding scheme or concept taken from a controlled vocabulary (concept space)"
Tokens
[from Wikipedia] "In computer science, specifically lexical analysis, a token is usually a word or an atomic element within a string. Tokenizing is systematically replacing portions of a string by such corresponding token"
Simple Knowledge Organization System (SKOS)
[from SKOS Home Page] "SKOS is an area of work developing specifications and standards to support the use of knowledge organization systems (KOS) such as thesauri, classification schemes, subject heading lists, taxonomies, terminologies, glossaries and other types of controlled vocabulary within the framework of the semantic web"
PURLs
[from the OCLC PURL Home page] "A PURL is a Persistent Uniform Resource Locator. Functionally, a PURL is a URL. However, instead of pointing directly to the location of an Internet resource, a PURL points to an intermediate resolution service. The PURL resolution service associates the PURL with the actual URL and returns that URL to the client. The client can then complete the URL transaction in the normal fashion. In Web parlance, this is a standard HTTP redirect"

Vocabulary and Member Term States

  • Private The state of a vocabulary or a vocabulary term that has been created in the registry by a Maintainer but that has not been submitted to the Registry Manager (or delegate)
  • Submitted The state of a vocabulary or a vocabulary term that has been submitted by a Maintainer and is under review by the Regestry Manager (or delegate)
  • Published The state of a vocabulary or a vocabulary term that has been exposed to external human and machine agents through the registry
  • Deprecated The state of a vocabulary or vocabulary terms the use of which is no longer advised

Policies

WARNING - assumption alert!! Many of the use cases below make assumptions about yet-to-be-decided policies (as of 9/2005)

  • Vocabularies must be associated with an Organization that acts as the Entity responsible for the Vocabulary
  • Vocabulary Maintainers are individuals and they must be associated with an Organization in order to maintain an Organization's Vocabularies
  • A Maintainer may be associated with more than one Organization and more than one Vocabulary
  • Maintainers assertion of association with an Organization will be assumed to be valid unless the organization, after notification of a vocabulary registration, questions the association. In other words, Organizations don't need to specifically authorize individual Maintainers to maintain a specific Vocabulary, but reasonable measures will be taken to assure the Registry against fraud and error.
  • Organizations must be able to be associated with an internet domain that will form the root of individual Vocabulary namespaces, or agree to allow the registry domain to substitute.

Registry Use Cases (Vocabularies)

Use Case 1: A Visitor wishes to register an Organization

Purpose
An NSDL project has a small subject vocabulary that they wish to register and needs to register their organization and at least one Maintainer
Primary Actor
Visitor
Prerequisites
None

Sequence

  1. Visitor accesses the Registry and initiates Organization Registration
  2. Visitor enters basic information about the organization -- Name, address, phone, domain (if available), URL, description, organization contact information including name and email
  3. Visitor submits form and Registry sends confirmation email to organizational contact.
  4. Registry asks if Visitor wishes to register as a Maintainer for that organization
  5. If yes, see Use Case 12
  6. Organization responds to confirmation email
  7. Registry assigns PURL to organization and stores organization info in database
  8. Registry notifies Registry Manager(s) that Organization has been added
Result
Organization is registered. Visitor is now a Maintainer associated with the registered organization.

Use Case 2: Maintainer Registers a Description of a Vocabulary

Purpose
A Maintainer associated with an Organization wishes to register the description of a Vocabulary with the Registry. This step is necessary before entering specific terms or uploading terms from an extant vocabulary. It is important to note that this use case describes the registration of a description of a vocabulary and not the vocabulary itself.
Primary Actor
Maintainer
Prerequisites
Organization must be registered. Maintainer must be associated with that Organization and logged in

Sequence

  1. Maintainer accesses the Vocabulary Maintenance page and selects 'Add new Vocabulary'
  2. Registry displays the 'Add Vocabulary' form, containing a list of Organizations with which Maintainer is associated
  3. Maintainer selects Organization, adds a description of the vocabulary, organization-defined URI for the vocabulary (if exists), and rights information (see note 1)
  4. Maintainer submits form
  5. Registry assigns PURL to vocabulary description, stores vocabulary info in database and sends confirmation email (no response required)
  6. Registry notifies Registry Manager(s) that Vocabulary description has been added
  7. Registry displays a list of other Maintainers associated with this Organization and asks if Maintainer wishes to add them to this Vocabulary and also offers Maintainer the opportunity to Register other Maintainers or add existing Maintainers to this Organization
  8. Maintainer selects from list and/or adds Maintainer registration information for other Maintainers
  9. Registry sends other Maintainers a confirmation email indicating that they have been added to this Vocabulary
  10. Registry offers Maintainer the opportunity to:
    1. Add terms to the new Vocabulary (If yes, see Use Case 3-3a); or
    2. Upload an existing vocabulary encoded in an acceptable syntax (If yes, see Use Case 4-4a); or
    3. Add no vocabulary terms
Result
Vocabulary description is registered.

Notes

  1. It might be useful to allow insertion of a full rights text block, a URL of a rights document, or a link to the Creative Commons Rights selection wizard that the MediaWiki setup uses: http://creativecommons.org/technology/web-integration Question (Diane): Does this imply that the rights statement would be attached to terms as well, if/when terms are added?

Use Case 2a: Maintainer Registers a Description of a Top-Level Vocabulary Only

Purpose
A Maintainer associated with an Organization wishes to register the description of a Vocabulary with the Registry. In this case the Vocabulary has terms available in some form locally but is not yet ready (or may never be ready) to expose their terms to the registry. It is important to note that this use case describes the registration of a description of a vocabulary and not the vocabulary itself.
Primary Actor
Maintainer
Prerequisites
Organization must be registered. Maintainer must be associated with that Organization and logged in

Sequence

  1. Maintainer accesses the Vocabulary Maintenance page and selects 'Add new Vocabulary'
  2. Registry displays the 'Add Vocabulary' form, containing a list of Organizations with which Maintainer is associated
  3. Maintainer selects Organization, adds a description of the vocabulary, organization-defined URI for the vocabulary (if exists), and rights information (see note 1 above)
  4. Maintainer submits form
  5. Registry assigns PURL to vocabulary description, stores vocabulary info in database and sends confirmation email (no response required)
  6. Registry notifies Registry Manager(s) that Vocabulary description has been added
  7. Registry displays a list of other Maintainers associated with this Organization and asks if Maintainer wishes to add them to this Vocabulary and also offers Maintainer the opportunity to Register other Maintainers or add existing Maintainers to this Organization
  8. Maintainer selects from list and/or adds Maintainer registration information for other Maintainers
  9. Registry sends other Maintainers a confirmation email indicating that they have been added to this Vocabulary
  10. When queried by Registry to offer Maintainer the opportunity to add terms, Maintainer opts to add no terms.
Result
Vocabulary description is registered.

Use Case 3: Maintainer Registers Terms with a Vocabulary

Purpose
The Maintainer of a Vocabulary wishes to add specific terms to a Vocabulary hosted in the registry. In this case the vocabulary terms are also hosted in the registry.
Primary Actor
Maintainer
Prerequisites
Vocabulary description must be registered. Maintainer must be associated with that Vocabulary and logged in

Sequence

  1. Maintainer accesses "Vocabulary Maintenance' page and selects 'Maintain Vocabulary'
  2. Maintainer selects Vocabulary from a list of vocabulary descriptions with which they are associated
  3. Maintainer adds the required data and some optional data for each term [what data yet to be determined]
  4. Maintainer adds term declaration
  5. Maintainer optionally adds relationships between new term and other existing terms
  6. Registry assigns a permanent term URI (PURL) to each term using the base URI established when the top level vocabulary was registered
  7. Maintainer submits terms
  8. Registry validates terms and when the terms pass validation routines, the terms are stored in the Registry
  9. Registry notifies Registry Manager(s) that terms have been added to a Vocabulary
Result
Hosted terms added to Vocabulary

Use Case 4: Maintainer Uploads Vocabulary Terms to the Registry

Purpose
In this case a Maintainer who has already registered the vocabulary as a whole may contribute individual terms via an upload process, subject to validation of the file. In this case, the intent is that the Registry will be hosting the terms, not reflecting terms hosted elsewhere. Maintenance of terms uploaded in this manner may be via service interaction with the vocabulary owner or manually within the registry.
Primary Actor
Maintainer
Prerequisites
Vocabulary must be registered. Maintainer must be associated with that Vocabulary and logged in

Sequence

  1. Maintainer accesses 'Vocabulary Maintenance' page and selects 'Maintain Vocabulary'
  2. Maintainer selects Vocabulary from a list of Vocabularies with which they are associated
  3. Maintainer chooses the 'upload file' option
  4. Maintainer chooses the file to upload from his/her browser window, and submits the file
  5. If the organizaion has already assigned URIs for the terms, and included these term URIs in the uploaded file, there URIs will be maintained as is in the Registry
  6. If there are not supplied term URIs in the uploaded file, the Registry will generate term URIs based on the URI generated or supplied when the top level vocabulary was registered
  7. The Maintainer (and the Organization Contact for the Organization) receive a validation report from the registry, confirming that required elements are present, and, if no URIs were supplied, that the Registry has generated valid URIs for the terms. The notification includes the caveat that the file must be reviewed by the Registry Manager before being inserted into the registry.
  8. If the file does not validate, the notification includes error messages associated with the process, a link to a FAQ detailing the error messages and possible next steps, and the email of the Registry Manager and/or Vocabulary Editor/Reviewer
  9. The Registry queues the file for the Registry Manager and/or Vocabulary Editor/Reviewer
  10. The Registry Manager submits the final file to the Registry. Notification of this event is sent to the Maintainer and the Organization Contact
Result
The Vocabulary terms are registered. Updates to the Vocabulary terms can be made individually or by uploaded file.


Use Case 4: Maintainer Uploads non-Hosted Vocabulary Terms to the Registry

Purpose
In this case a Maintainer who has already registered the vocabulary as a whole may contribute individual terms via an upload process, subject to validation of the file. In this case, the terms are hosted and maintained elsewhere, and may only be updated via service interaction with the maintaining organization or manual uploading of replacement files.
Primary Actor
Maintainer
Prerequisites
Vocabulary must be registered. Maintainer must be associated with that Vocabulary and logged in

Sequence

  1. Maintainer accesses 'Vocabulary Maintenance' page and selects 'Maintain Vocabulary'
  2. Maintainer selects Vocabulary from a list of Vocabularies with which they are associated
  3. Maintainer chooses the 'upload file' option
  4. Maintainer chooses the file to upload from his/her browser window, and submits the file
  5. If the organizaion has already assigned URIs for the terms, and included these term URIs in the uploaded file, there URIs will be maintained as is in the Registry
  6. If there are not supplied term URIs in the uploaded file, the Registry will generate term URIs based on the URI generated or supplied when the top level vocabulary was registered
  7. The Maintainer (and the Organization Contact for the Organization) receive a validation report from the registry, confirming that required elements are present and, if no URIs were supplied, that the Registry has generated valid URIs for the terms. The notification includes the caveat that the file must be reviewed by the Registry Manager before being inserted into the registry.
  8. If the file does not validate, the notification includes error messages associated with the process, a link to a FAQ detailing the error messages and possible next steps, and the email of the Registry Manager and/or Vocabulary Editor/Reviewer
  9. The Registry queues the file for the Registry Manager and/or Vocabulary Editor/Reviewer
  10. The Registry Manager submits the final file to the Registry. Notification of this event is sent to the Maintainer and the Organization Contact
Result
The Vocabulary terms are registered. Updates to the Vocabulary terms can be made only via service interaction or manually by uploaded file.

Use Case 5: Maintainer Adds Information to Registered Term

Purpose
A Maintainer who already has vocabulary terms registered comes back to the registry to update the terms.
Primary Actor
Maintainer, Registry Manager
Prerequisites
Must be registered as a Maintainer with the relevant Vocabulary and logged in

Sequence

  1. User searches for the term he/she wishes to update
  2. The Registry associates the user with the Vocabulary, and presents a menu of choices for updating
  3. The user chooses the appropriate task, and is presented with a form
  4. The user completes the form, which sends the update through validation and reports back to the user
  5. The user okays the transaction, and it goes to the queue of the Registry Manager or the Editor/Reviewer
  6. Registry Manager or Editor/Reviewer approves the transaction
Result
Updated term appears in the Registry

Use Case 6: Maintainer Changes Semantics of Term

Purpose
A Maintainer wishes to change the semantics of an existing registered term
Primary Actor
Maintainer
Prerequisites
Must be registered as a Maintainer for the relevant vocabulary and logged in

Sequence

  1. User searches for the term he/she wishes to update
  2. The Registry associates the user with the Vocabulary, and presents a menu of choices for updating
  3. The user chooses the appropriate task, and is presented with a form; the form includes a check box indicating that the term semantics will change with the current transaction
  4. The user supplies a new term name, and new URI
  5. The user completes the form, which sends the update through validation and reports back to the user
  6. The user okays the transaction, and it goes to the queue of the Registry Manager or the Editor/Reviewer
  7. Registry Manager or Editor/Reviewer approves the transaction
Result
'New' term appears in the Registry with a new URI; the old term status changes to 'deprecated'

Use Case 7: Maintainer Changes Status of Term

Purpose
A Maintainer wishes to change the status of an existing registered term
Primary Actor
Maintainer
Prerequisites
Must be registered as a Maintainer for the relevant vocabulary and logged in

Sequence

  1. User searches for the term he/she wishes to update
  2. The Registry associates the user with the Vocabulary, and presents a menu of choices for updating
  3. The user chooses the appropriate task ('Change status'), and is presented with a form with a pull-down list with available statuses
  4. The user chooses a new status and submits the form, sending the update through validation and reporting back to the user
  5. The user okays the transaction, and it goes to the queue of the Registry Manager or the Editor/Reviewer
  6. Registry Manager or Editor/Reviewer approves the transaction
Result
Term appears in the Registry with a different term status

Use Case 8: Registry Software Validates Inputs and Uploads

Use Case 9: Registry Manager Interacts with User and User Input

Use Case 10: External Service Interactions

Use Case 11: External User Interactions

Use Case 12: User registers as a Maintainer associated with a Vocabulary

Purpose
A Registered User wishes to be registered as a Maintainer for an existing Vocabulary
Primary Actor
Registered User
Prerequisites
Must be registered as a user and logged in

Sequence

  1. Registered User initiates Maintainer Registration
  2. Visitor selects Vocabulary from list and submits form.
  3. Registry sends confirmation email to Registered User and notification email to Organization Contact (notification will include information on how to contact the Registry if the Maintainer does not have authorization to assume that role).
  4. Registered User replies to confirmation email and user relationship to vocabulary info is stored in database as confirmed.
Result
Registered User is now a Maintainer associated with a registered Vocabulary.

Example Registries