Page History

Querytool Use Cases

1. Logon
2. New Search
3. Show Search Results
4. Select Specimens
5. Process Specimen Request
6. Remap Specimens to Codebook
7. Show Specimen Request
8. Show User History
9. Restart Search
10. Delete Search
11. Source code for each use case

Use Case: Logon

Precondition(s):                          

Post-condition(s):            

• User authenticated by Ecommons service
• Started Session for authenticated user
• Recorded logon event
• Cached copy of the users search history is loaded into the current session
• Session Cache contains User object and Signed Identity

Steps:

1. Go to logon page
2. Authenticate @ Ecommons with username & password
3. Lookup user role (public, investigator, admin) from the local database
4. Assign digitally signed SPIN Identity (included in all SPIN queries)
5. Load user search history (user session context)
6. Forward user to search page
   

Alternate Paths

#2.IF Authentication fails, THEN reload logon page

#3.IF the user has no assigned role, THEN assign the default public role.

Notes

The Ecommons authentication service can be replaced by a local identity service or any other service adhering to the Identity Service interface.

Use Case: New Search

Precondition(s):

• User is authenticated

Post-condition(s):            

• Search is started
• User is forwarded to the results page
• Search criteria is cached in the user session
• Search criteria is saved to user history

Steps:

1. Go to search page
2. Enter form criteria including
   1. Full Text Search Expression
   2. Age at specimen collection
   3. Year of specimen collection
   4. Gender (F, M, T, U)
   5. Search Results
      1. Age at specimen collection
      2. Year of specimen collection
      3. Diagnosis Text
      4. Gender

1. Click "Locate De-Identified Specimens"
2. System submits query and writes the log event with queryId and criteria

Alternate Paths

#4.If the query criteria is invalid, reload the search form.

Notes

• See the User Guide for descriptions of the Full text query expressions

Use Case: Show Results

Precondition(s):                        

• queryId is provided to lookup the search results (in querystring)

Post-condition(s):

• User is displayed search results

Steps:            

1. System polls for completion of the SPIN query (showing GRAPH of current results)
2. When SPIN query is complete, user is forwarded to the results page.
3. Show the query criteria header
4. Show the statistical results as graph image (Bin on Age or Bin on Age & Gender)
5. Show specimen details according to access policies (investigators only) and Criteria
   1. Icon of the Peer repository (BWH, MGH, CHB, ...)
   2. Gender
   3. Patient Age at Specimen Collection
   4. Tissue Acquisition Date
   5. Diagnosis Text (highlighting any term that was part of the search)
      

Alternate Paths

#1.If the query never completes (node offline), it will complete as a "timeout" after the default time period (TTL)

Notes

If an investigator logged out, then they must rerun the query to view detailed results.

Use Case: Select and Request Specimens

Precondition(s):                        

• User is investigator and on the Results Page @See Show Results

Post-condition(s):

• Investigator level user can select and requested specimens

Steps:            

1. Investigator browses list of specimens
2. Investigator can resort the specimens by any of the return variable types
   (gender, age, TissueDate, peer)
3. All search terms are BOLD and when hovering a single case it is highlighted
4. Clicking a case will bold-highlight that case
5. User can browse through all the results, broken down into result "pages"
6. Navigating to a new page will keep track of all the previously selected specimens.
7. When the investigator is satisfied with their selections, they will click the "Request Specimens"
8. The Investigator will then confirm their selections, optionally removing any entries.
9. The Investigator will then complete the specimen request

a.     "I accept the terms of this disclaimer"

b.    Project Title

c.     Project Description

d.    Notes to Pathologist

1. The specimen request will be saved to the querytool database (visible via the /specimens page)
2. The specimen request will be emailed to the administrator.
3. The specimen request will be sent to the pathology core system.

Alternate Paths

Notes

Use Case: Process Specimen Request in Pathcore (needs update-mike)

Precondition(s):                        

• ...
  

Post-condition(s):

• ...

Steps:            

1.     ....

Alternate Paths

Notes

Use Case: Remap Specimens via codebook (needs doc update)

Precondition(s):                        

• ...
  

Post-condition(s):

• ...

Steps:            

2.     ....

Alternate Paths

Notes

Use Case: Show Specimen Requests

Precondition(s):                        

Post-condition(s):

