diff --git a/docs/Design/Approach.md b/docs/Design/Approach.md new file mode 100755 index 0000000..819be60 --- /dev/null +++ b/docs/Design/Approach.md @@ -0,0 +1,13 @@ + +# ***Approach*** +These business requirements are documented following Alistair Cockburn’s recommendations in Writing Effective Use Cases, Addison-Wesley, 2001. +## Key points +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 [***here***](https://github.com/ivoa/ProposalDM). + +The UI is documented elsewhere. \ No newline at end of file diff --git a/docs/Design/BusinessRequirements.md b/docs/Design/BusinessRequirements.md new file mode 100755 index 0000000..6ed00f3 --- /dev/null +++ b/docs/Design/BusinessRequirements.md @@ -0,0 +1,375 @@ + + +# ***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***](NFRs.md#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***](https://github.com/ivoa/ProposalDM) + +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***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#viewing-a-proposal), [***Editing a proposal***](BusinessRules.md#editing-a-proposal), and [***Document exchange format***](BusinessRules.md#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***](BusinessRules.md#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***](Components.md#verify-submission) and [***Discover cycles***](Components.md#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***](Components.md#audit-activity), executes [***Informs***](Components.md#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***](BusinessRules.md#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***](Components.md#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***](Components.md#audit-activity), and executes [***Informs***](Components.md#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***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#reviewing-a-proposal) and [***Document exchange format***](BusinessRules.md#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***](Components.md#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***](Components.md#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***](BusinessRules.md#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***](Components.md#audit-activity), and [***Informs***](Components.md#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***](BusinessRules.md#creating-a-proposal), [***Viewing a proposal***](BusinessRules.md#viewing-a-proposal), and [***Editing a proposal***](BusinessRules.md#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***](Components.md#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***](Components.md#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***](BusinessRules.md#creating-a-proposal), [***Viewing a proposal***](BusinessRules.md#viewing-a-proposal) and [***Editing a proposal***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#creating-a-proposal), [***Viewing a proposal***](BusinessRules.md#viewing-a-proposal) and [***Editing a proposal***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#creating-a-proposal), [***Viewing a proposal***](BusinessRules.md#viewing-a-proposal), [***Editing a proposal***](BusinessRules.md#editing-a-proposal), and [***Observations***](BusinessRules.md#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***](Components.md#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***](BusinessRules.md#creating-a-proposal), [***Viewing a proposal***](BusinessRules.md#viewing-a-proposal) and [***Editing a proposal***](BusinessRules.md#editing-a-proposal) + +See [***Maintain observations***](#maintain-observations) + +### *Maintain title and summary* + +This provides the means to create, view, and edit a proposal but see business rules [***Creating a proposal***](BusinessRules.md#creating-a-proposal), [***Viewing a proposal***](BusinessRules.md#viewing-a-proposal) and [***Editing a proposal***](BusinessRules.md#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***](Components.md#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 | | + + + + + + + + + + + diff --git a/docs/Design/BusinessRules.md b/docs/Design/BusinessRules.md new file mode 100644 index 0000000..efe55df --- /dev/null +++ b/docs/Design/BusinessRules.md @@ -0,0 +1,112 @@ +# ***Business rules*** + + +### *Creating a proposal* + + + +### *Document exchange format* + + + + +### *Editing a proposal* + + + + +### *Home page features* + + + +### *Observations* + + + +### *Proposal cycle* + + + +### *Proposal status* + +A proposal is assigned one of the following depending on its current state. + + + +### *Reference data* + + + + +### *Reviewing a proposal* + + + + +### *Revoking an allocation* + + + + +### *Submitting a proposal* + + + + +### *Viewing a proposal* + + + + +### *Withdrawing a proposal* + + + + diff --git a/docs/Design/Components.md b/docs/Design/Components.md new file mode 100644 index 0000000..7ef382e --- /dev/null +++ b/docs/Design/Components.md @@ -0,0 +1,39 @@ + +# ***Components*** + +### *Assigns PI* + +Polaris assigns the current user as PI for the created proposal + +### *Assigns Reviewer* + +Polaris assigns the current user as Reviewer for the submitted proposal + +### *Audit activity* + +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 + +### *Discover cycles* + +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. + +### *Informs* + +Polaris delivers a suitable message to the named target. + + +### *Reviewer search* + +Polaris searches for submissions to the Reviewer’s observatory, returning a list made of Title, Summary, and Status, or a message if none found. + +### *Verify Submission* + +Polaris reviews the current user’s proposals - see business rule [***Submitting a proposal***](BusinessRules.md#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. + + +### *Withdrawal search* + +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. + diff --git a/docs/Design/NFRs.md b/docs/Design/NFRs.md new file mode 100755 index 0000000..45835cc --- /dev/null +++ b/docs/Design/NFRs.md @@ -0,0 +1,90 @@ +# ***Non-functional requirements*** + +## *Inactivity* + +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. + +## *Operations, Security and Deployment* + +Who will be responsible for providing these services? + +## *Response to System Failure* + +What will be in place in the the event of a system failure? + +## *Use and Accessibility* + +Are there guidelines for these? + +## *Performance and Availability* + +Are there guidelines for these? + +## *Maintenance and Portability* + +Are there guidelines for these? + +## *Extensibility and Scalability* + +Are there guidelines for these? + +## *Legal* + +Who will be responsible for compliance with The UK GDPR and any local arrangements within Manchester University? + +## *Training and Documentation* + +How will users be trained? + +## *Assumptions and Dependencies* + +### *AAI system* + +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. + + +## *Interfaces to other systems* + +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 + +## *Volumes* + + +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 + + +## *Dependencies* + +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 diff --git a/docs/Design/PurposeAndScope.md b/docs/Design/PurposeAndScope.md new file mode 100755 index 0000000..2c8bf18 --- /dev/null +++ b/docs/Design/PurposeAndScope.md @@ -0,0 +1,57 @@ + +# ***Purpose and scope*** + +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). + +## **Overall scope and goals** + +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. + +## **Stakeholders** + +| 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 | + +## **Scope** + +| 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 | + + diff --git a/docs/Project Management/ProjectManagement.md b/docs/Project Management/ProjectManagement.md new file mode 100644 index 0000000..04b2211 --- /dev/null +++ b/docs/Project Management/ProjectManagement.md @@ -0,0 +1,97 @@ +# ***Introduction*** + +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). + +## **Management** + +More than one role can be filled by the same person. + +## *Programme Management* + +| Role | Responsibility | Name | +|-------------------|----------------|------| +| Programme Manager | Appoint board | | + +## *Project Board* + +| Role | Responsibility | Name | +|------------------|---------------------|------| +| Executive | Appoint team | | +| Senior Users | Define requirements | | +| Senior Suppliers | Provide resources | + +## *Team Management* + +| 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 | | + +## *Project and Product Security* + +| Role | Responsibility | Name | +|------------------|----------------------------------------------------------------------|------| +| Security Manager | Manage project and product security, including project and user data | | + +## *Project Brief* + +See [***here***](../Design/PurposeAndScope.md) + +## *The Project* + +See [***here***](../Design/PurposeAndScope.md/#overall-scope-and-goals) + +## *Objectives and outcomes* + +See [***here***](../Design/PurposeAndScope.md#overall-scope-and-goals) + +## *Scope and exclusions* + +See [***here***](../Design/PurposeAndScope.md#scope) + +## *Constraints and assumptions* + +See [***here***](../Design/NFRs.md#assumptions-and-dependencies) + +## *Users* + +See [***here***](../Design/BusinessRequirements.md#primary-actors-and-their-goals) + + +## *Interfaces* + +See [***here***](../Design/NFRs.md#interfaces-to-other-systems) + +## *Outline business case* + +The proposal submission tool previously serving this purpose no longer works, and cannot be fixed. + +## *Product description* + +See [***here***](../Design/BusinessRequirements.md#business-use-cases) + +## *Project approach* + +See [***here***](../Design/Approach.md#approach) + +### *Meetings and reports* + +Project meetings will be held every Monday afternoon, and as necessary. + +### *Standards* + +See [***here***](../Design/Approach.md#approach) + +### *RAID Log* + +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. + +### *RACI matrix* + +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. + diff --git a/mkdocs.yml b/mkdocs.yml index 21d2462..f665927 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,16 +26,42 @@ nav: - API: Developer/api.md - Deployment: - Getting Started: Deployment/index.md + # 2024-06-24 mwa design and proj mgt + - Design: + - Approach: Design/Approach.md + - Purpose and Scope: Design/PurposeAndScope.md + - Business Requirements: Design/BusinessRequirements.md + - Business Rules: Design/BusinessRules.md + - Components: Design/Components.md + - Non-functional Requirements: Design/NFRs.md + - Project Management: Project Management/ProjectManagement.md + # 2024-06-24 mwa theme: name: material features: - navigation.instant - navigation.tabs - content.action.edit + - toc.follow # 2024-06-24 mwa logo: assets/logo.svg favicon: assets/icons/polaris_square_icon.png palette: - primary: black +# 2024-06-24 mwa colour scheme +# primary: black + - scheme: default + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + primary: cyan + accent: deep orange + - scheme: slate + toggle: + icon: material/toggle-switch + name: Switch to light mode + primary: amber + accent: lime +# 2024-06-24 mwa + custom_dir: theme_overrides markdown_extensions: diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..1c7bd30 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +mkdocs-material==9.5.25 +plantuml-markdown