Business Requirements
Primary actors and their goals
Polaris users are defined in the following table.
Actor | Description and Goals |
---|---|
AAI system | Create Polaris account for applicant. AAI does little if any checking, we would like it to check the applicant’s email address and membership of an academic institution – see Dependencies |
AAI user | Any user of Polaris, a user can have many roles. The AAI system will grant access to Polaris for verified prospective users. |
Co-Investigator | Assists Principal Investigator in assembling observing proposals. |
Investigator | Collective term for Principal Investigator and Co-Investigator |
Observatory Administrator | Maintains detailed descriptions of their observatory. Associates known users with their observatory. Assigns known observatory users to be members of their observatory’s Time Allocation Committee (TAC). |
Principal Investigator | Creates and maintains observing proposals. Assigns zero or more users to be a co-investigator. |
Polaris | The web application (system) |
Polaris-user | Collective term for any Polaris user |
Reviewer | Collective term for scientific and technical reviewers. Reviews submitted observing proposals as instructed by the TAC. The reviewer does not necessarily have to be a member of the TAC – in fact one of the driving design goals of PST is to allow “anonymous” community reviewing. |
Scientific Reviewer | Reviews a proposal from a scientific point of view awarding a score to each proposal |
System Administrator | The System Administrator will be assigned from outside the system when it is first deployed. Manages system reference data including user roles and assigning a known user to be a System Administrator. Creates a record for each participating observatory with minimal data, viz, observatory name and address, and TAC Chairman. |
TAC Chair | Chairs Time Allocation Committee |
TAC | Responsible for ranking the reviewed proposals and then allocating observing time based on the rankings and the requested resources. Manages observations schedule (not within Polaris). |
Technical Reviewer | Reviews a proposal from a technical point of view – checks that it is feasible (and probably scores) |
Viewer | Collective term for Investigator and Reviewer |
Business use cases
As a | I want to | So that |
---|---|---|
System Administrator | maintain system reference data | astronomers can readily assemble valid observing proposals. |
manage user roles in Polaris | users get access to the information and features that they need. | |
set up basic observatory data (name etc) and assign an observatory administrator to it | observatory data can be maintained (see observatory administrator details) |
|
Observatory administrator | maintain observatory details and inventory for my observatory, such as proposal cycles, and available resources such as instruments and telescopes | astronomers are aware of the available facilities. |
publish future proposal cycles | astronomers can apply to use the available observatory resources at a suitable time. (This function might be undertaken by TAC Chair) |
|
Astronomer | create an observing proposal for submission to a suitable observatory | I can test my hypothesis by experiment. |
be informed of the TAC’s decision on my proposal | I can consider next steps. | |
clone any proposal of mine | I can edit and submit it to one or more observatories | |
import a proposal created in an external system | I can make use of material generated by non-Polaris investigators | |
export a proposal | I can read it offline its contents can be shared with non-Polaris investigators |
|
Reviewer | identify submitted observing proposals awaiting a decision | I can assign a score to them to enable the TAC to make a decision regarding allocation of observing time |
export a proposal | I can read it offline | |
TAC Chair | invite other users to join the TAC | the TAC can function |
TAC member | consider reviewed proposals | Allocate observing time to suitable proposals, and exceptionally revoke previously allocated proposals when necessary. |
export a proposal | I can read it offline |
System uses cases
There are many Business Rules governing individual use cases, and there is a general Inactivity non-functional requirement covering all use cases.
This document does not describe the interaction between Polaris and the database management system, but it is the case that Polaris must respond gracefully to any failures. Polaris will preserve the integrity and consistency of the data. The data models can be found here
These use cases are presented in rough order of the natural process flow.
Apply to use Polaris
Somebody wants to be able to use Polaris. They apply for access via AAI which will send them login credentials as an astronomer if approved.
Choose a Polaris activity
See business rule Home page features
Item | Description |
---|---|
Primary Actor | Polaris-user |
Preconditions | |
Trigger | Polaris-user has opened the application |
Main Success Scenario | 10 Polaris presents Home page offering Polaris-users options consistent with their Polaris role 20 Polaris-user selects options until finished.
30 Polaris user logs out |
Extensions | |
Occurrence | Frequent |
Success Guarantee | Polaris-user is given access to the desired information and functionality |
Minimal Guarantee | Nothing happens |
Open Issues |
Polaris reference data
Item | Description |
---|---|
Primary Actor | System Administrator (sysadmin) |
Preconditions | |
Trigger | sysadmin has chosen to Maintain Polaris system reference data |
Main Success Scenario | 10 Polaris presents a menu of Polaris system reference data from which the sysadmin selects until finished
20 sysadmin chooses which data to view 30 Polaris retrieves and displays selected data 40 sysadmin makes changes and saves them 50 Polaris confirms changes saved, executes Audit activity, go to step 20 |
Extensions | 20a sysadmin ends request, Polaris follows next user request 40a sysadmin discards changes, go to step 20 |
Occurrence | Occasional |
Success Guarantee | Polaris system reference data has been maintained |
Minimal Guarantee | Nothing happens |
Open Issues |
Observatory reference data
Note that there will almost certainly be no GUI for this activity as it will be infrequent and managed by a scriptable command line interface. See business rule Proposal cycle
Item | Description |
---|---|
Primary Actor | Observatory Administrator (obsadmin), TAC Chair |
Preconditions | |
Trigger | Either user has chosen to Maintain Polaris observatory reference data |
Main Success Scenario | Each of MSS steps 20 – 50 are optional Polaris confirms when any changes have been saved and executes Audit activity 10 Polaris presents a menu of Polaris observatory reference data, from which the user selects until finished
20 obsadmin maintains the observatory’s organization details, observatory instruments with a spectral window setup for each, observatory telescopes, equipment arrays and configurations, and the TAC Chair 30 TAC Chair maintains TAC members 40 TAC Chair maintains proposal cycles each with their available resources 50 TAC Chairs nominates a Polaris user as a Reviewer of a submitted proposal |
Extensions | 20a obsadmin ends request, Polaris follows next request 30a TAC Chair ends request, Polaris follows next request 40a TAC Chair ends request, Polaris follows next request 50a TAC Chair ends request, Polaris follows next request |
Occurrence | Occasional |
Success Guarantee | Polaris observatory reference data has been maintained |
Minimal Guarantee | Nothing happens |
Open Issues |
Create proposal
See business rule Creating a proposal
Item | Description |
---|---|
Primary Actor | Principal Investigator (PI) |
Preconditions | |
Trigger | PI selects Create |
Main Success Scenario | 10 Polaris Assigns PI and presents the proposal maintenance page with the following options from which the PI selects until finished
30 Polaris confirms changes saved, executes Audit activity 40 Polaris follows next user request |
Extensions | 20a PI discards changes, go to step 20 20b PI ends request, Polaris follows next user request |
Occurrence | Frequent |
Success Guarantee | A new observing proposal has been created |
Minimal Guarantee | Nothing happens |
Open Issues |
Import proposal
See business rule Document exchange format
Item | Description |
---|---|
Primary Actor | Principal Investigator (PI) |
Preconditions | A proposal has been created in an external system |
Trigger | Investigator selects Import proposal from the Homepage |
Main Success Scenario | 10 Polaris displays operating system file management window 20 PI selects file to import 30 Polaris confirms selected document has been imported and a proposal created from it, sets its status to Created, assigns PI to imported proposal, and executes Audit activity 40 PI goes to step 10 |
Extensions | 20a PI ends request, Polaris follows next user request 30a Selected file is not in approved Polaris Exchange Format, Polaris displays error message, goes to step 10 40a PI ends request, Polaris follows next user request |
Occurrence | ?? |
Success Guarantee | Externally generated proposal has been imported into Polaris, can be viewed by a Viewer |
Minimal Guarantee | Nothing happens |
Open Issues | Where is the approved Polaris Exchange Format declared? How often will this happen? |
Export proposal
See business rule Document exchange format
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | A proposal exists |
Trigger | Viewer selects Export proposal while viewing it |
Main Success Scenario | 10 Polaris displays operating system file management window 20 Viewer selects destination 30 Polaris confirms proposal has been exported and executes Audit activity 40 Viewer goes to step 10 |
Extensions | 20a Viewer ends request, Polaris follows next user request |
Occurrence | Frequent |
Success Guarantee | Selected proposal has been exported from Polaris |
Minimal Guarantee | Nothing happens |
Open Issues | Where is the approved Polaris Exchange Format declared? |
View proposal
See business rules Viewing a proposal, Editing a proposal, and Document exchange format
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | |
Trigger | Viewer selects View |
Main Success Scenario | 10 Polaris displays a summary list of proposals including Title, Summary, and Status. 20 Viewer selects from the list and views selected proposal until finished, optionally choosing another proposal from the list |
Extensions | 20a Viewer ends request, Polaris follows next user request 20b if Viewer selects Delete proposal then Polaris prompts for confirmation and if Viewer confirms then Polaris deletes it |
Occurrence | Frequent |
Success Guarantee | Observing proposal has been viewed, including the possibility of editing or deleting it. |
Minimal Guarantee | Nothing happens |
Open Issues |
Submit proposal
See business rule Submitting a proposal
Item | Description |
---|---|
Primary Actor | Principal Investigator (PI) |
Preconditions | Observing proposal has been completed by the investigators |
Trigger | PI selects Submit |
Main Success Scenario | 10 Polaris executes Verify Submission and Discover cycles and for any selected proposal displays a list of suitable observatories and proposal cycles 20 PI selects one or more observatory/ proposal cycles and saves 30 Polaris confirms proposal submitted, changes the status to Submitted, executes Audit activity, executes Informs the relevant TAC, and follows next user request |
Extensions | 20a There are no proposals suitable for submission, Polaris displays a message and awaits next user request once the PI has cleared 20b There are no proposal cycles available for this proposal, Polaris displays a message and awaits next user request once the PI has cleared 20c PI discards changes, go to step20 20d PI ends request, Polaris follows next user request |
Occurrence | As the proposal cycle deadline draws near, the rate of submissions will probably increase, and many if not most of them are expected to be in the week before the deadline. |
Success Guarantee | Observing proposal is submitted to the selected observatory |
Minimal Guarantee | Nothing happens |
Open Issues | There is no means as yet to ...capture and store the result of multiple submissions for a single proposal - it may be rejected by one observatory but accepted by another ...capture and store the fact that the observations have been completed |
Withdraw proposal
See business rule Withdrawing a proposal
Item | Description |
---|---|
Primary Actor | Principal Investigator (PI) |
Preconditions | Observing proposal has previously been submitted by the PI |
Trigger | PI selects Submitted |
Main Success Scenario | 10 Polaris executes Withdrawal search for submissions 20 PI selects from the list and requests Withdrawal 30 Polaris confirms withdrawal, and changes proposal status to Withdrawn, executes Audit activity, and executes Informs the TAC and PI 40 PI go to step 20 |
Extensions | 20a PI discards changes, go to step 20 20b PI ends request, Polaris follows next user request |
Occurrence | Rare |
Success Guarantee | Withdrawal decision has been submitted to the selected observatory and their TAC has been made aware of this, with copy to PI. |
Minimal Guarantee | Nothing happens |
Open Issues |
Clone proposal
See business rule Creating a proposal
Item | Description |
---|---|
Primary Actor | Principal Investigator (PI) |
Preconditions | PI is viewing one of their proposals |
Trigger | PI selects Clone |
Main Success Scenario | 10 Polaris makes a copy of the proposal being viewed, Assigns PI to it, and presents the proposal maintenance page with the following options from which the PI selects until finished
20 PI supplies data and saves 30 Polaris confirms changes saved, executes Audit activity 40 Polaris follows next user request |
Extensions | 20a PI discards changes, go to step 20 20b PI ends request, Polaris follows next user request |
Occurrence | Frequent |
Success Guarantee | A new observing proposal has been created |
Minimal Guarantee | Nothing happens |
Open Issues |
Review proposal
See business rules Reviewing a proposal and Document exchange format
Item | Description |
---|---|
Primary Actor | Reviewer |
Preconditions | One or more observing proposals have been submitted to the Reviewer’s observatory |
Trigger | Reviewer selects Review |
Main Success Scenario | 10 Polaris executes Reviewer Search 20 Reviewer selects a result from the list to view 30 Polaris displays the selected proposal 40 Reviewer reads proposal online, and/ or Exports it 50 Reviewer assigns a score to the proposal, adds a comment, and saves 60 Polaris confirms changes saved, Assigns Reviewer to the proposal, changes the proposal status to Scored, executes Audit activity |
Extensions | 20a Reviewer ends request, Polaris follows next user request 20b Result list is empty, Reviewer ends request, Polaris follows next user request 50a Viewer discards, or ends request, Polaris follows next user request |
Occurrence | Frequent |
Success Guarantee | A decision has been captured about the proposal |
Minimal Guarantee | Nothing happens |
Open Issues |
Revoke allocation
See business rule Revoking an allocation
Item | Description |
---|---|
Primary Actor | TAC Chair |
Preconditions | A proposal exists |
Trigger | TAC Chair selects revoke an allocation while viewing allocations |
Main Success Scenario | 10 Polaris displays allocations panel showing future cycle allocations 20 TAC Chair selects an allocation to be revoked 30 Polaris changes proposal status to Revoked, and executes Audit activity, and Informs the TAC and PI 40 TAC Chair ends request, Polaris follows next user request |
Extensions | 20a TAC Chair ends request, Polaris follows next user request |
Occurrence | Rare |
Success Guarantee | Allocation has been revoked |
Minimal Guarantee | Nothing happens |
Open Issues |
Common use cases
Maintain documents
This provides the means to create, view, and edit a proposal but see business rules Creating a proposal, Viewing a proposal, and Editing a proposal
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | A proposal exists |
Trigger | Investigator selects Create Documents while creating a proposal Investigator or Reviewer selects View Documents while viewing a proposal Investigator selects Edit while viewing Documents |
Main Success Scenario | 20 PI selects open document 30 Polaris opens and displays document 40 PI selects Upload document 50 Polaris displays operating system file management window 60 PI selects document 70 Polaris confirms document has been uploaded and executes Audit activity 80 Viewer selects document and Download document 90 Polaris displays operating system file management window 100 Viewer selects destination 110 Polaris confirms document has been downloaded and executes Audit activity 120 Viewer goes to step 40 |
Extensions | 20a Viewer does not select open, go to step 40 20b Viewer ends request, Polaris follows next request 40a PI does not select Upload, go to step 80 40b PI ends request, Polaris follows next request 60a PI ends request, Polaris follows next request 80a Viewer ends request, Polaris follows next request 100a Viewer ends request, Polaris follows next request |
Occurrence | Frequent |
Success Guarantee | All documents displayed, optionally downloaded by Viewer, or added to by Investigator |
Minimal Guarantee | Nothing happens |
Open Issues |
Maintain investigators
This provides the means to create, view, and edit a proposal but see business rules Creating a proposal, Viewing a proposal and Editing a proposal
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | A proposal exists |
Trigger | Investigator selects Create investigators while creating a proposal Investigator or Reviewer selects View Investigators while viewing a proposal Investigator selects Edit while viewing investigators |
Main Success Scenario | 10 Polaris displays the Investigators panel showing Principal Investigator and any Co-Investigators 20 Principal Investigator adds or removes one or more Co-Investigators from a list of available investigators, and saves 30 Polaris confirms changes saved, executes Audit activity, go to step 20 |
Extensions | 20a Investigator ends request, Polaris awaits next user request 20b PI discards, go to step 20 |
Occurrence | |
Success Guarantee | All investigators displayed, optionally added to by PI |
Minimal Guarantee | Nothing happens |
Open Issues |
Maintain justifications
This provides the means to create, view, and edit a proposal but see business rules Creating a proposal, Viewing a proposal and Editing a proposal
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | A proposal exists |
Trigger | Investigator selects Create Justifications while creating a proposal Investigator or Reviewer selects View Justifications while viewing a proposal Investigator selects Edit while viewing Justifications |
Main Success Scenario | 10 Polaris displays the justifications panel showing scientific and technical justifications 20 Investigator changes justifications, and saves 30 Polaris confirms changes saved, executes Audit activity, go to step 20 |
Extensions | 20a Viewer ends request, Polaris follows next user request 20b Investigator discards, go to step 20 |
Occurrence | |
Success Guarantee | All justifications displayed, optionally added to by Investigator |
Minimal Guarantee | Nothing happens |
Open Issues |
Maintain observations
This provides the means to create, view, and edit a proposal but see business rules Creating a proposal, Viewing a proposal, Editing a proposal, and Observations
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | A proposal exists |
Trigger | Investigator selects Create Observations while creating a proposal Investigator or Reviewer selects View Observations while viewing a proposal Investigator selects Edit while viewing Observations |
Main Success Scenario | 10 Polaris displays the observations panel showing a list of observations, each showing its target description, and options which the viewer can select until finished as follows
20 Viewer selects option 30 Investigator changes data and saves 40 Polaris confirms changes saved, executes Audit activity, go to step 30 |
Extensions | 20a Viewer ends request, Polaris follows next user request 30a Investigator ends request, Polaris follows next user request 30b Investigator discards, go to step 30 |
Occurrence | |
Success Guarantee | All observations displayed, optionally added to by Investigator |
Minimal Guarantee | Nothing happens |
Open Issues |
Maintain targets
This provides the means to create, view, and edit a proposal but see business rules Creating a proposal, Viewing a proposal and Editing a proposal
Maintain title and summary
This provides the means to create, view, and edit a proposal but see business rules Creating a proposal, Viewing a proposal and Editing a proposal
Item | Description |
---|---|
Primary Actor | Viewer |
Preconditions | A proposal exists |
Trigger | Investigator selects Create title and summary while creating a proposal Viewer selects View title and summary while viewing a proposal Investigator selects Edit while viewing title and summary |
Main Success Scenario | 10 Polaris displays the title and summary panel 20 Investigator changes data and saves 30 Polaris confirms changes saved, executes Audit activity, go to step 20 |
Extensions | 20a Viewer ends request, Polaris follows next user request 20b Investigator discards, go to step 20 |
Occurrence | |
Success Guarantee | title and summary displayed, optionally edited by Investigator |
Minimal Guarantee | Nothing happens |
Open Issues |