Skip to end of metadata
Go to start of metadata

Plans

This may begin with prose, and expand into something like a project plan at some point. This need not be a complete schedule, but it will make sense to include the steps and approaches, milestones, etc.

User Stories

1. Create and store ID Patterns

User story:
A system administrator wants to create and store ID patterns

Behavior-oriented user story:

  • As a system administrator
  • I want to be able to create and store patterns corresponding to various IDs used at my museum
  • so that the system can automatically generate and validate IDs matching those patterns.

Service consumer user story:

  • As a service consumer
  • I want to be able to:
    • Create new ID Patterns.
    • Read an existing ID Pattern by its ID.
    • Read all ID Patterns.
    • Update - by renaming only - an existing ID Pattern.
    • Update - by setting to active or inactive only - an existing ID Pattern.

Anticipated tasks:
(This list may be too large for a single user story, so we may need to divide the story and/or task ...)

  • Create a rudimentary object model and identify their initial prototypical methods and data. Initially anticipated - before taking into account support for later tasks, below, such as ID registration and release:
    • ID Generator
    • ID Validator
    • ID Part
    • ID Part Sequence (or Group)
    • ID Pattern
    • ID
  • Build ID generators and associated tests:
    • ID generators which generate "next" IDs, given a supplied starting value. (Consider doing so by extending the 'series' classes within Apache Commons Id.)
    • ID generators which generate "current" values (e.g. "current year").
    • An ID generator which generates static values. (This is already present in Apache Commons Id.)
  • Design and build an ID Part class, and associated tests. This may compose:
    • An ID generator.
    • An ID validator.
    • An initial (base) value, to which the ID Part may be reset.
  • Design and build an ID Pattern class, which aggregates ID Parts, and associated tests.
  • Research mechanisms for giving namespace-unique identifiers for components of the object model, such as ID Parts and ID Patterns, or determine if CSIDs are sufficient.
  • Build ID Service functionality capable of storing and providing access to patterns.
    • Model resources for providing access to patterns.
    • Write representations for those resources, which can used as payload formats.
    • Decide on persistent storage for ID Patterns (probably a Nuxeo document type, using the representation format above).
    • Write REST APIs in JAX-RS based on that resource model.
      • Create new ID Patterns.
      • Read an existing ID Pattern, by supplying an ID Pattern identifier.
      • Read all ID Patterns.
      • Update (rename only?) an existing ID Pattern.
      • Update (set to inactive only?) an existing ID Pattern.
    • Decide and document whether to allow deletion of previously-created ID Patterns, and if so, under what circumstances.
    • Write "out of the box" ID Patterns that follow standards-based recommendations (e.g. SPECTRUM). See {link to appropriate section of ID Service Descriptions and Assumptions page here}.
2. Generate IDs

User story:
A user wants to have a pre-generated ID filled in when they start to create a new record.

Behavior-oriented user story:

  • As a museum staff member or volunteer
  • When I am entering a new record for collection objects, loans, or other entities
  • I want the "next available" ID to be automatically generated and filled in
  • so that I don't have to look it up, or accidentally assign duplicate IDs.

Service consumer user story:

  • As a service consumer
  • I want to be able to:
    • Read a "next ID", by supplying an ID Pattern identifier.

Anticipated tasks:

  • Build ID Service functionality capable of returning a "next" ID:
    • Provide a (probably mock) mechanism for storing a "last used" ID for each ID Pattern.
    • Model resources for providing access to ID generation, to return "next" IDs for any previously-registered pattern.
    • Write representations for those resources, which can used as payload formats.
    • Write REST APIs in JAX-RS based on that resource model.
3. Generate multiple IDs

User story:
A user wants to have multiple pre-generated IDs filled in when they start to create a set of new records in bulk, as in a grid-oriented data entry screen.

Behavior-oriented user story:

  • As a museum staff member or volunteer
  • When I am entering more than one new record for collection objects, loans, or other entities in bulk
  • I want a set of "next" available IDs to be automatically generated and filled in
  • so that I don't have to look them up, or accidentally assign duplicate IDs.

Service consumer user story:

  • As a service consumer
  • I want to be able to:
    • Read (multiple) a list of "next" IDs, by supplying an ID Pattern identifier.

Anticipated tasks:

  • Build ID Service functionality capable of returning multiple IDs:
    • Extend existing resources to provide access to multiple ID generation, to return multiple IDs for any previously-registered pattern.
    • Write representations for those resources, which can used as payload formats.
    • Write REST APIs in JAX-RS based on that resource model.
4. Handle Concurrent Requests for IDs

User story:
Two or more users need to obtain generated IDs via concurrent or near-concurrent requests.

Behavior-oriented user story:

  • As a museum staff member or volunteer
  • When I am entering one or more new records for collection objects, loans, or other entities
  • and someone else is also doing so at the same time
  • I want the "next" available ID or IDs that are generated for my records to be distinct from the IDs generated for their records
  • so that I don't accidentally assign duplicate IDs.

Service consumer user story:
(This functionality is transparent to a service consumer.)

Anticipated tasks:

  • Research Java's concurrency package and synchronization techniques.
  • Write code and tests to ensure that generated IDs are unique, even in the face of concurrent (or near-concurrent) requests. (This support is also needed for requests to store new ID Patterns.)
5. Generate segment-based IDs

User story:
A user wants to enter the beginning part of an ID, such as an accession lot number, and obtain a generated "next" available ID, such as the next object number associated with that lot.

Behavior-oriented user story:

  • As a museum staff member or volunteer
  • When I am entering new records for collection objects, loans, and other entities
  • When I enter a part of an ID, such as an accession lot number, or an object number
  • I want the "next" available identifier(s) in that pattern, such as the ID for the next object within that accession, or the ID for a sub-object of that object, to be automatically generated and filled in
  • so that I don't have to look it up, or accidentally assign a duplicate ID.

Service consumer user story:

  • As a service consumer
  • I want to be able to:
    • Read a "next ID", by supplying an ID Pattern identifier and the part of the ID which is to be used to generate the "next" ID.
    • Read (multiple) a list of "next" IDs, by supplying an ID Pattern identifier and the part of the ID which is to be used to generate the "next" ID.

Anticipated tasks:

  • Design and build an ID Part Sequence (or Group) class, which adds:
    • Aggregation of a related set of ID Parts.
    • Algorithmic generation of the "next" ID, on a per sequence basis from constituent parts
    • Rules as to when changes in one ID Part Sequence trigger changes (such as resets) in 1-n other ID Parts. Begin with this simplifying assumption: the only rule initially required is that, when the value of a specified ID Sequence changes, all dynamic ID Parts downstream in the chain will have their values reset to their initial values. (E.g. something like this pseudocode: "if canReset(), for each dynamic downstream ID Sequence, doReset()".)
  • Write representations of ID Sequences, which can used in payload formats.
6. Validate IDs

User story:
A user wants their manually-entered IDs to be validated, for correctness against a pattern.

Behavior-oriented user story:

  • As a museum staff member or volunteer, who is entering new records for collection objects, loans, and other entities
  • I want an ID that I enter manually to be validated
  • so that it can be checked that it matches a valid pattern.
  • As a service consumer
  • I want to be able to:
    • Read whether a supplied ID is valid against a pattern, by supplying an ID and an ID Pattern identifier.

Anticipated tasks:

Issues and questions:

  • Do we need a check for "valid against any (one) ID Pattern"?
7. Provide uniqueness of IDs

User story:

Behavior-oriented user story:

Anticipated tasks:
Initial rough notes

  • ...
8. Support reservations and releases of IDs

User story:
Initial rough notes
(Notes about avoiding gaps here ...)
(Notes about block of IDs allocated to researcher for five years here ...)

Behavior-oriented user story:

Anticipated tasks:
Initial rough notes

  • Investigate how we reserve resources.
  • Reserve and un-reserve IDs.
  • Explore a parallel hashing of IDs for quick lookups of ID reservations
  • ...
9. Handle multi-tenancy

User story:

Behavior-oriented user story:

Anticipated tasks:
Initial rough notes

  • Maintain data separately for different tenants, where needed
  • Share data among different tenants, where needed.
10. Support Internationalization

User story:

Behavior-oriented user story:

Anticipated user story:

Dependencies

This should be a description of the major dependencies of the ID Service implementation. Example dependencies could be 3rd party utility classes, core classes or packages, other services, etc.

Test Plan

This should describe how the ID Service implementation will be tested. The testing here could include white box style test, unit test, and/or integration tests.

Data Models