Skip to content

Commit f3b39d4

Browse files
lfdebruxstephencdaly
lfdebrux
and
stephencdaly
committed
Update sequence diagrams for sending submission emails
We no longer use GOV.UK Notify to send submission emails, instead we use Amazon SES asynchronously. Our documentation and sequence diagrams need to be updated to reflect this, this commit: - Add Amazon SES to high level architecture diagram - Removes references to GOV.UK Notify from sequence diagram for filling in a form - Moves sequence diagrams related to sending submission emails from file upload file to a new file - Updates details around updating submission record with delivery status and time Co-authored-by: Stephen Daly <stephen.daly@digital.cabinet-office.gov.uk>
1 parent 295fea1 commit f3b39d4

4 files changed

Lines changed: 165 additions & 165 deletions

File tree

‎diagrams/sequence-diagrams/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,15 +38,15 @@ graph TD
3838
filler --- runner --- admin
3939
4040
notify(GOV.UK Notify)
41+
ses(Amazon Simple Email Service)
4142
4243
pay(GOV.UK Pay)
4344
filler -.- pay -.- runner
4445
4546
filler -.- notify
46-
notify --- runner
47-
processor --- notify
48-
49-
47+
notify -.- runner
48+
ses --- runner
49+
processor --- ses
5050
```
5151

5252
## Links to Sequence Diagrams

‎diagrams/sequence-diagrams/file-upload.md‎

Lines changed: 0 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -138,157 +138,3 @@ runner->>browser: HTTP 302 redirect response
138138
139139
note over user,runner: User completes the rest of the questions
140140
```
141-
142-
### User submits their form
143-
```mermaid
144-
145-
---
146-
title: User submits their form
147-
---
148-
149-
sequenceDiagram
150-
151-
autonumber
152-
153-
actor user as User
154-
155-
participant browser as Browser
156-
157-
participant runner as Forms Runner
158-
participant runner-db as Forms Runner database
159-
participant solidqueue-db as Solid Queue database
160-
161-
browser->>runner: GET check your answers
162-
runner->>browser: HTTP 200 response
163-
browser->>user: display check your answers page
164-
165-
user->>browser: select "Submit"
166-
browser->>runner: POST submit form
167-
runner->>runner-db: save Submission
168-
runner->>solidqueue-db: enqueue send submission job
169-
170-
runner->>browser: HTTP 302 response
171-
browser->>runner: GET confirmation page
172-
runner->>browser: HTTP 200 response
173-
browser->>user: Display confirmation page
174-
175-
```
176-
177-
### Sending the submission email asynchronously
178-
179-
```mermaid
180-
181-
---
182-
title: Sending the submission email asynchronously
183-
---
184-
185-
sequenceDiagram
186-
187-
autonumber
188-
189-
participant worker as Forms runner worker
190-
participant solidqueue-db as Solid Queue database
191-
participant runner-db as Forms Runner database
192-
participant s3 as Amazon S3
193-
participant ses as Amazon SES
194-
participant sns as Amazon SNS
195-
participant inbox as Email inbox
196-
participant sentry as Sentry
197-
198-
actor processor
199-
200-
worker->>solidqueue-db: dequeue send submission job
201-
worker->>runner-db: get Submission
202-
worker->>s3: get file(s)
203-
worker->>ses: send email
204-
205-
break error
206-
alt AWS SDK error and max retries not reached
207-
worker->>solidqueue-db: schedule retry
208-
else
209-
worker->>sentry: send error
210-
end
211-
end
212-
213-
ses->>worker: return message_id
214-
worker->>runner-db: set mail_message_id on Submission
215-
worker->>runner-db: update mail_status of Submission to "pending"
216-
217-
ses-)inbox: send email
218-
note over ses,inbox: happens some time later
219-
220-
alt email sent successfully
221-
ses->>sns: send delivery notification
222-
processor->>inbox: get form from inbox
223-
processor->>processor: process form
224-
else email bounces
225-
ses->>sns: send bounce notification
226-
note over ses,sns: We have an SQS queue subscribed to the<br/> SNS topic and a recurring task to poll<br/>the SQS queue.
227-
end
228-
229-
worker->>worker: Recurring task deletes Submissions<br/>that haven't bounced after 7 days
230-
```
231-
232-
### Handling email bounces/complaints
233-
```mermaid
234-
235-
---
236-
title: Handling email bounces/complaints
237-
---
238-
239-
sequenceDiagram
240-
241-
autonumber
242-
243-
participant worker as Solid Queue worker
244-
participant solidqueue-db as Solid Queue database
245-
participant runner-db as Forms Runner database
246-
participant sqs as Amazon SQS
247-
participant sentry as Sentry
248-
249-
actor support as Forms team tech support
250-
251-
worker->>solidqueue-db: enqueue recurring receive bounces job
252-
worker->>solidqueue-db: dequeue receive bounces job
253-
worker->>sqs: get messages from bounces and complaints queue
254-
alt there is a bounce SQS message
255-
worker->>runner-db: get Submission by the message_id in the SQS message
256-
worker->>runner-db: update mail_status of Submission to "bounced"
257-
worker->>worker: Log with the submission details
258-
worker->>sentry: send error event
259-
sentry->>support: Alert via Slack
260-
support->>support: Identify why the email bounced
261-
support->>support: Run rake task to retry submission
262-
else there is a complaint SQS message
263-
worker->>runner-db: get Submission by the message_id in the SQS message
264-
worker->>worker: Log with the submission details
265-
end
266-
267-
```
268-
269-
### Handling successful deliveries
270-
271-
```mermaid
272-
273-
---
274-
title: Handling successful deliveries
275-
---
276-
277-
sequenceDiagram
278-
279-
autonumber
280-
281-
participant worker as Solid Queue worker
282-
participant solidqueue-db as Solid Queue database
283-
participant runner-db as Forms Runner database
284-
participant sqs as Amazon SQS
285-
286-
actor support as Forms team tech support
287-
288-
worker->>solidqueue-db: enqueue recurring receive deliveries job
289-
worker->>solidqueue-db: dequeue receive deliveries job
290-
worker->>sqs: get messages from deliveries queue
291-
worker->>runner-db: get Submission by the message_id in the SQS message
292-
worker->>runner-db: update mail_status of Submission to "delivered"
293-
note over worker,runner-db: we don't currently use the "delivered" status for anything other than for information
294-
```

‎diagrams/sequence-diagrams/filling-in-a-form.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ sequenceDiagram
77
participant govuk as GOV.UK website
88
participant runner as forms-runner
99
participant admin as forms-admin
10-
participant notify as GOV.UK Notify
1110
participant inbox as shared email inbox
1211
actor processor as Form processor
1312
@@ -41,13 +40,13 @@ sequenceDiagram
4140
user->>browser: Click "Submit"
4241
browser->>runner: POST /form/{form id}/{form slug}/submit-answers
4342
runner->>admin: GET /api/v2/forms/{form id}/live
44-
runner->>notify: client.send_email()
45-
runner->>runner: Delete user session
43+
runner->>runner: save Submission
44+
runner->>runner: enqueue send submission job
4645
runner-->>browser: 302
4746
browser->>runner: GET /form/{form id}/{form slug}/submitted
4847
runner->>admin: GET /api/v2/forms/{form id}/live
4948
browser-->>user: Show confirmation page
50-
notify->>inbox: Send email
49+
runner->>inbox: Send email
5150
inbox->>processor: Read email
5251
```
5352

@@ -61,7 +60,6 @@ sequenceDiagram
6160
participant browser as Web Browser
6261
participant runner as forms-runner
6362
participant admin as forms-admin
64-
participant notify as GOV.UK Notify
6563
6664
user->>browser: Click link to form
6765
browser->>runner: GET /form/{form id}/{form slug}
@@ -75,8 +73,6 @@ sequenceDiagram
7573
end
7674
```
7775

78-
79-
8076
## Brief summary
8177

8278
The users answers are store in Redis in the following structure as they progress through the form.

