wiki:use-cases/AnnotateCIMRecord

Use-Case: Annotate a CIM Record


Author: Phil Bentley
Version: 0.2
Date: 28 April 2008, 27 July 2010
Associated Work Packages: WP4, WP5, WP6

Purpose: Describes the scenario whereby an end-user wishes to annotate the currently selected CIM record with a comment of some sort. An obvious possibility is to describe something about the quality of the data or metadata.

Actors: RegisteredUser, MetadataManager, DataManager

Related Use-Cases:

Summary:

This use-case describes the scenario whereby a registered end-user wishes to annotate a particular CIM record with a comment of some kind. It may be desirable, for instance, to insert a reference to an end-user's own dataset which may be similar to, or even based upon, the dataset described by a CIM record. Or the end-user may wish to highlight an error in the dataset, or record how the dataset is being used in their own domain. This use-case is similar to the way in which readers of a PDF document may add comments to the document without actually modifying the original content.

The important distinction is made here between annotating a CIM record (as described here), and updating the actual content of the CIM record. The former process can be considered as attaching, or associating, supplementary information to the CIM record. The latter can be considered as the normal process whereby the CIM record itself is modified by a responsible data manager or metadata maintainer. This latter process is not considered to fall within the scope of the WP5 CIM Query Toolkit.

Typical Course of Events

  1. The end-user clicks on an 'Add Annotation' control, or somesuch, in the web application interface.
  2. The web applications displays a web form in which the end-user can enter the text of the description in free format. This text entry field or control should also allow the user to include hyperlinks to other internet resources.
  3. The end-user can optionally choose to preview the new annotation item.
  4. If the annotation is as intended, the end-user submits the web form.
  5. The web application confirms that the annotation item has been attached to the current CIM record.

Alternative Course of Events

  1. If the annotation item could not be saved with the CIM record a suitable error message is displayed and the end-user is given the chance to edit and resubmit the web form.

Pre-Conditions

In order to identify annotation authors, only registered users of a CIM repository are permitted to add annotation items to a CIM record.

The desired CIM record to annotate will have been previously selected or identified using, for example, one of the CIM repository query use-cases.

Post-Conditions

  1. The new annotation item is made visible to other end-users who subsequently select the affected CIM record.
  2. The custodian/owner of the CIM record is sent a notification that a new annotation has been attached to the record.

Miscellaneous Notes:

The mechanism by which the new annotation item is attached to, or otherwise associated with, the chosen CIM record is not defined here. It is suggested, however, that the CIM record itself is not modified since that typically is the responsibility of a small number of recognised roles (e.g. a data manager or metadata custodian). One solution, therefore, might be to maintain annotation items as separate artefacts in the CIM repository or else as artefacts in a separate repository. The annotations and CIM records could then be linked together using URIs.

Use-Case Diagram: