Basic Use Cases for the Users Database
v2

Bryan Butler

2004-Oct-22


This set of use cases describes interactions with the User Database 
(see the document _NRAO User Database_).  The program and interface 
that give access to the User Database is the User Database Tool, 
and it will be made clear whether access to it is via a GUI or API.

Acronyms:
  UD = User Database
  UDT = User Database Tool
  UDTGUI = User Database Tool GUI
  UDTAPI = User Database Tool API
  UDM = User Database Manager
  PD = Proposal Database
  PT = Proposal Tool
  PI = Principal Investigator
  CoI = Co-Investigator



 Use Case 1 - A returning user, entering a proposal 

This is a use case for a user who already exists in the UD desiring 
to put in a proposal (as PI).

I. user goes to the PT login page.
II. user enters username and password.
III. user proceeds into the PT with the proper identifying information.

Implementation notes (yes, I recognize that these are a bit out of
scope for a Use Case, but here they are anyway):

   Presumably the "login" page of the PT is just a front-end to the 
   UDT, i.e., it calls the UDTAPI.  Either that, or the UDTGUI actually
   truly acts as the portal through which access to the PT is obtained.

   The information that should be passed from the UDT to the PT is:
      Users.UniqueID
      Users.FirstName
      Users.LastName
      Users.Type (this is an indicator of whether the user is a
         PhD student or not)
      Addresses.Email
      Institutions.UniqueID
      Institutions.Name
   Consider this as the "object" that is passed from one to the other,
   as this is the information that the PT might retrieve from the UDT.
   Alternatively, the UDT could just pass the Users.UniqueID, and
   require the PT to do the database lookup for the other information.



 Use Case 2 - A new user, entering a proposal 

This is a use case for a user who does not already exist in the UD 
desiring to put in a proposal (as PI).  Because all PIs for proposals 
must exist in the UD, the user needs to get into the UD.  

I. user goes to the PT login page
II. user is not in the current UD, so identifies himself as a new user.
III. a form is brought up that must be filled out by the user, 
     containing the fields of the Users Table.  Fields that must be
     entered are:
        FirstName
        LastName
        Type
IV. a form is brought up for address information, containing the fields
    of the Addresses Table.  Fields that must be entered are:
       Type
       Country
       Email
    Note that Country should be from a pull-down menu, with USA as the
    topmost entry.
V. institutional information must be gathered.
   A. user attempts to find his institution (this could be a pull 
      down, first letter driven, full searchable text field, etc...).
   B. if user's institution exists in the current list, he selects it.
   C. if not, new institutional information must be entered - this is
      the information from the Institutions Table.  Fields that must
      be entered are:
         Name
         Department
         Type
         Parent (or none)
         ContactPerson
         Address Information
      The Address information is the same as that for item V. above,
      except that the Type is automatically filled in (indicating
      that it is an Institutional address), and the Email is not
      required (so only the Country is absolutely required here).
VI. user is asked to review all of the input information, and given
    two options:
    A. edit any of it.
    B. submit it.
VII. after submitting the information, the user is automatically 
     assigned a unique username and password (emailed to the email 
     address entered), and taken directly to the PT, with the proper 
     identifying information.

UD Handling note (yes, I recognize that this is also a bit out of
scope for a Use Case, but here we go anyway):

   After entering the information above, it should be verified by
   an appropriate UDM.  Verification should include at the very least 
   checking for duplicate Users Table and Institutions Table entries.
   Special care should be taken with new Institutions Table entries
   (with the minimal set of input information - see V.C above).



 Use Case 3 - A returning user, not sure if they are in the UD or not 

In some (many?) cases, our users may forget whether they have signed
up with the tool or not.  In this case, there needs to be a search
capability in the signin page to determine this.

I. user goes to the PT login page
II. user is not sure if they are in the current UD or not, and
    indicates so.
III. user is taken to some sort of search page, where searches might 
     be done by last name (partial matches should be supported - 
     wildcards would be nice, but not critical), by pull-down menu
     (displaying name), by all users at a given institution, or
     by more complicated search method.
IV. if the user is in the UD, they click on the proper entry, and
    they are taken back to the PT login page, with the username
    field filled in (password blank, of course).



 Use Case 4 - A returning user, whose information has changed 

As users move around, they need to be able to modify their information 
within the UD.

I. user goes to the PT login page
II. user enters username and password, and clicks a box that indicates
    that the information has changed