‎diagrams/sequence-diagrams/sending-submission-emails.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Sending submission emails asynchronously
2+
3+
forms-runner uses SolidQueue and Amazon SES/SNS to send submissions asynchronously.
4+
5+
## User submits their form
6+
7+
```mermaid
8+
9+
---
10+
title: User submits their form
11+
---
12+
13+
sequenceDiagram
14+
15+
autonumber
16+
17+
actor user as User
18+
19+
participant browser as Browser
20+
21+
participant runner as Forms Runner
22+
participant runner-db as Forms Runner database
23+
participant solidqueue-db as Solid Queue database
24+
25+
browser->>runner: GET check your answers
26+
runner->>browser: HTTP 200 response
27+
browser->>user: display check your answers page
28+
29+
user->>browser: select "Submit"
30+
browser->>runner: POST submit form
31+
runner->>runner-db: save Submission
32+
runner->>solidqueue-db: enqueue send submission job
33+
34+
runner->>browser: HTTP 302 response
35+
browser->>runner: GET confirmation page
36+
runner->>browser: HTTP 200 response
37+
browser->>user: Display confirmation page
38+
39+
```
40+
41+
## Sending the submission email asynchronously
42+
43+
```mermaid
44+
45+
---
46+
title: Sending the submission email asynchronously
47+
---
48+
49+
sequenceDiagram
50+
51+
autonumber
52+
53+
participant worker as Forms runner worker
54+
participant solidqueue-db as Solid Queue database
55+
participant runner-db as Forms Runner database
56+
participant s3 as Amazon S3
57+
participant ses as Amazon SES
58+
participant sns as Amazon SNS
59+
participant inbox as Email inbox
60+
participant sentry as Sentry
61+
62+
actor processor
63+
64+
worker->>solidqueue-db: dequeue send submission job
65+
worker->>runner-db: get Submission
66+
worker->>s3: get file(s)
67+
worker->>ses: send email
68+
69+
break error
70+
alt AWS SDK error and max retries not reached
71+
worker->>solidqueue-db: schedule retry
72+
else
73+
worker->>sentry: send error
74+
end
75+
end
76+
77+
ses->>worker: return message_id
78+
worker->>runner-db: set mail_message_id on Submission
79+
worker->>runner-db: set the last_delivery_attempt timestamp on Submission
80+
81+
ses-)inbox: send email
82+
note over ses,inbox: happens some time later
83+
84+
alt email sent successfully
85+
ses->>sns: send delivery notification
86+
processor->>inbox: get form from inbox
87+
processor->>processor: process form
88+
else email bounces
89+
ses->>sns: send bounce notification
90+
note over ses,sns: We have an SQS queue subscribed to the<br/> SNS topic and a recurring task to poll<br/>the SQS queue.
91+
end
92+
93+
worker->>worker: Recurring task deletes Submissions<br/>that haven't bounced after 7 days
94+
```
95+
96+
## Handling email bounces/complaints
97+
```mermaid
98+
99+
---
100+
title: Handling email bounces/complaints
101+
---
102+
103+
sequenceDiagram
104+
105+
autonumber
106+
107+
participant worker as Solid Queue worker
108+
participant solidqueue-db as Solid Queue database
109+
participant runner-db as Forms Runner database
110+
participant sqs as Amazon SQS
111+
participant sentry as Sentry
112+
113+
actor support as Forms team tech support
114+
115+
worker->>solidqueue-db: enqueue recurring receive bounces job
116+
worker->>solidqueue-db: dequeue receive bounces job
117+
worker->>sqs: get messages from bounces and complaints queue
118+
alt there is a bounce SQS message
119+
worker->>runner-db: get Submission by the message_id in the SQS message
120+
worker->>runner-db: update delivery_status of Submission to "bounced"
121+
worker->>worker: Log with the submission details
122+
worker->>sentry: send error event
123+
sentry->>support: Alert via Slack
124+
support->>support: Identify why the email bounced
125+
support->>support: Run rake task to retry submission
126+
else there is a complaint SQS message
127+
worker->>runner-db: get Submission by the message_id in the SQS message
128+
worker->>worker: Log with the submission details
129+
end
130+
131+
```
132+
133+
## Handling successful deliveries
134+
135+
```mermaid
136+
137+
---
138+
title: Handling successful deliveries
139+
---
140+
141+
sequenceDiagram
142+
143+
autonumber
144+
145+
participant worker as Solid Queue worker
146+
participant solidqueue-db as Solid Queue database
147+
participant runner-db as Forms Runner database
148+
participant sqs as Amazon SQS
149+
150+
actor support as Forms team tech support
151+
152+
worker->>solidqueue-db: enqueue recurring receive deliveries job
153+
worker->>solidqueue-db: dequeue receive deliveries job
154+
worker->>sqs: get messages from deliveries queue
155+
worker->>runner-db: get Submission by the message_id in the SQS message
156+
worker->>worker: log a "form_submission_delivered" event
157+
note over worker,runner-db: we don't currently use the "delivered" status for anything other than for information
158+
```

0 commit comments

Comments
 (0)