Polaris is designed to be deployed into a kubernetes cluster
+ + + + + + + + + + + + + +These business requirements are documented following Alistair Cockburn’s recommendations in Writing Effective Use Cases, Addison-Wesley, 2001.
+The use cases are well-formed processes and sub-processes with a purpose, a trigger, some inputs, and some outputs. +The happy path is described as numbered steps in the Main Success Scenario, with alternatives and error responses described in +the Extensions. The numbered steps in the Extensions correspond to the MSS steps.
+Some use cases (eg, maintaining investigators) and components (eg audit activity) are called by other use cases, (eg, create a proposal, edit a proposal). Such items are declared just once and referenced by name with a bold italic hyperlink. Click the hyperlink to see the detail and then return with the browser back button.
+The data models can be found in a separate project.
+The UI is documented elsewhere.
+ + + + + + + + + + + + + +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 | +
| 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 | +
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.
+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.
+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 | ++ |
| 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 | ++ |
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 | ++ |
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 | ++ |
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? |
+
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? | +
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 | ++ |
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 |
+
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 | ++ |
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 | ++ |
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 | ++ |
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 | ++ |
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 | ++ |
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 | ++ |
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 | ++ |
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 | ++ |
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
+ +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 | ++ |
A proposal is assigned one of the following depending on its current state.
+Polaris assigns the current user as PI for the created proposal
+Polaris assigns the current user as Reviewer for the submitted proposal
+For all database Create, Update, and Delete activity, Polaris writes to the transaction audit log capturing username, datetime stamp, activity (Create, Update, Delete), and an array of table, fieldname, old value, new value, for each field changed.
+For import and export activities, Polaris writes to the transaction audit log capturing username, activity, proposal title and key
+Polaris compares the proposal’s technical goals with available observatory equipment and returns a list of observatories with proposal cycles having submission deadlines in the future, or a message if none found.
+Polaris delivers a suitable message to the named target.
+Polaris searches for submissions to the Reviewer’s observatory, returning a list made of Title, Summary, and Status, or a message if none found.
+Polaris reviews the current user’s proposals - see business rule Submitting a proposal - and adds any that are ready for submission to the search results list with any observatory cycles, else an empty list is returned with a suitable message.
+Polaris searches for the Investigator’s proposals with a status of Submitted, returning a list made of Title, Summary, and Status, or a message if none found.
+ + + + + + + + + + + + + +After tba minutes inactivity, Polaris will warn the user that the session will be terminated in tba minutes if there is no further activity, and terminate the session if there is no response within that time.
+Who will be responsible for providing these services?
+What will be in place in the the event of a system failure?
+Are there guidelines for these?
+Are there guidelines for these?
+Are there guidelines for these?
+Are there guidelines for these?
+Who will be responsible for compliance with The UK GDPR and any local arrangements within Manchester University?
+How will users be trained?
+Creates 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.
+Polaris will import proposals in the approved Polaris Exchange Format from any external system
+Polaris will export proposals to any external system in the approved Polaris Exchange Format
+Here are the usage estimates for the expected lifetime of the PST
+discrete users : in 1000s
+concurrent users : in 10s (near submission time)
+proposals and rate of creation : proposals in 1000s and maybe 100s per day (near submission time)
+investigators per proposal : 1-10
+observations per proposal : typically only a few if single target - however could be 1000s for surveys
+spectral and timing windows per target per proposal : a few
+document numbers and volume per proposal : < 10 (documents are intended to be images to be included in the justifications)
+required equipment per proposal :
+observatories and organisations taking part : perhaps 10
+TACs per observatory : typically only one
+equipment and its spectral windows, arrays, and configurations per observatory :
+submitted proposals per observatory per cycle : 10s - 1000s
+allocated proposals per observatory per cycle :10s-100s
+AAI grants access to Polaris to prospective users. We would like it to verify their email address and membership of a recognised academic institution before doing so.
+Polaris does not have access to observatory schedules, so revoking an allocation will be a decision made by the TAC who does, but the decision will be captured in Polaris
+ + + + + + + + + + + + + +Provide an online web application available over the Internet for astronomers to create observing proposals and submit them to participating observatories. Each observatory’s Time Allocation Committee (TAC) will nominate technical and scientific reviewers to consider each submitted proposal. A review scoring system will determine whether or not the TAC allocate observing time to a submitted proposal.
+The application will be known as the Polaris Proposal Submission Tool (Polaris).
+Polaris will be used for the following activities:-
+Participating observatories publish their future observing cycles, typically of six months duration. Each observatory maintains an inventory of available resources.
+Astronomers create, maintain, and submit observing proposals for one of those cycles. They may submit their proposals to more than one observatory and may also create another proposal from an existing one, submitting it after editing.
+TAC nominated reviewers discover and read astronomers’ submitted proposals and assign to them a score which will determine whether or not observing time is allocated. The final decision regarding observing time allocation rests with the TAC. In the event of an observing cycle being oversubscribed, the TAC may revoke any allocation.
+The desired outcomes are that astronomers are able to make their observations using their nominated observatory’s resources, and that the observatory's resources are used effectively.
+| Stakeholder | +Description | +
|---|---|
| Administrator | +Enables efficient use of facilities and resources | +
| Astronomer | +Applies to use observatory resources to conduct scientific experiments | +
| Reviewer | +Considers submitted observing proposals as directed by the TAC | +
| Time Allocation Committee (TAC) | +Considers submitted observing proposal reviews and determines whether or not to award observing time to them | +
| Topic | +MoSCoW | +
|---|---|
| Allocate time for a submitted proposal | +Must - NB Polaris captures this decision but does not have access to the observatory schedules in order to make it | +
| Assign roles to users | +Must | +
| Automate scheduling of proposals | +Won’t – it does provide the input data for a scheduling tool however. | +
| Capture observatory details, eg location, equipment, availability, observing cycles, etc | +Must | +
| Capture state of a completed proposal | +Could | +
| Capture published state of a completed proposal | +Won't - there are complicated rules around publication accessibility | +
| Capture system details, eg users and roles | +Must | +
| Clone a proposal | +Must | +
| Communicate with users | +Should | +
| Create a proposal | +Must | +
| Download a document | +Must | +
| Edit a proposal | +Must | +
| Export a proposal | +Must | +
| Import a proposal | +Must | +
| Open a stored document | +Must | +
| Reject a submitted proposal | +Must | +
| Review a submitted proposal | +Must | +
| Revoke an allocation | +Must - NB Polaris captures this decision but does not have access to the observatory schedules in order to make it | +
| Score a submitted proposal | +Must | +
| Search for and view a proposal | +Must | +
| Submit a proposal | +Must | +
| Upload a document | +Must | +
| Withdraw a submitted proposal | +Should | +
The underlying proposal data model is defined in a separate project.
+ + + + + + + + + + + + + +A swagger Ui for the deployed api is available at https://kilburn.jb.man.ac.uk/pst/api/q/swagger-ui/
+ + + + + + + + + + + + + +The proposal tool uses the Proposal Data Model as +its native storage format. The Proposal Data Model is developed in parallel as it is +intended also to be a stand-alone interchange format that can be used to share proposals between different systems.
+The proposal tool is designed as a microservices based architecture +that can run on kubernetes clusters.
+
requirements
+Need to clone the following projects in sibling directories
+git clone git@github.com:orppst/build-logic.git
+git clone git@github.com:orppst/pst-lib.git
+git clone git@github.com:orppst/pst-api-service.git
+git clone git@github.com/orppst/pst-gui.git
+The following are the actors and high level use cases for the proposal tool.
+
The following use cases occur in rough chronological order of configuring and using the Proposal tool.
+In deploying the system a special user that is the system administrator is created - this user's authentication is managed locally +rather than using the AAI and has full access to the system.
+All other users should go through the AAI mechanisms on initial creation
+the system administrator configures initial supported observatory object(s) and assigns an already registered user (or users) +to be the observatory administrators
+observatory administrators have the permission to be able to more fully configure observatories - e.g. add telescopes and instruments
+the observatory administrators can assign someone to be the time allocation committee chair for the observatory
+The TAC Chair can add existing users to the TAC
+The TAC chair would then create Proposal Cycle
+A PI will create an observing proposal and invite CO-Is
+the proposal could be imported in the approved Polaris Document Exchange Format
+PI clones one of their proposals to act as a seed for a new proposal
+PIs and CO-Is can edit an observing proposal
+When the proposal is complete the PI can formally submit the proposal
+PI withdraws a previously submitted proposal
+TAC Chair assigns a reviewer from their observatory, who must be a registered Polaris user
+TAC Chair assigns a reviewer from outside their observatory, but reviewer must be a registered Polaris user
+The proposals can be distributed to the TAC - this might
+the proposal could be exported in several forms, eg, PDF, approved Polaris Document Exchange Format
+There might be a scoring system that allows people outside the TAC to score as well. See the external reviewer.
+TAC members review the scores assigned by reviewers
+The TAC assigns observing time to the highest scoring proposals
+possibly automated email
+TAC Chair revokes a previously allocated proposal, possibly because cycle schedule has become over-subscribed
+ + + + + + + + + + + + + + + + +Functions available to observatory administrators
+ + + + + + + + + + + + + +A fresh proposal will have no Targets added, and you will be presented with the following page:
+
To add a Target click the Add + button, which will bring up the New Target form.
+
In the screenshot you will see we have added the Aladin Lite Sky Atlas, +and we have found the Crab Nebula using the Lookup function. This fills in the corresponding +positional and coordinate system data for the named target, and displays the target in the Sky Atlas. +Notice that the backend uses Simbad to search for the named target, such that the name must +exist in their databases to be successful; an appropriate error notification is displayed if the +named target cannot be found.
+You may also simply click anywhere on the Sky Atlas and the corresponding positional details will be +updated in the RA and DEC fields (notice that these are currently displayed as degrees only, we have +development plans to add HH:MM:SS format and to allow you to select between the units with which you +are most comfortable).
+You can also manually fill in the fields, the Sky Atlas will automatically change the view to those +coordinates. Notice that in this alpha version of Polaris, you can have any coordinate system you like, +so long as it's J2000.
+You may also change the name of the target after you have looked it up and before you save it as a +Target. To save, click the Save button. This will return you to the Targets tab of your proposal +now displaying the Target you just saved, and any other targets you may have added.
+
Please notice that the Reference System should read ICRS but due to some bug that has yet to be +squished it reads unknown; did I mention this was the alpha version?
+You may Delete this target if you so wish, just remember that you need at least one target in order +to build an Observation for your proposal.
+If you haven't already added a Technical Goal then please follow the guide here. +If you have now added at least one Target and one Technical Goal to your proposal then please +follow the link to Building Observations.
+ + + + + + + + + + + + + +A fresh proposal will have no Technical Goals and you will be presented with the following page:
+
To add a Technical Goal click the Add + button, which will bring up the New Technical Goal form.
+
In the screenshot you can see we have filled out the Performance Parameters with some values and their +corresponding units; the values in the screenshot are contrived for this guide. The units are selected via a +drop-down menu. These values are what you would like the observation to achieve, and are not necessarily strict +requirements. Further explanation of each field can be found here (to-do). The Performance Parameters +are the minimum amount of information required to Save (screenshot reads Submit because alpha version) a +Technical Goal. For now, we ignore the Spectral Window aspect of a Technical Goal, to be revisited later.
+After clicking Save you will be brought back to the technical goals summary page, which should now display your +newly added Technical Goal.
+
Unlike Targets, you can also Edit and Copy Technical Goals as well as Delete them. This allows you +to change the attributes of an existing Technical Goal, or quickly add other Technical Goals that may have +similar Performance Parameters and/or Spectral Windows without having to re-input all the data.
+If you haven't already added a Target then please follow the guide here. +If you have now added at least one Target and one Technical Goal to your proposal then please follow the +link to Building Observations.
+ + + + + + + + + + + + + + + + +After adding at least one Target and at least one Technical Goal you will see the following summary page +for Observations, which will be empty.
+
To build an Observation click the Add + button, which will bring up the new observation form.
+
In this screenshot we have already selected our Target, the "crab", and our Technical Goal, and have +selected the Observation Type as Calibration and the Calibration intended use as Pointing. Notice that +the Observation Type is a choice between Target and Calibration, and if you select Target there is no +"intended use" field; the Target is the intention of the Observation. For a Calibration Observation +there are several "intended use" options to pick from; see the documentation (to-do) for details.
+Selecting the Target, Technical Goal, and Observation Type is the minimum amount of information to Save +an Observation to the database. However, for the Proposal to pass the server side validation before +submission, all Observations in the Proposal must have at least one Timing Window.
+A Timing Window is a timing constraint on the Observation, and consists of start and end times that +can be specified up to the minutes unit, an avoid toggle switch that changes the meaning of the window, to be +explained presently, and an optional note to provide additional information if required. Typically, a +Timing Window will specify the range of times when the Observation should be performed i.e., the avoid +toggle is unset. However, with the avoid toggle set the window then specifies the range of times when the +Observation should not be performed.
+You can add as many Timing Windows to an Observation as required by your needs. Please note that the +start time must be at an earlier time than the end time, but that different Timing Windows may overlap. +In this case, it is recommended to write optional notes to provide context for anyone reviewing your proposal. +Notice that we assume all times are entered as UTC.
+With all that information entered, click Save to save the Observation to your Proposal. This will +bring you back to the Observations summary page, that will now contain your newly built Observation.
+
As with Technical Goals you may Edit and Copy Observations to avoid having to repeat data entry for +Observations that have similar attributes. For example, using the same Target but for different types, +Target or Calibration, of Observation with perhaps the same Technical Goal and/or timing constraints.
+With an Observation now built both the Target and the Technical Goal to which is refers have their +Delete button disabled. This prevents you from deleting either of these things while they are actively pointed +to by an Observation. In order to re-enable the Delete button on Targets and Technical Goals you +must first delete all Observations that refer to them.
+In this alpha version of Polaris, once you have an Observation with at least one Timing Window in your +Proposal it will pass server side validation checks, and you may submit it for review. In subsequent versions, +you will also have to provide both Scientific and Technical Justifications to pass validation checks, and +it is likely more things will be added to the validation check in the future.
+To see how to submit your proposal for review please follow the guide at +Submitting Proposals
+ + + + + + + + + + + + + +If you haven't registered with and logged-in to Polaris please do so now.
+
This will bring up the new Proposal details form.
+
The basic details of an Observing Proposal are the title, a brief summary, and the Kind of your proposal +either STANDARD, SURVEY, or T.O.O. (target-of-opportunity). These attributes can be changed after you create +the proposal.
+Now that you have a created a new proposal you can see its Overview by clicking the dropdown +menu for the relevant proposal in the navigation pane on the left, and clicking on the Overview +tab.
+
In the screenshot example we have given our proposal the title An awesome proposal title, filled +in the summary with a very brief summary (literally), and assigned it a Kind of STANDARD. Notice +that, as the creator of the new proposal, you will have been automatically assigned the PI, or +Principal Investigator, role for the proposal (in the example we used for the screenshots, the +username is also PI; nobody said we had to be inventive).
+If you now try to go to the Observations tab you will be presented with the following page:
+
In the Polaris app you must first add at least one observational Target and at least one Technical +Goal before you can generate an Observation for your proposal. Notice that the yellow text in the +screenshot is a link to take you to the corresponding page in the App.
+For the next steps in this guide, please follow either the Adding Targets link or the Adding Technical Goals +link, the order here does not matter. The Building Observations page assumes you have added at least one target +and at least one technical goal to your proposal.
+ + + + + + + + + + + + + +Please be aware that the submission functionality of Polaris is under active development such that this page +may very well be out-of-date. Please bear with us while we get around to updating this page.
+Last updated 2024-03-06 Polaris alpha version.
+Once you are happy with the details of your Proposal, and it has passed the server side validation checks +you may submit it for review.
+
You will have to select the Proposal Cycle from the drop-down menu to which you wish to submit your Proposal. +Once selected the page will display the submission deadline for that cycle.
+Server side validation checks currently include:
+As we develop the server side validation checks this list will grow. For example, we'd expect that a Proposal +must have a Scientific Justification and a Technical Justification to be valid for review. Indeed, we +expect this list to expand significantly as we put Polaris in to beta-testing.
+If a Proposal doesn't pass the validation checks then you will be presented with the following page for the +Submit tab of your proposal, which lists the problems.
+
Here we have created another proposal but haven't added any Targets, Technical Goals, or Observations.
+ + + + + + + + + + + + + +Observers will mostly interact with Polaris via the web based GUI
+There is also a Front end CLI under development which will offer a way of manipulating proposals via scripting.
+ + + + + + + + + + + + + +Planned Delivery dates
+Phase 1 :
+Phase 2 :
+Phase 3 :
+| Epic | +Story | +Phase 1 | +Phase 2 | +Phase 3 | +
|---|---|---|---|---|
| Manage Reference Data | +UC02 Create observatory admin | +Phase 1 | ++ | + |
| + | UC03 Configure observatory | +Phase 1 | ++ | + |
| + | UC 04 Create new proposal cycle | +Phase 1 | ++ | + |
| + | UC08 Create TAC Chair | ++ | Phase 2 | ++ |
| + | UC09 Add TAC members | ++ | Phase 2 | ++ |
| + | UC16 Assign internal reviewer | ++ | Phase 2 | ++ |
| + | UC17 Assign external reviewer | ++ | Phase 2 | ++ |
| + | + | + | + | + |
| Deploy System | +UC00 Deploy the system | +Phase 1 | ++ | + |
| + | UC01 User registers to the system | +Phase 1 | ++ | + |
| + | + | + | + | + |
| Assemble Proposal | +UC05 Create observing proposal | +Phase 1 | ++ | + |
| + | UC06 Edit observing proposal | +Phase 1 | ++ | + |
| + | UC07 Submit a proposal | +Phase 1 | ++ | + |
| + | UC15 Import whole proposal | ++ | Phase 2 | ++ |
| + | UC20 Clone proposal | ++ | Phase 2 | ++ |
| + | UC21 Withdraw proposal | ++ | + | Phase 3 | +
| + | + | + | + | + |
| Consider Proposal | +UC10 Review proposals | ++ | Phase 2 | ++ |
| + | UC11 Score proposals | ++ | Phase 2 | ++ |
| + | UC12 Assign observing time | ++ | Phase 2 | ++ |
| + | UC13 Inform PIs about allocation | ++ | + | Phase 3 | +
| + | UC18 Review proposal scores | ++ | Phase 2 | ++ |
| + | UC22 Revoke allocation | ++ | + | Phase 3 | +
| + | + | + | + | + |
| Common | +UC14 Export whole proposal | ++ | Phase 2 | ++ |
| + | + | + | + | + |
| Manage Hardware | +Procure, configure, and deliver Dev application servers,with agreed standby | +Phase 1 | ++ | + |
| + | Procure, configure, and deliver Stage and Production application servers, with agreed standby | ++ | Phase 2 | ++ |
| + | + | + | + | + |
| Manage DBMS | +Procure, configure, and deliver Dev database servers, with agreed standby | +Phase 1 | ++ | + |
| + | Procure, configure, and deliver Stage and Production database servers, with agreed standby | ++ | Phase 2 | ++ |
| + | Implement database security | +Phase 1 | ++ | + |
| + | Implement agreed data backup strategy | +Phase 1 | ++ | + |
| + | + | + | + | + |
| Statistics | +Monitor Production system usage | ++ | + | Phase 3 | +
This project follows Prince2 best practices at least in terms of there being somebody who is Directing, somebody who is Managing, and somebody who is Delivering. +This document describes the aims of the project, how it will be managed, designed, built, tested, deployed, maintained, used, and not least, secured. +Application and data security, including user privacy, will be overseen by an acknowledged security expert with particular regard for the provisions of data protection within the UK (GDPR).
+More than one role can be filled by the same person.
+| Role | +Responsibility | +Name | +
|---|---|---|
| Programme Manager | +Appoint board | ++ |
| Role | +Responsibility | +Name | +
|---|---|---|
| Executive | +Appoint team | ++ |
| Senior Users | +Define requirements | ++ |
| Senior Suppliers | +Provide resources | ++ |
| Role | +Responsibility | +Name | +
|---|---|---|
| Assurance | +Assure stakeholder interests | ++ |
| Change Authority | +Manage unplanned change | ++ |
| Project Manager | +Manage project plan and day-to-day running | ++ |
| Team Manager | +Fulfil needs of project plan | ++ |
| Support | +General admin | ++ |
| Role | +Responsibility | +Name | +
|---|---|---|
| Security Manager | +Manage project and product security, including project and user data | ++ |
See here
+See here
+See here
+See here
+See here
+See here
+See here
+The proposal submission tool previously serving this purpose no longer works, and cannot be fixed.
+See here
+See here
+Project meetings will be held every Monday afternoon, and as necessary.
+See here
+This log identifies any impacts on the project in the form of risks, assumptions, issues and dependencies. A risk may happen and needs to be planned for, an issue has happened and needs to be dealt with. Assumptions need to be verified to determine whether or not they constitute a risk. Dependencies, particularly external ones (either outgoing or incoming) may constitute a risk. A RAID template is provided with this documentation.
+For any particular task the RACI matrix defines which role is Responsible, Accountable, Consulted or Informed in relation to that task. A RACI template is provided with this documentation.
+ + + + + + + + + + + + + +Functions available to the Time Allocation Committee (TAC)
+ + + + + + + + + + + + + +