III. steps III - VI of Use Case 2 are executed
IV. the user is taken to the PT, with the proper new identifying 
    information.



 Use Case 5 - A returning user, entering a proposal with CoIs 

This is a use case for a user who already exists in the UD desiring 
to put in a proposal (as PI).  The proposal has several Co-Is, some of 
which are already in the UD, and some of which are not.

I. user goes to the PT login page
II. user enters username and password.
III. user proceeds into the PT, with the proper identifying information.
IV. within the PT, the user needs to enter CoI information, for each
    CoI, the user:
    A. does a search for the CoI in the current UD (this could be a 
       pull down, first letter driven, full searchable text field, 
       etc... - see Use Case 3, step III).
    B. if the CoI is in the UD, the information is retrieved into the
       PT.  
       1. if the information is incorrect, and the PI knows this, the 
          PI should be able to modify the information that is in the PT 
          and hence in the PD (but *not* that in the UD - that can only 
          be done by the CoI).
    C. if not, CoI information must be entered.  The minimal 
       information that must be entered for CoIs is:
          FirstName
          LastName
          User Type (important for indicating PhD students)
          Country
          Email
          Institutional Name

Implementation note:

   The information gathered in step IV.B.1 or IV.C (i.e., in the case 
   that the CoI is new or has changed information) should be passed 
   back to the UDT, i.e.:
      Users.FirstName
      Users.LastName
      Users.Type
      Addresses.Email
      Addresses.Country
      Institutions.Name
   Would be passed back.  If the information is new, the UDT should 
   then create a temporary entry for this person.  It is unclear how
   to store the information in the case that it is incorrect.  An 
   appropriate UDM should review it.  A nag email should be sent to 
   this CoI, stating the entered information, who entered it (the PI), 
   and pointing them to the UDTGUI (the main one, not the one embedded 
   in the PT [if they are different]), to get them to enter more full 
   information, or verify the changed information from the PI.  For new 
   CoIs, this presents a bit of a problem, as the question of how to 
   feed that new information back to the PD is open - but for now we 
   can just say that we don't feed any of it back (so, Users.UniqueID 
   and Institutions.UniqueID in the PD entry for that CoI in that 
   proposal are null).



 Use Case 6 - A user forgets their password 

The existence of forgetting has never been proved:  We only know that 
some things don't come to mind when we want them.  Friedrich Nietzsche

I. user goes to the UDTGUI (or PT) login page
II. user indicates that he has forgotten his username and/or password.
III. user is taken to some sort of search page - see Use Case 3, step III.
IV. user selects himself.
V. an email with username and password is sent to the email in the
   UD for that person.



 Use Case 7 - A UDM, editing information 

This is a use case for a UDM editing information in the UD.  This 
could be as part of the verification process, or as a result of
communication with the user.

I. UDM goes to the UDTGUI login page
II. UDM enters username and password, and proceeds into the UDTGUI, 
    with the UDTGUI recognizing that this person has both read and 
    write capability into the UD.
III. UDM does a search for a user in question in the current UD (this 
     could be a pull down, first letter driven, full searchable text 
     field, etc... - see Use Case 3, step III).
     A. if the user is found, the UDM is taken to forms similar to 
        those in Use Case 2, items IV., V., and VI.
        1. UDM can edit fields in the Users Table, except for UniqueID.
           Note that this is the only way a username and password can
           be modified - i.e., the user himself cannot do so, only a
           UDM.
        2. UDM can add or delete linked Addresses Table entries.
           i. UDM can edit the information in the existing Addresses 
              Table entries.
           ii. For an added Addresses Table entry, a blank form is
               started with, and the UDM fills in the information.
        3. UDM can change the linked Institutions Table entry.
        4. UDM can add Notes Table entries.
        5. UDM can add Flags Table entries.
     B. if the user is not found, the UDM is taken to the same forms,
        with blank entries.  In this case, a new UniqueID, username,
        and password must be created.
     C. UDM is asked to review all of the information for the user, and 
        given two options:
        1. go back and edit any of it.
        2. submit it.
IV. UDM does a search for an institution in question (this could be a 
    pull down, first letter driven, full searchable text field, etc...).
    A. if the institution is found, the UDM is taken to an institution
       editing form, where he can:
       1. modify the fields therein (except for Institutions.UniqueID).
       2. modify the linked Address.
    B. if the institution is not found, the UDM is taken to a new
       institution form, where the information is entered.
       1. when choosing the Parent institution, if one exists, the list 
          of existing institutions should be presented for selection 
          therefrom.  If there is no Parent institution, this field
          is left as null.