Calculating the number of pages in a letter is quite slow. And the send
yourself a test pages need to load _fast_. Since filling in placeholders
is very unlikely to change the number of pages in the resultant letter,
it’s pretty safe to cache that count, and makes the subsequent pages
load a lot faster.
The send yourself a test feature is useful for two things:
- constructing an email/text message/letter without uploading a CSV file
- seeing what the thing your going to send will look like (either by
getting it in your inbox or downloading the PDF)
- learning the concept of placeholders, ie understanding they’re thing
that gets populated with _stuff_
The problem we’re seeing is that the current UI breaks when a template
has a lot of placeholders. This is especially apparent with letter
templates, which have a minimum of 7 placeholders by virtue of the
address.
The idea behind having the form fields side-by-side was to help people
understand the relationship between their spreadsheet columns and the
placeholders. But this means that the page was doing a lot of work,
trying to teach:
- replacement of placeholders
- link between placeholders and spreadsheet columns
The latter is better explained by the example spreadsheet shown on the
upload page. So it can safely be removed from the send yourself a test
page – in other words the fields don’t need to be shown side by side.
Showing them one-at-a-time works well because:
- it’s really obvious, even on first use, what the page is asking you to
do
- as your step through each placeholder, you see the message build up
with the data you’ve entered – you’re learning how replacement of
placeholders works by repetition
This also means adding a matching endpoint for viewing each step of
making the test letter as a PDF/PNG because we can’t reuse the view of
the template without any placeholders filled any more.
Right now showing all the pages in full is the only way we have of
showing a letter that makes sense to our users. Maybe in the future we
show some kind of truncated version, but the end of the first page is
not a good place to truncate the letter.
This commit just extracts the code for showing multiple pages from the
template view, refactors it for reuse, and includes it in the send
views.
If a service can send internationally, our CSV validation should not
catch valid international phone numbers. This means calling through
to code added to utils in:
- [ ] https://github.com/alphagov/notifications-utils/pull/156
This has been removed from utils (so things will break if utils is
upgraded without this change isn’t made). I think it’s friendlier to
present the phone number as the user entered it anyway – because this is
what they think a ‘correct’ phone number representation looks like
anyway.
while PDFs work on paas, they only do that because it turns out the
python buildpack happens to have imagemagick preinstalled - if that
ever changes then it'd break. so move those to the template preview
service. This also means we can get rid of weazyprint and wand
dependencies
We’ve seen in letters usability testing that people get stuck in a
“no-man’s land” when trying to go back from the _Send yourself a test_
page.
This was broken for two reasons:
- we hadn’t considered that a letter template without placeholder still
requires you to fill in
- we’ve changed subsequently made the _view template_ page the place
where you do your actions, rather than the (old) page with all the
templates shown
So this commit fixes it so that the back link always take you back to
the page you were previously on, and adds some more test cases so we
have all the scenarios accounted for.
Address line 3 is optional. Currently the only way we have of indicating
to users what is/isn’t optional is by using the example. Which probably
isn’t ideal, but should at least be correct.
Not necessary to have it on its own page – it’s one line of stuff. And
definitely not as frequent use as the ‘Upload recipients’ or ‘Send
yourself a test’ links.
Right now we have separate pages for email and text message templates.
In the future we will also have a separate page for letter templates.
This commit changes Notify to only have one page for all templates.
What is the problem?
---
The left-hand navigation is getting quite crowded, at 8 items for a
service that can send letters. Research suggests that the number of
objects an average human can hold in working memory is 7 ± 2 [1]. So
we’re at the limit of how many items the navigation should have.
In the future we will need to search/sort/filter templates by attributes
other than type, for example:
- show me the ‘confirmation’ templates
- show me the most recently used templates
- show me all templates containing the placeholder `((ref_no))`
These are hypothetical for now, but these needs (or others) may become
real in the future. At this point pre-filtering the list of templates
by type would restrict what searches a user could do. So by making this
change now we’re in a better position to iterate the design in the
future.
What’s the change?
---
This commit replaces the ‘Email templates’, ‘Text message templates’ and
‘Letter templates’ pages with one page called ‘Templates’.
This new templates page shows all the templates for the service, sorted
by most recently created first (as before).
To add a new template there is a new page with a form asking you what
kind of template you want to create. This is necessary because in the
past we knew what kind of template you wanted to create based on the
kind you were looking at.
What’s the impact of this change on new users?
---
This change alters the onboarding process slightly. We still want to
take people through the empty templates page from the call-to-action on
the dashboard because it helps them understand that to send a message
using Notify you need a template. But because we don’t have separate
pages for emails/text messages we will have to send users through the
extra step of choosing what kind of template to create. This is a bit
clunkier on first use but:
- it still gets the point across
- it takes them through the actual flow they will be using to create new
templates in the future (ie they’re learning how to use Notify, not
just being taken through a special onboarding route)
I’m not too worried about this change in terms of the experience for new
users. Furthermore, by making it now we get to validate whether it’s
causing any problems in the lab research booked for next week.
What’s the impact of this change on current services?
---
Looking at the top 15 services by number of templates[2], most are using
either text messages or emails. So this change would not have a
significant impact on these services because the page will not get any
longer. In other words we wouldn’t be making it worse for them.
Those services who do use both are not using as many templates. The
worst-case scenario is SSCS, who have 16 templates, evenly split between
email and text messages. So they would go from having 8 templates per
page to 16, which is still less than half the number that HMPO or
Digital Marketplace are managing.
References
---
1. https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two
2. Template usage by service
Service name | Template count | Template types
---------------------------------------|----------------|---------------
Her Majesty's Passport Office | 40 | sms
Digital Marketplace | 40 | email
GovWifi-Staging | 19 | sms
GovWifi | 18 | sms
Digital Apprenticeship Service | 16 | email
SSCS | 16 | both
Crown Commercial Service MI Collection | 15 | email
Help with Prison Visits | 12 | both
Digital Future | 12 | email
Export Licensing Service | 11 | email
Civil Money Claims | 9 | both
DVLA Drivers Medical Service | 9 | sms
GOV.UK Notify | 8 | both
Manage your benefit overpayments | 8 | both
Tax Renewals | 8 | both
> When the CSV is missing the header row, we get an error and the user
> will see "Sorry, we are experiencing technical difficulties..."
>
> We should return a better error message for the user.
– https://www.pivotaltracker.com/story/show/140668615
This was caused by an attempt to access the `first_recipient` variable
before it was assigned. It would only be assigned when there was at
least one row in the file.
Fixing this means doing two things:
- defaulting `first_recipient` to be `None` before looking in the file
- adding an error message for when we can’t extract any rows out of the
file (which is more nuanced than the file just being completely empty)
(There’s a nasty `sort` in the Jinja template because when there are no
rows in the file the order of the required column headers is not
deterministic.)
(previously it would have sent them to the choose template page)
if the user has added new templates or deleted the example one,
they're clearly competent enough to use the app so don't worry
(we wouldn't know what URL the tour starts on since the UUID of
the example template is random)
previously we were issuing a flask redirect (302) from the function,
which we then attempted to unpack as a dict further down the line.
raise a werkzeug.routing.RequestRedirect (301 MOVED PERMANENTLY)
instead. note: only use this pattern when the URL they attempted to
access will *NEVER* be valid, as 301s are cached by browsers.
Right now we can show what a letter template looks like as a PDF or PNG.
This commit completes the work so this is also possible when:
- showing a template with the placeholders replaced
- showing any version of a template
Also removes dependency on `Exception().message`, which was deprecated
in Python 2.6. See
97f82d565f
for full details.
Posit that examples of where you can put different parts of the address
is more helpful than ‘example, example, example’. Also shows that you
don’t have to fill all of the address columns.
Spot the Easter egg 🎅
Implements https://github.com/alphagov/notifications-utils/pull/81
Handles addresses as multiple columns:
- in ‘Send yourself a test’
- in example CSV files
- in validating that a CSV file has recipients (eg at least an ‘address
line 1’ and ‘postcode’ column)
- when showing the contents of a CSV file
As few UI changes as possible, once we have the thing working end-to-end
we can think about how the UI might need to work differently.
Who knows what would happen if a job with a letter template actually
got into the database. `403`ing the page is a quick and dirty hack to
stop this from happening.
Let users create/edit/delete letter templates.
Let them upload a CSV file or send a test against a letter template.
Big assumption at the moment is that addresses only have one line, and
therefore one column in the CSV file.
If you want to send a job on Monday morning, you should be able to
schedule it on Friday. You shouldn’t need to work on the weekend.
96 hours is a full 4 days, so you can schedule a job at any time on
Friday for any time on Monday.
We’ve checked with the information assurance people, and they’re OK
with us holding the data for this extra amount of time.
This commit changes the choose time form from showing one radio button
for each of the next 24 hours to one for each of the next 96 hours. It
changes the labels from ‘9am’ to ‘Monday at 9am’ so it’s clear which
day you’re choosing.
For two reasons:
- it’s extra stuff in tour that users dont yet need to know about
- test messages are hidden from the dashboard, so you’d have no
visibility of when they were sending once you’d scheduled them
Users need to pick a time in the next 24hrs, or send a file immediately.
Rationale for this is a bit lost in time-before-holiday, but generally:
‘Now’ and ‘later’ as the inital choices makes it really clear what
this feature is about conceptually.
The choice of times is absolute, eg ‘1pm’ not ‘in 3 hours’
Our templates are a littered with `request.args.get('help', '0')`.
This commit refactors these into a single helper method, which can be
used by the view functions, then passed to the template.
This makes the templates cleaner, and should make it easier to refactor
`help` out of the query parameters entirely in the future.
This changes it back to how it was when we first introduced this
feature:
https://github.com/alphagov/notifications-admin/pull/181
It’s kind of lost on the page where you upload a file, which is a shame
because it’s a good teaching aid.
After the tour we should ground users by dropping them on the dashboard.
In the background, we delete the example text message template. This
means that users start from a clean slate when they go to add their own
templates
This also means some wording changes to the tour so it still makes
(some) sense:
- 1, 2 and 3 should refer to the current step, not describe the next
one
- the link should take you to the dashboard
- change from ‘Get started’ to ‘Try this example’ because we’re using
‘Get started on the dashboard’
Steps to reproduce:
- make a template with a placeholder
- click ‘send yourself a test’
- leave fields blank
- click ‘check’
- see error, click ‘back’
Expected: previous page
Actual: previous page with blue help sidebar
When the URL contains `help=0`, `request.args.get('help')` returns '0'.
Doing `if '0':` is the same as doing any `if <non empty string>:` which
returns `True`.
So we should only display the help when the help query parameter is:
- not missing
- AND a string that isn’t `'0'`
While test messages technically have a file and are a job, there’s not
much reason to ever revisit them. So all they end up doing is cluttering
the dashboard and making it harder to find the actual files you’ve
actually uploaded from your computer.
So this commit:
- abstracts the name of test messages into config
- filters out any files whose filename represents a test message
- adds some more thorough tests for the jobs on the dashboard
For the button on the check page, we need to be able to say ‘1 text message’ or
‘55 emails’. We already have the logic to do this on the dashboard (101 text
messages sent), and it’s already in a component. So this commit makes the check
page use the same component.
