#  Document control {#document-control .TOC-Title .unnumbered}

## Previous documents {#previous-documents .Doc-Control-Headings .unnumbered}

  ---------- -------------------- --------- -------- ------------ ------------ --------------
  Document   File Name            Version   Issue    Date         Replaced by  Reason
  Name                            Number    Date     with-drawn                

  Pullist    Pulllist_specs.doc   2                                            
  specs                                                                        

                                                                               
  ---------- -------------------- --------- -------- ------------ ------------ --------------

## Version history {#version-history .Doc-Control-Headings .unnumbered}

  --------- --------- -------- ------------------ ------------ -------------- -------------
  Version   Date      Author   **Comments**       **Sections   **Circulated   **Purpose**
                                                  affected**   to:**          

  0-01                         Initial draft      All                         
  --------- --------- -------- ------------------ ------------ -------------- -------------

## Changes since last version {#changes-since-last-version .Doc-Control-Headings .unnumbered}

  ------------ ------------------------------------- ---------------------
  Section      Change                                Reason for change

                                                     
  ------------ ------------------------------------- ---------------------

## Outstanding issues and omissions {#outstanding-issues-and-omissions .Doc-Control-Headings .unnumbered}

  ------------ ----------------------------------------------------------
  Section      Issue or Ommission

               
  ------------ ----------------------------------------------------------

## Distribution control {#distribution-control .Doc-Control-Headings .unnumbered}

  --------------------- --------------------------- ---------------------
  Author:               Shelley Tworoger            

  Signature:                                        Date:
  --------------------- --------------------------- ---------------------

## Distribution List {#distribution-list .Doc-Control-Headings .unnumbered}

  ------------- ------------------- ----------------- ---------------------
  **Company**   **Entity**          **Recipient       **Action**
                                    Name**            

                                    Shelley Tworoger  

                                    Mark Magid        

                                    Helena Judge      
                                    Ellis             

                                    Rachel DePasquale 

                                    Jeanne Sparrow    

                                    Eric Rimm         

                                    Sue Hankinson     
  ------------- ------------------- ----------------- ---------------------

## File reference(s) {#file-references .Doc-Control-Headings .unnumbered}

#  Contents {#contents .TOC-Title .unnumbered}

