Skip to content

Commit

Permalink
Merge pull request #15 from orppst/MWA0624B
Browse files Browse the repository at this point in the history 
adding  some project documentation
  • Loading branch information
@pahjbo
pahjbo authored Jun 25, 2024
2 parents 18a64d4 + 4421066 commit 8570dcf
Show file tree
Hide file tree
Showing 9 changed files with 812 additions and 1 deletion.
13 changes: 13 additions & 0 deletions docs/Design/Approach.md
View file
Original file line number Diff line number Diff line change
@@ -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.
375 changes: 375 additions & 0 deletions docs/Design/BusinessRequirements.md
View file

Large diffs are not rendered by default.

112 changes: 112 additions & 0 deletions docs/Design/BusinessRules.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# ***Business rules***


### *Creating a proposal*

<ul><li>
A proposal cannot be saved unless both the Title and the Summary are not empty.
</li></ul>

### *Document exchange format*

<ul><li>A proposal must be Exported in both PDF format and the approved Polaris Exchange Format (defined elsewhere)</li></ul>
<ul><li>An Imported proposal created in an external system must be presented in the approved Polaris Exchange Format</li></ul>

### *Editing a proposal*

<ul><li>
A proposal cannot be edited or deleted by anyone other than its investigators.
</li><li>A proposal with a status other than Created cannot be edited or deleted by anybody.
</li><li>Only an Investigator can upload a document to a proposal
</li></ul>


### *Home page features*

<ul><li>
Polaris must not offer the Maintain Polaris observatory reference data option to any user who does not have an Observatory Administrator role, apart from a System Administrator who must create the initial Observatory record and assign an Observatory Administrator to it.
</li><li>Polaris must not offer the Maintain Polaris system reference data option to any user who does not have a System Administrator role.
</li></ul>

### *Observations*

<ul><li>A proposal has one or more observations</li>
<li>An observations has one target</li>
<li>A target has one set of technical goals, one or many timing windows, and zero, one or many constraints, and must be identified as either Observation or Calibration</li>
<li>A set of technical goals consists of one set of performance parameters and one or more spectral windows</li></ul>

### *Proposal cycle*

<ul><li>
Start date must be later than submission deadline, end date must be later than start date.
</li></ul>

### *Proposal status*

A proposal is assigned one of the following depending on its current state.

<ul>
<li>Allocated: A proposal has been allocated observing time by the TAC
</li><li>Completed: A proposal's observations have all been made
</li><li>Created: A new proposal is being prepared for submission
</li><li>Rejected: A proposal has been rejected by the TAC
</li><li>Revoked: A proposal allocation has been revoked by the TAC
</li><li>Scored: A proposal has been assigned a score by the TAC
</li><li>Submitted: A proposal has been submitted
</li><li>Withdrawn: A submitted or allocated proposal has been withdrawn by the Principal Investigator
</li></ul>

### *Reference data*

<ul><li>
Reference data records (People, Organizations, etc) must not be deleted, they must simply be marked as Discontinued.
</li><li>Administrators must never be deleted, they must simply be marked as Discontinued.
</li><li>Do not display discontinued records when offering a selection.
</li><li>Only Administrators can add or change reference data
</li></ul>


### *Reviewing a proposal*

<ul><li>
A proposal cannot be reviewed by any Polaris-user who is not a nominated Reviewer for the proposal’s chosen observatory.
</li><li>A proposal cannot be reviewed by a TAC member who is also an investigator on the Proposal
</li><li>Investigators’ names must not be displayed to a Reviewer
</li><li>Reviewers’ names must not be displayed to an Investigator
</li></ul>


### *Revoking an allocation*

<ul><li>
A proposal with a status other than Allocated cannot be revoked.
</li><li>Nobody other than the TAC Chair can revoke a proposal.
</li></ul>


### *Submitting a proposal*

<ul><li>
A proposal cannot be submitted unless Title, Summary, Justifications, Observations and each of their components (Targets, Technical Goals, Spectral Windows and Timing Windows) all have non-null values.
</li><li>Nobody other than the Principal Investigator can submit a proposal.
</li><li>A proposal with a status other than Created cannot be submitted.
</li><li>A Proposal cannot be submitted to a proposal cycle whose submission deadline is in the past
</li></ul>


### *Viewing a proposal*

<ul>
<li>A proposal cannot be viewed by anyone who is not one of its investigators or reviewers
</li></ul>


### *Withdrawing a proposal*

<ul><li>

Nobody other than the Principal Investigator can withdraw a submitted a proposal.
</li><li>A proposal with a status of Completed cannot be withdrawn.
</li></ul>


39 changes: 39 additions & 0 deletions docs/Design/Components.md
View file
Original file line number Diff line number Diff line change
@@ -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.

90 changes: 90 additions & 0 deletions docs/Design/NFRs.md
View file
Original file line number Diff line number Diff line change
@@ -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
57 changes: 57 additions & 0 deletions docs/Design/PurposeAndScope.md
View file
Original file line number Diff line number Diff line change
@@ -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 |


Loading

0 comments on commit 8570dcf

Please sign in to comment.