Skip to content

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
  • Person
  • Organization
  • Observatory
  • Observatory Administrator
  • System Administrator

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
  • Administration - obsadmin only
  • Organization - obsadmin only
  • Resources - obsadmin only
  • Time Allocation Committee - both
  • Proposal cycles - both

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 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

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
  • New observation (implies target)
  • Identify target and field
  • State performance parameters with one or more spectral windows and spectral lines
  • State one or more timing windows
  • State constraints

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

See Maintain observations

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