• Display This user's specimen requests (if any)
  • Status
  • Peer(s)
  • Project Title
  • Project Description
  • Tracking # (queryId)
  • Notes to Pathologist
• Specimen Availability and Business Rules from each of the participating peer institutions
  • # Specimens available, rules, and pricing
  • Material Transfer Agreement

Steps:            

1. Go to specimens page
2. Website shows specimen requests and availability from all sites.
   

Alternate Paths

#1.IF no specimen requests are open, display "you have not requested any specimens".

Notes

• Specimen availability cannot be currently be queried in real time, will use a static specimen count.
  
  

Use Case: Show User History

Precondition(s):                        

Post-condition(s):

• User history is shown
  • Query criteria
  • Option to restart search (@see Restart search)
  • Option to delete search (@see Delete Search)

Steps:            

1:       Go to history page

2:       User is shown a list of their previously run queries

Alternate Paths

#2.IF Authentication fails, THEN reload logon page

#3.IF the user has no assigned role, THEN assign the default public role.

Notes

Specimen Requests should not be shown in the history, @SEE Show Specimen Requests

Use Case: Restart Search

Precondition(s):                        

• queryId is provided to lookup the search criteria

Post-condition(s):

• User restarts a query with the same / modified criteria

Steps:            

1. Go to history page
2. Select a query previously run
3. User is forwarded to the New Search page with the historical query criteria already populated

Alternate Paths

#2.IF Authentication fails, THEN reload logon page

#3.IF the user has no assigned role, THEN assign the default public role.

Use Case: Delete Search

Precondition(s):                        

• queryId is provided to lookup the search

Post-condition(s):

• delete search results (statistical graph image)
• search criteria is no longer shown in user history page

Steps:            

1. User clicks "delete search" from the history page
2. System forwards user to history page

Alternate Paths

Notes

• Detailed results (including the SOAP message) are never cached in the query-interface. This is for IRB compliance and general concerns over a single centralized node.
• Once the user fetches the results from the cache once, the results are stored in the user session and removed from the cache. If the user wants to see detailed results again, then a new query must be reissued. (Statistical results still available)
  
  

Appendix

Primary Supporting Java Files by Use Case (Needs doc update)

Note: VSLApplicationResources is used to one-time initialize Application Wide Modules

• Agent                           (send/receive SPIN messages to/from supernode)
• Cache Driver                (used to read back query responses)
• Identity Service            (façade to eCommons identity service with Digital Signing of the auth token)
  

Logon

• LogonServlet
• Logon.jsp
• EcommonsIdentityService
• UserVO
• Identity
• DataSourceManager
  • logEventUserLogon(...)
  • getUserEventHistory(...)
• SessionCache
  • setUserVO(...)
  • setIdentity(...)

New Search

• SearchServlet
• search.jsp
• Agent           
  • getDefaultQueryInfo(...)
  • send(...)
• DataSourceManager
• logEventQueryStarted(...)
• SessionCache
  • getIdentity(...)
  • setCriteria(...)
    

Show Results

• ResultsServlet
• polling.jsp
• results_main.jsp
• results_specimen_detail.jsp
• Agent
  • isComplete(...)
  • getResultNoDelete(....)
  • getResult(....)
• DataSourceManager
  • logEventQueryCompleted(...)
• SessionCache
  • getCriteria(...)
  • hasCompleted(...)
  • setChart(...)
  • setResponse(...)
  • setSpecimens(...)
  • getUserVO(...)
    

Select and Request Specimens

• SpecimensServlet
• results_main.jsp
• results_specimen_detail.jsp
• specimen_final_confirmation.jsp
• Agent
• SenderConfiguration
• SpecimenRequest
• SpecimenCollection
• DataSourceManager
  • logEventUserRequestSpecimens(...)
  • SessionCache
  • getCriteria(...)
  • getSpecimens(...)
  • setSpecimens(...)
  • hasSpecimens(...)
  • getUserVO(...)
    

Show Specimen Requests

• SpecimensServlet
• specimens.jsp
• SessionCache
  • getQueryVOs(...)

Show User History

• HistoryServlet
• history.jsp

• SessionCache
  • getQueryVOs(...)
    

Restart Search

• SearchServlet
• search.jsp
  

Delete Search

• ResultsServlet
• History.jsp
• DataSourceManager
  • logEventQueryDeleted(..)
• SessionCache
  • removeQueryEventLog(...)