From bf7b0d74b999c5b314e752e85ef9f817067d7996 Mon Sep 17 00:00:00 2001
From: jonavellecuerdo <cuerdojonavelle@gmail.com>
Date: Fri, 26 Apr 2024 15:42:12 -0400
Subject: [PATCH] Create sequence diagram describing PERS workflow

---
 docs/publication_email_requests.md | 41 ++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 docs/publication_email_requests.md

diff --git a/docs/publication_email_requests.md b/docs/publication_email_requests.md
new file mode 100644
index 0000000..94da6aa
--- /dev/null
+++ b/docs/publication_email_requests.md
@@ -0,0 +1,41 @@
+# 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 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 'Publication' where `Publication.id == PublicationRecord.id`.
+        pers ->> pers_db: Upsert record to 'Publication' table    
+    end
+```
\ No newline at end of file