add documentation

docs/entity_relationship_diagram.md

@@ -0,0 +1,54 @@
+# PERS Database Entity Relationship Diagram 
+
+The Publication Email Request Service (PERS) relies on a database to keep track of the email requests that have been sent by stakeholders. Monitoring the email requests via database prevents duplication of email requests. The diagram describes the relationships between entities, or tables, in the database.
+
+The entities involved in PERS are as follows:
+
+* `DLC`: Represents a department, lab, or center at MIT and is managed by a single **liaison**. A **DLC** can comprise of many **authors**, but an author is assigned to a single **DLC**.
+* `Liaison`: Represents a DLS staff member on MIT's Scholarly Communications team. **Liaisons** are assigned to one or more **DLCs**. **Liaisons** receive the email requests generated by PERS, who then send the email to authors in their assigned DLCs.
+* `Author`: Represents MIT student and faculty who are registered on Symplectic Elements. An **author** is assigned to a single **DLC**. When citations are imported for an author, zero or more **Publications** may be found that require submission.
+* `Publications`: Represents a publication written by one or more **Authors**.
+* `Email`: Represents an email request for a publication. Many **publications** may be associated with a single **email**. The email generated by PERS will contain a list of citations for publications that need submission. 
+
+   **Note:** According to Solenoid documentation, authors on a single publication will receive **at most one (1)** email for a publication. However, (TO BE CONFIRMED) this is only if, when they're data is imported, the publication appears as not having been requested yet (via a second author that was previously imported through PERS).
+
+```mermaid
+erDiagram
+    publication["Publication (needing request)"]{
+        string publication_id PK 
+        string author_id PK
+        string title
+        string citation
+        string email_id FK
+    }
+    dlc[DLC]{
+        string id PK
+        string name
+    }
+    liaison[Liaison]{
+        string id PK
+        string first_name
+        string last_name
+        string email_address
+        bool active
+    }
+    author[Author]{
+        string id PK
+        string dlc FK
+        string email_address
+        string first_name
+        string last_name
+    }
+    email[Email]{
+        string id PK
+        richtext original_text
+        richtext latest_text
+        date date_sent
+    }
+    liaison |o--o{ dlc: "belongs to"
+    dlc ||--o{ author: has
+    author }|--o{ publication: has
+    publication }o--|| email: "included in"
+    author ||--o{ email: receives
+    liaison ||--o{ email: receives
+```

docs/publication_email_requests.md