1\. Introduction [5](#introduction)

1.1 Purpose of document [5](#purpose-of-document)

1.2 Background [5](#background)

1.3 Scope of the specification [5](#scope-of-the-specification)

1.4 Input [5](#input)

1.5 Output [5](#output)

1.6 Glossary of Terms and Definitions
[6](#glossary-of-terms-and-definitions)

1.7 Contacts [7](#contacts)

2\. Functional Overview [8](#functional-overview)

2.1 Business Objectives [8](#business-objectives)

2.2 Functional Diagram [8](#functional-diagram)

2.3 Design Mock-up [9](#design-mock-up)

2.4 Requirements [9](#requirements)

2.5 Non-Functional Requiremets [11](#non-functional-requiremets)

2.6 Outstanding Issues [11](#outstanding-issues)

# Introduction

## Purpose of document

The purpose of this document is to outline the specifications for
dealing with missing vials after a pull list has been generated (see
Pull List specifications) and when the blood lab RAs are pulling
samples. For a small proportion of samples, the freezer database has the
incorrect location. If the RA cannot locate the sample in a different
spot in the box, a new vial must be pulled. The purpose of this
secondary application is to allow the end-user to update the freezer
database with the vial information and if needed to select a new vial to
pull for the project.

## Background

When an error is discovered on a pull list (e.g. a vial is not in the
expected location), the RA attempts to locate the correct tube in the
same box (usually the tube is there). The freezer database must then be
updated to correct the error and note which tube was actually pulled. If
the tube cannot be easily located, the freezer must be updated to
reflect what was actually in the spot of interest (either no tube or a
different ID) and then select another vial for the pull list.

## Scope of the specification

The only concern of this application and this specification are to allow
the end-user to correct problems in the freezer database, update the
freezer database to reflect the actual status of the spot of interest
and, if needed, to choose a new vial to be selected for the pull list.

## Input

All inputs will be entered by the user into the screen described below.
The related pull list will need to be accessed to update the new
location of the vial.

## Output

Output will include one or two pieces of information. The first piece
will be output every time and will include a verification that the
freezer database has been correctly updated or the vial has been frozen
from further use until additional checks have been made. The second
piece of information will only be output if the user needs to select a
new vial(s) for the active pull list. This will be in the pull list
format described in the Pull List Specifications and will include output
such as freezer, rack, box, and spot of the new vial to be pulled (see
appendix A).

## Glossary of Terms and Definitions

  -----------------------------------------------------------------------
  Term              Definition
  ----------------- -----------------------------------------------------
  Vial              A tube filled with biological specimen to be used in
                    an assay request or as part of a pull list.

  Pull List         General term for the functionality that generates the
                    all the vial lists used to pull biospecimens from the
                    freezer for a set of assay requests.

  STAGES OF PULL    
  LIST              

  Initialization    Entering the initial data for a pull list, choosing
                    assay requests, setting parameters. Includes making
                    decisions about appropriate parameter settings and
                    changing those parameters to get the best list.

  Active            Approved and finalized the pull list, all final
                    parameter settings selected. Vials are reserved in
                    the database. Pull list has been generated and blood
                    lab personnel are actively pulling samples out of the
                    freezer. Includes updating the freezer file when an
                    incorrect tube is found, getting new locations of
                    alternate vials, and noting what new subvials have
                    been created.

  Completed and\    After all vials have been pulled for a particular
  Updated           pull list, finalized updates are made to the freezer
                    file, including removal of original and subvials,
                    addition of newly made subvials. Also includes final
                    update to the sub-sending list that notes which vials
                    were sent for which assay requests.

  TYPES OF LISTS IN 
  PULL LIST         
  FUNCTIONALITY     

  Original vial     List of original vials, separated by vial type (i.e.
  list              vial size), with locations in the freezer and other
                    information (see appendix) to be used for pulling
                    vials for a Pull List. Generated by the pull list
                    functionality.

  Subvial list      List of subvials, separated by assay request, with
                    locations in the freezer and other information (see
                    appendix) to be used for pulling vials for a Pull
                    List. Generated by the pull list functionality.

  Index number      A sequential set of numbers, beginning at 1, assigned
                    to each vial in a pull list overall all original and
                    sub-vial lists. In other words, no number is repeated
                    and this acts as a unique identifier within pull
                    list.

  Unique Vial ID    ID number assigned by oracle for every vial handled
                    in a pull list or other project

  Participant ID    The ID number assigned to a participant when he or
                    she entered the study

  Pull list ID      ID number assigned by oracle for each Pull List
                    generated for a set of assay requests.

  Sub-sending list  A list of all potential IDs/vials in an assay
                    request. Notes what vial was sent for that
                    individual, whether a vial was sent for that
                    individual, and if not sent then why.
  -----------------------------------------------------------------------

## Contacts

+----------+---------------+------------+------------+---------------+
| Name     | Job Title/    | Signoff    | Telephone  | E-mail        |
|          | Position/     |            |            |               |
|          | Role          |            |            |               |
+----------+---------------+------------+------------+---------------+
| Shelley  | Project Lead  |            | 5-2087     | <n            |
| Tworoger |               |            |            | hsst@channing |
|          |               |            |            | .harvard.edu> |
+----------+---------------+------------+------------+---------------+
| Mark     | Project       |            | 5-0074     | mgmag         |
| Madgid   | Development   |            |            | i@hotmail.com |
+----------+---------------+------------+------------+---------------+
| Helena   | Lab Manager   |            | 61         | <n            |
| Judge    |               |            | 7-732-5781 | hhje@channing |
| Ellis    | End User      |            |            | .harvard.edu> |
+----------+---------------+------------+------------+---------------+
| Rachel   | Lab Manager   |            |            | hprap@channin |
| De       |               |            |            | g.harvard.edu |
| Pasquale | End User      |            |            |               |
+----------+---------------+------------+------------+---------------+
| Jeanne   | Data Manager  |            | 5-4220     | nhjms@channin |
| Sparrow  |               |            |            | g.harvard.edu |
+----------+---------------+------------+------------+---------------+

# Functional Overview

## Business Objectives

## Functional Diagram

Enter Assay Request Enter Assay Request Enter Assay Request

\*if replace/delete participants

\*\*if need to change parameters

Conduct tally to find cases/controls

that may need to be removed,

update sending lists.

Create Pull List Request

\* \*\*

See Intermediate Results (Put "hold" on potential vials)

Finalize Pull List

Generate Freezer Pull List(s)

\*\*\*if a vial is Generate Pull Box Labels

missing in

freezer, pull (Blood Lab RA Pulls Tubes\*\*\*)

alternate vial if

one exists, if Generate Sub-Sending List by Assay Request

not remove from to note which ID's will actually be set.

list + any matched

controls if a case Sorting Lists Information Defined (e.g. Box size,
aliquot volumes)

Sort Lists Generated

-Aliquot sort list, separated Final sort list, separate by assay

by original vial volume request , notes where subvials are

-Generates labels for newly placed into sending boxes. Make

aliquoted tubes QC labels

Actual aliquots recorded Add QCS w/ labels that have fake ID's

in healthtrack Put subvials into

sending box

New aliquots into Computer generates a box list/ASCII file

sending box Double check, give sub-sending list to programmer

## Design Mock-up

N/A

## Requirements

Below are the fields and actions that should be included on the Missing
Vial Update user-interface:

\* Pull list ID: \<Single selection of pull down list of Active
(pulling) Pull List IDs\>. Based on this selection, the corresponding
information about the cohort, collection, sample type, endpoint, and all
assay request IDs in the pull list will be displayed.

To note which vial is missing the user will have several options:

1.  Index Number: \<user will enter the index number from the pull list
    of the affected vial\>

2.  Unique Vial ID (assigned by oracle): \<user will enter the unique
    vial ID of the affected vial\>

3.  Multi-field entry of:

    a.  Freezer \< Single selection, pull down list \>,

    b.  Rack \< Single selection, pull down list \>,

    c.  Box \< Single selection, pull down list \>,

    d.  Spot \< Single selection, pull down list \>

Based on the above information the screen will display the following
fields:

1.  Index number

2.  Unique Vial ID

3.  Participant ID

4.  Freezer

5.  Rack

6.  Box

7.  Spot

8.  Volume of missing vial

User will confirm information, the press a button to proceed.

User must indicate the status of the spot in the box with the incorrect
pull list information. The actions taken depend on the selection of the
user. The field "Status of Vial" will contain the following options:

\* Status of Vial: \< single select list with choices below\>\
a. No vial in spot,

b\. Same participant ID but different sample type (e.g., buffy
coat/plasma or follicular/luteal),

c\. Same participant ID and sample type but different volume,

d\. Different participant ID

e\. For NHS2 include "Same participant ID, different Unique Vial ID".

Actions associated with choices of "Status of Vial" field:

1.  [No vial in spot]{.underline}: freezer database is updated to
    reflect that the vial in that spot has been removed. Prompts user to
    complete the next field called "Alternate Vial Found?".

2.  [Same participant ID but different sample type]{.underline}: User
    will be prompted to complete the field "Correct Sample Type" which
    is a single selection pull down list of the possible types that are
    cohort/collection specific (e.g., buffy coat, plasma, DNA,
    follicular, luteal, etc.). Then user will be prompted to complete
    the field "Correct Volume", , which is a single selection pull down
    list of the possible volumes (e.g., 100ul, 200ul, 300ul, etc.) and
    will choose the closest volume. After user enters this field, the
    database will be updated to reflect the correct sample type and
    prompt the user to complete the next field called "Alternate Vial
    Found?".

3.  [Same participant ID and sample type but different
    volume]{.underline}: User will be prompted to complete the field
    "Correct Volume", as described above. After user enters this field,
    the database will be updated to reflect the correct volume and
    prompt the user to complete the next field called "Alternate Vial
    Found?".

4.  [Different participant ID]{.underline}: User will be prompted to
    complete the field "Correct participant ID" which will be a straight
    numeric data entry field, "Correct Sample Type", and "Correct
    Volume" as described above. However, the database will not be
    updated to reflect this change directly. Instead this vial/spot will
    be invalidated and kept from further use until such time that a more
    thorough investigation of the box occurs (e.g., checking for a shift
    in IDS) and the database is corrected. A report will be generated in
    oracle recording the location of the mismatched IDs for further use
    by the Lab manager. User will be prompted to complete the next field
    called "Alternate Vial Found?".

The next step is for the user to note whether an appropriate vial was
found in the box nearby or not.

\* Alternate Vial Found: \<single selection, yes or no\>

Actions are:

1\. If yes, user will be prompted to enter the location of the vial
pulled, using the following fields:

\* Freezer \< Single selection, pull down list \>,

> \* Rack \< Single selection, pull down list \>,\
> \* Box \< Single selection, pull down list \>,\
> \* Spot \< Single selection, pull down list \>
>
> \* Volume \< Single selection, pull down list \>
>
> \* if NHS2 then enter unique vial ID if a subvial
>
> The freezer database then needs to be updated to reflect that this
> vial has been removed and the internal pull list/sub-sending list
> needs to be updated about the alternate vial being used.

2\. If no, then HealthTrack to enter the freezer database to select an
alternate vial, updating the\
internal pull list/sub-sending list.

\* Buttons: 1. Input another missing ID (for the same pull list), 2.
Print out new freezer\
location(s) for alternate vials (see appendix A).

NOTE: When choosing an alternate vial, Healthtrack may have to choose a
vial based on a different vial priority than the vial on the original
vial list. If this occurs, the appropriate lists must be updated to
exclude the originally selected vial and add the newly selected vial.
For example if a subvial was originally chosen and then not found and an
original vial was selected, the subvial list will be updated to show
that the ID is now not on that list and the original vial list will add
that ID/vial on it's list.

## Non-Functional Requiremets

Research Assistants and Lab Technicians generally have not used oracle
databases. The user interface of this and any part of Htrack needs to
accommodate for their skill set and ensure usability by making the
product as easy to use for non-technical people as possible.

## Outstanding Issues

*None*

**Appendix A**

[a. Example of an original vial list]{.underline}

PULL LIST ID = 1000

COHORT = NHS

ENDPOINT = BREAST CANCER

FOLLOW-UP YEARS = 1990 -- 2004

APPLICABLE ASSAY REQUESTS = 100, 101, 102

SAMPLE TYPE = PLASMA

PULL LIST TYPE = ORIGINAL VIAL 4.5mL

<table>
<colgroup>
<col style="width: 6%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 6%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 10%" />
<col style="width: 10%" />
</colgroup>
<tbody>
<tr class="odd">
<td>Index #</td>
<td>Partici-pant ID</td>
<td><p>Unique</p>
<p>vial ID</p></td>
<td>Freezer</td>
<td>Rack</td>
<td>Box</td>
<td>Spot</td>
<td>Volume</td>
<td><p>Multiple</p>
<p>vial #</p></td>
<td>Pull box number</td>
<td>Pull box spot</td>
<td>Comments area</td>
<td>Applicable assay requests</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>

[b. Example of an subvial list]{.underline}

PULL LIST ID = 1000

COHORT = NHS

ENDPOINT = BREAST CANCER

FOLLOW-UP YEARS = 1990 -- 2004

FOR ASSAY REQUEST = 100

SAMPLE TYPE = PLASMA

PULL LIST TYPE = SUBVIALS

<table>
<colgroup>
<col style="width: 7%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 6%" />
<col style="width: 6%" />
<col style="width: 6%" />
<col style="width: 9%" />
<col style="width: 9%" />
<col style="width: 8%" />
<col style="width: 8%" />
<col style="width: 11%" />
</colgroup>
<tbody>
<tr class="odd">
<td>Index #</td>
<td>Partici-pant ID</td>
<td><p>Unique</p>
<p>vial ID</p></td>
<td>Freezer</td>
<td>Rack</td>
<td>Box</td>
<td>Spot</td>
<td>Volume</td>
<td><p>Multiple</p>
<p>vial #</p></td>
<td>Pull box number</td>
<td>Pull box spot</td>
<td>Comments area</td>
</tr>
<tr class="even">
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>