@@ -0,0 +1,127 @@
+# Publication Email Request Service (PERS)
+
+The following are sequence diagrams describing the workflow for sending publication email requests with this service. At high-level the steps involved are:
+
+1. Import citations for authors
+2. Create publication email requests
+3. Review and (optionally) update emails
+4. Send emails to Liaisons
+
+## Import citations for authors 
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant user as User
+    participant pers as Publication Email Request Service <br> (PERS)
+    participant elements as Symplectic Elements
+    participant pers_db as PERS Database
+    user ->> pers: Select option to import citations
+    pers ->> user: Request user input for author's Element's ID
+    user -->> pers: Respond with selected author's Element's ID
+    pers ->> elements: Send GET request to Elements API <br>to retrieve author data <br> "<ELEMENTS_ENDPOINT>users/{author_id}
+    elements -->> pers: Author data XML string <br> ("Email", "First Name", "Last Name", "MIT ID", "DLC", "Start Date", "End Date")
+    pers ->> pers: Parse XML string to AuthorRecord
+    pers ->> pers_db: Upsert record to 'Author' table
+    pers ->> elements: Send GET request to Elements API <br> to retrieve author's publications <br> <ELEMENTS_ENDPOINT>users/{author_id}/publications?&detail=full
+    elements -->> pers: Author publications XML string
+    pers ->> pers: Parse XML string to list of key-value pairs <br> for *qualifying* publications <br>(publication IDs and titles)
+
+    Note over pers, elements: As PERS parses through the author publications XML string, <br> it runs a series of preliminary checks to determine if the publication meets the criteria <br> for an email request. If checks pass, the publication is added to a list.
+
+    loop For every publication
+        pers ->> elements: Send GET request to Elements API <br> to retrieve publication data <br> <ELEMENTS_ENDPOINT>publications/{publication_id}
+        elements -->> pers: Publication citation data XML string
+        pers ->> pers: Parse XML string to PublicationRecord
+        pers -->> pers: Run checks on publication <br> 1.PublicationRecord is citable <br> 2. PublicationRecord has required identifiers <br> (MIT ID, Publication ID)
+        pers ->> pers_db: Check if any records in the 'Email' table linked to the publication have been sent <br> (i.e., `PublicationRecord.id in Email.publications and Email.date_sent is not None`)
+        pers ->> pers_db: Check if a record exists in the 'Publication' table where `Publication.id = PublicationRecord.id`.
+        pers ->> pers_db: Upsert record to the 'Publication' table    
+    end
+```
+
+## Create publication email requests
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant user as User
+    participant pers as Publication Email Request Service <br> (PERS)
+    participant elements as Symplectic Elements
+    participant pers_db as PERS Database
+
+    user ->> pers: Select from list of unsent citations <br> (records from 'Publications' table)
+    loop For all authors linked to the selected publications
+        pers ->> pers_db: Get records from the 'Publication' table where `Publication.id in selected list AND Publication.author = author.id`
+        pers ->> pers_db: Get records from the 'Publication' table where `Publication.email.date_sent = Null`.
+        pers_db -->> pers: Unsent record(s) from 'Publication' table
+        pers ->> pers_db: Get the author from the unsent records
+        pers_db -->> pers: Record from 'Author' table
+        pers ->> pers_db: Get records from 'Email' table where `Email.author = author AND Email.date_sent = Null"
+        pers_db -->> pers: Record(s) from 'Email' table
+        break if author has more than one (>1) unsent email
+            pers ->> user: Raise error
+        end
+
+        alt single (1) unsent email exists for author
+            pers ->> pers: Rebuild citations list in email
+            pers ->> pers_db: Update record in 'Email' table
+        else no (0) unsent email exists for author 
+            pers ->> pers: Create email for author
+            pers ->> pers_db: Add record to 'Email' table
+        end
+    end
+```
+
+## Review and (optionally) update emails
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant user as User
+    participant pers as Publication Email Request Service <br> (PERS)
+    participant pers_db as PERS Database
+
+    user ->> pers: Select option to evaluate emails
+    pers ->> pers_db: Get records from 'Email' table <br> (`Email.date_sent = NULL`)
+    pers_db -->> pers: Pending emails
+    pers -->> user: List of unsent emails
+
+    user ->> pers: Select pending email to review
+    pers -->> user: Display text editor with content of pending email
+    alt User updates content of pending email
+        pers ->> pers_db: Update 'latest_text' field of record in 'Email' table
+    end
+```
+
+## Send emails to Liaisons
+
+```mermaid
+sequenceDiagram
+    autonumber
+    autonumber
+    participant user as User
+    participant liaison as Liaison
+    participant pers_admins as PERS Admins
+    participant pers as Publication Email Request Service <br> (PERS)
+    participant pers_db as PERS Database
+
+    user ->> pers: Select option to list unsent email requests
+    pers ->> pers_db: Get records from 'Email' table <br> where `Email.date_sent = NULL`)
+    pers -->> user: Display list of drafted email requests
+    user ->> pers: Select email requests to send <br> (mark checkbox next to email request in list)
+
+    loop For every selected email
+        pers ->> pers_db: Get record from 'Email' table <br> where `Email.id = ID of selected email`
+        pers_db -->> pers: Record from 'Email' table
+        pers ->> pers: Run checks on email <br> 1. Email.date_sent is NULL (not sent) <br> 2. Email.liaison is NOT NULL (assigned)
+
+        alt if EMAIL_TESTING_MODE
+            pers ->> pers_admins: Send email request
+        else
+            pers ->> liaison: Send email request <br> (cc Scholarly Communications Moira List)
+        end
+        pers ->> pers_db: Update record in 'Email' table <br> (Email.date_sent = current date [YYYY-MM-DD])
+    end
+```
+