Personalisation, PDF conversion and font language variant updates (#81)

* Added mention of 'message cascades' in routing plan content for 'parallel send' feature mention.

* 'or' replaced with 'and'

* Message status page created
- changes to /using-nhs-notify/mesh to match MESH guidance
- sender IDs changed to sender names

* Emma 2i requested changes

* Added /using-nhs-notify/nhs-app-templates, /using-nhs-notify/email-templates, /using-nhs-notify/text-message-templates and /using-nhs-notify/letter-templates.

These are based on the Confluence pages https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?spaceKey=RIS&title=3.8+Creating+letter+templates onwards, with some minor tweaks to word ordering. Romy has approved this content now.

Uploaded the standardised Word doc templates for all 4 channels to /assets/worddocs, and linked to these. Craig in cyber security approved this approach (see ticket for screenshot).

Updated /using-nhs-notify/personalisation in line with the Confluence page. The FAQs from onboarding indicated there's a user need to provide the PDS personalisation fields.

I also added content on how users provide their own personalisation data, in line with Tan's Confluence page https://nhsd-confluence.digital.nhs.uk/display/RIS/NHS+Notify+%7C+Personalisation+Fields.

In /pricing/text-messages, I replaced 'it will count as more than one message' with 'it will be charged as more than one message'. This was prompted by a comment from Romy on the text message template content. I tweaked the content to match the later version of the UI prototype, which we based on findings from user research.

* Removed mention of bank holidays from emails and text message delivery times.

* Removed unnecessary bullets and headings anchor links in Text message templates.

Updated link text for the 4 template pages in the Using NHS Notify parent page - removed 'Creating...' from the start of each link.

* Fixed typo in /text-message-templates. Removed 'Creating...' from links on /using-nhs-notify.

* Updated names of Word docs to replace spaces with hyphens and make all lower case. Updated downloadable links to follow the approach Jake researched, for example [letter template]({% link assets/worddocs/letter-template-nhs-notify.docx %})

* Removed unnecessary space from line 26 on docs/pages/using-nhs-notify/letter-templates.

* Update accept.txt

Includes:
- Noto
- URL
- ctrl
- pending_enrichment
- unnotified
- permanent_failure
- temporary_failure
- technical_failure
- precompiled
- validation_failed
- fullName
- namePrefix
- clientRef

* In /using-nhs-notify/delivery-times#letters, replaced the sentence 'Once your letter has been sent, it can take...' with 'Once you've provided us with recipients' NHS numbers, it can take up to 2 working days for our suppliers to dispatch your letter'.

I also added anchor links to the top of the same page, /using-nhs-notify/delivery-times, to make navigation easier.

* Added content on what users need to do in order to use recipient contact details that are outside of PDS.

* Emma recommendations

* Removed address_line_x, clientRef, recipientContactValue and template from the bulleted list of personalisation fields from PDS as these are for internal use only.

Restructured the first paragraph under ### Personal Demographics Service (PDS) personalisation fields. This was based off a conversation with Jake and it aims to clarify the link between PDS, NHS numbers and personalisation fields.

* In /workspaces/nhs-notify-web-cms-dev/docs/_sass/_nhsnotify.scss I added the line 'flex-wrap: wrap;' in the following code:

.nhsuk-header__navigation-list {
  justify-content: flex-start;
  flex-wrap: wrap;
}

This is an interim step to make the main nav list items wrap correctly when the site is viewed on a mobile device. It's not our ultimate solution but it makes the site more mobile responsive and accessible.

* Removed mentions of date of birth from failed message status descriptions. Removed date of birth as as an example of a column header in a MESH request.

* Added link to NHS Notify MESH documentation in /using-nhs-notify/mesh

* Squashed commit of the following:

commit 7b904fc
Author: Ross Buggins <[email protected]>
Date:   Tue Nov 19 17:02:42 2024 +0000

    Quick and easy js to auto hide.

commit 8aed356
Author: Jake Cosgrove <[email protected]>
Date:   Tue Nov 19 16:05:22 2024 +0000

    Developer banner and new site banner

commit a3d47d2
Author: Jake Cosgrove <[email protected]>
Date:   Mon Nov 11 15:47:17 2024 +0000

    removed phase banner and underlines from primary nav list items when hovered

commit 3a30f41
Author: Jake Cosgrove <[email protected]>
Date:   Mon Nov 11 13:50:40 2024 +0000

    removed border from phase banner

commit fc61be5
Author: Jake Cosgrove <[email protected]>
Date:   Fri Nov 8 16:32:05 2024 +0000

    Added phase banner component and related sass.

    Added new template for including pages of content that does not need a side-navigation.

commit 45d34e6
Author: Jake Cosgrove <[email protected]>
Date:   Tue Nov 5 21:59:47 2024 +0000

    two-third column tests

* Changed first subheading to a h2 from h3

* Removed the other phase banners from Ross' test

* removed phase banner includes due to component not being tested or released by developer

* Update personalisation.md

* First draft updated guidance

* Requested changes

* Changes from Alex's review:
- corrected typo's
- added missing anchor link
- included image of example inbox showing sender name and 'from' address

* Romy suggested that we use screenshots to show where the sender names appear for NHS App and SMS.

This commit includes additional images to support user understanding of sender names and where they sit in context.

* This commit includes:
- new HTML includes specific for images with captions so they fit 100% of their container
- images on pages use new includes
- inset text has override style class to reduce margin-top
- side nav now disappears when below 768px breakpoint (need to talk to design team about mobile solution)

* Added the onboard with NHS Notify page to our main site to keep information in one place - requested by Amina in onboarding/ engagement.

* Added content about sending text message sender names for approval with NCSC.

* Use new image-with-text.html includes

* Changes from Emma/ Jake discussion

Removes numbered steps from /get-started and introduces onboarding as a section in /get-started

* Content changes following Emma's 2i

* Added 'new' to text message sender names

* Aligns side navigation styling to NHS UK frontend by removing indents from 'child' pages

* This commit includes:
- New breadcrumb.html includes to support navigation
- Updated styling to the side navigation to match the NHS Design system
- Updated side navigation to exclude parent pages
- primary-navigation.html updated to include mobile responsive dropdown (needs future commit to patch)
- New override css to remove margin-bottom from breadcrumb

* Header styling fixes - janky fixes to enable the menu dropdown to work at mobile breakpoints.

* Emma 2i requested changes:
- add and change link to sandbox environments
- Change 'lead in line' for details component in step 9
- replace(s) from device(s)
- rephrase bullets in step 9 'Prove you have developed your integration securely' to statements instead of questions

* Silly apostrophe syntax change

* Typo correction.

* Pause 'Onboard with NHS Notify' migration.

The migration of this page from the service catalogue has paused until changes to the onboarding process are confirmed and accurately reflected in the content.

* Changes:
- Moved 'text message sender name' to last section of page to reflect preferred channel order of NHS Notify
- removed 'return addresses for letters heading'
- reordered bulleted list of anchor links to reflect heading structure

* update ruby version

* Updated /personalisation based on CCM-7937, CCM-7780 and CCM-8133. I also:

- added sentence about no spaces in placeholder text following Mike Houston's comment saying that
we need to be more restrictive as we're generalising across multiple suppliers and template systems
- added anchor links at top of page to help with navigation between the 2 types of personalisation and avoid the custom fields section being missed

* Updated /using-nhs-notify/letter-templates based on CCM-8312 - added new section 'Converting your letter to a PDF' and updated 'Downloading Noto Sans' with language variant guidance. Added anchor links at the start to highlight the ordered steps users need to go through, including the new PDF conversion step.

Changed the personalisation sections in each of the 4 template pages in /using-nhs-notify. Simplified the content and linked to /using-nhs-notify/personalisation to reduce duplication and have one single source of truth.

* Following Jake's 2i, I changed two instances of 'fields' to 'placeholder' to be more consistent with the rest of the content.

* Changes based on Jake's 2i comments

---------

Co-authored-by: Mark R <[email protected]>
Co-authored-by: Jake Cosgrove <[email protected]>
Co-authored-by: Ross Buggins <[email protected]>
Co-authored-by: alexcolbeck1 <[email protected]>

Author: 5 people

docs/assets/personalisationexampledata/personalisation-example-data-nhs-notify.xlsx

@@ -18,7 +18,7 @@ Download our [email template]({% link assets/worddocs/email-template-nhs-notify.
 
 You can save the template and edit it with your message content.
 
-## Formatting your NHS App message
+## Formatting your email
 
 Organise your message content using the styles in the template.
 
@@ -42,13 +42,7 @@ You can also find out about:
 
 ## Personalisation
 
-To add a personalisation field, include a placeholder with double brackets around it. For example:
-
-{% include components/inset-text.html
-    text='Hello ((firstName)), your NHS Number is ((nhsNumber))'
-%}
-
-Read about the [personalisation fields]({% link pages/using-nhs-notify/personalisation.md %}) that are available in the Personal Demographics Service (PDS) and how to provide your own personalisation data.
+You can personalise your emails by adding personalisation fields. [Learn how to use personalisation]({% link pages/using-nhs-notify/personalisation.md %}).
 
 ## Headings
 

docs/pages/using-nhs-notify/email-templates.md

@@ -10,20 +10,30 @@ permalink: /using-nhs-notify/letter-templates
 section: Writing a message
 ---
 
-Upload a Word document of a letter and NHS Notify will print and post it for you.
+Upload a PDF of your letter and NHS Notify will print and post it for you.
 
-## How to edit your letter using our template
+Your PDF must meet our letter specification. The page size and layout is A4 portrait (210 x 297mm).
+
+You'll need to:
+
+1. [Download our Microsoft Word template.](#how-to-use-our-letter-template)<!-- markdownlint-disable-line -->
+2. [Format your letter.](#formatting-your-letter)
+3. [Convert your letter to a PDF.](#converting-your-letter-to-a-pdf)
+
+## How to use our letter template
 
 Your Word document must meet our letter specification. The page size and layout is A4 portrait (210 x 297mm).
 
 Download the relevant letter template to set up your letter:
 
-- [letter template]({% link assets/worddocs/letter-template-nhs-notify.docx %})
+- [standard letter template]({% link assets/worddocs/letter-template-nhs-notify.docx %})
 - [large print letter template]({% link assets/worddocs/letter-template-nhs-notify-large-print.docx %})
 - [other language letter template]({% link assets/worddocs/letter-template-nhs-notify-other-language.docx %})
-- [other language letter (right aligned)]({% link assets/worddocs/letter-template-nhs-notify-other-language-right-aligned.docx %})
+- [other language letter (right aligned) template]({% link assets/worddocs/letter-template-nhs-notify-other-language-right-aligned.docx %})
 - [parent or guardian letter template]({% link assets/worddocs/letter-template-nhs-notify-parent-or-guardian.docx %})
 
+You'll need the desktop Microsoft Word app.
+
 You can save the template and edit it with your message content.
 
 ## Formatting your letter
@@ -32,14 +42,18 @@ Do not edit the page margins in the letter template. It has the correct formatti
 
 Organise your message content using the styles in the template.
 
-If you’re copying and pasting text from another document, paste it without any formatting. Then [apply the styles](https://support.microsoft.com/en-gb/office/apply-styles-f8b96097-4d25-4fac-8200-6139c8093109) in the template.
+If you're copying and pasting text from another document, paste it without any formatting. Then [apply the styles](https://support.microsoft.com/en-gb/office/apply-styles-f8b96097-4d25-4fac-8200-6139c8093109) in the template.
 
-You can also use [Microsoft Word’s format painter](https://support.microsoft.com/en-gb/office/use-the-format-painter-4bb415a9-d4e4-42b7-b579-170adc594e40) to copy the formatting of the styles and apply it to your text.
+You can also use [Microsoft Word's format painter](https://support.microsoft.com/en-gb/office/use-the-format-painter-4bb415a9-d4e4-42b7-b579-170adc594e40) to copy the formatting of the styles and apply it to your text.
+
+{% include components/inset-text.html
+    text="Keep the comments and pre-formatted text in the template until you've finished adding your message content. They'll help you to apply the styles."
+%}
 
 Find out how to use:
 
-- [personalisation](#personalisation)<!-- markdownlint-disable-line -->
-- [font and font size](#font-and-font-size)
+- [font and font size](#font-and-font-size)<!-- markdownlint-disable-line -->
+- [personalisation](#personalisation)
 - [headings](#headings)
 - [paragraphs and body text](#paragraphs-and-body-text)
 - [links](#links)
@@ -55,16 +69,6 @@ You can also find out about content you should not edit, including the:
 - [date](#date)
 - [page count](#page-count)
 
-## Personalisation
-
-To add a personalisation field, include a placeholder with double brackets around it. For example:
-
-{% include components/inset-text.html
-    text='Hello ((firstName)), your NHS Number is ((nhsNumber))'
-%}
-
-Read about the [personalisation fields]({% link pages/using-nhs-notify/personalisation.md %}) that are available in the Personal Demographics Service (PDS) and how to provide your own personalisation data.
-
 ## Font and font size
 
 The font size for standard letters is 12 points. The font size for large print is 16 points.
@@ -73,21 +77,34 @@ NHS Notify prints letters in the font Noto Sans.
 
 ### Downloading your font
 
+You must download and use Noto Sans as the font for all of your letters, including [letters in other languages]({% link pages/using-nhs-notify/letters-in-other-languages.md %}). If you're sending letters in other languages that use different character sets, download Noto Sans in those languages.
+
+Go to [Noto Sans on Google Fonts](https://fonts.google.com/noto/fonts) and choose the languages you need by selecting 'Get font'. Then select 'Download all' to download Noto Sans to your device as a zip file.
+
 Noto Sans is a free font.
 
-Download Noto Sans to ensure that you can edit and view your template as it will be printed.
+#### For Windows
+
+1. Right click the zip file and select 'Extract all'.
+2. Open the file. Open each folder. Select all of the TrueType font files, right click and select 'Install'.
+3. If the folder contains a sub-folder called 'static', open this.
+4. Select all of the TrueType font files in this folder. Right click and select 'Install'.
 
-1. Go to [Noto Sans on Google Fonts](https://fonts.google.com/noto/specimen/Noto+Sans). Select 'Download all' to download Noto Sans to your device as a zip file.
-2. Right click the zip file and select 'Extract all'.
-3. Open the file. Right click 'NotoSans-Italic-VariableFont_wdth,wght' and select 'Install'. Right click 'NotoSans-VariableFont_wdth,wght' and select 'Install'.
-4. Open the folder 'static'.
-5. Select all of the files in this folder by dragging your mouse over them or selecting 'ctrl' + 'a' on your keyboard. Right click and select 'Install'.
+#### For Mac
 
-Noto Sans will now be available in Microsoft Word.
+Follow the [install fonts guidance](https://support.apple.com/en-gb/guide/font-book/fntbk1000/mac). Make sure you install the static fonts.
+
+Read [Google's guidance on installing fonts](https://fonts.google.com/knowledge/using_type/installing_and_managing_fonts) for more information.
+
+Noto Sans should now be available in Microsoft Word.
+
+## Personalisation
+
+You can personalise your letters by adding personalisation fields. [Learn how to use personalisation]({% link pages/using-nhs-notify/personalisation.md %}).
 
 ## Headings
 
-Use the style ‘Heading 2, NHS letter heading' in the template for headings.
+Use the style 'Heading 2, NHS letter heading' in the template for headings.
 
 Headings are in bold. They are not in italics or underlined.
 
@@ -105,7 +122,7 @@ If you do not want a paragraph to run over different pages, add a page break bef
 
 ## Links
 
-Use the style ‘Hyperlink' in the template for links.
+Use the style 'Hyperlink' in the template for links.
 
 Write links in full, starting with https://. For example:
 
@@ -124,7 +141,7 @@ If you have a long, complex web address, you can [request a short URL from GOV.U
 We do not recommend using a third-party link shortening service because:
 
 - your users cannot see where the link will take them
-- your link might stop working if there’s a service outage
+- your link might stop working if there's a service outage
 - you can no longer control where the redirect goes
 
 ## Bullet points
@@ -146,7 +163,7 @@ Images must be black and white. Position them within the same page margins as th
 
 If you want to include a QR code, put it in the body of your letter. Insert it as an image.
 
-You’ll need to generate the QR code yourself.
+You'll need to generate the QR code yourself.
 
 You must also provide a short URL or written instructions for how to find your webpage. For example:
 
@@ -162,7 +179,9 @@ The address field fits inside the address window on the envelope.
 
 The address is a personalisation field and is set automatically.
 
-The recipient’s name is always included as the first line of the address. For a letter about a child, the first line will include 'Parent or guardian of'.
+The recipient's name is always included as the first line of the address.
+
+If your letter is about a child, use the [parent or guardian letter template](#how-to-use-our-letter-template). This template includes 'Parent or guardian of' in the first line of the address.
 
 ### NHS logo
 
@@ -189,3 +208,30 @@ The page count shows the current page number and the total number of pages. For
 %}
 
 It updates automatically.
+
+## Converting your letter to a PDF
+
+When you've finished editing your template in Microsoft Word, you'll need to save it as a PDF.
+
+Before you start, check that your English message content is in the Noto Sans font and any message content in other languages is in the relevant language variant of the Noto Sans font.
+
+1. In the 'Review' tab, go to 'Markup'. Select 'No markup' from the drop-down list to hide any comments or tracked changes.
+2. Select 'File' and 'Save as'. Select 'PDF' from the drop-down list.
+3. For Windows, select 'Standard (publishing online and printing)' in the 'Optimize for' section. Then select 'Save'. For Mac, select 'Best for printing' in the 'File format' section. Then select 'Save'.
+
+### Naming your PDF
+
+Name your PDF template clearly so that it's easy to identify. Make sure you include the following details:
+
+- organisation or service name
+- cohort or topic of your message
+- language used, including English
+- accessible format or standard format used
+- message channel - letter
+- version number
+
+For example:
+
+{% include components/inset-text.html
+    text='vaccinations_under-16_english_standard_letter_v1'
+%}

docs/pages/using-nhs-notify/letter-templates.md

@@ -41,13 +41,7 @@ You can also find out about:
 
 ## Personalisation
 
-To add a personalisation field, include a placeholder with double brackets around it. For example:
-
-{% include components/inset-text.html
-    text='Hello ((firstName)), your NHS Number is ((nhsNumber))'
-%}
-
-Read about the [personalisation fields]({% link pages/using-nhs-notify/personalisation.md %}) that are available in the Personal Demographics Service (PDS) and how to provide your own personalisation data.
+You can personalise your NHS App messages by adding personalisation fields. [Learn how to use personalisation]({% link pages/using-nhs-notify/personalisation.md %}).
 
 ## Headings
 

docs/pages/using-nhs-notify/nhs-app-templates.md

@@ -10,14 +10,19 @@ permalink: /using-nhs-notify/personalisation
 section: Writing a message
 ---
 
-You can send personalised messages using a single template.
+You can send personalised messages by adding personalisation fields to a single template.
 
-To personalise a message, use double brackets to add a placeholder to your content. For example:
+Use double brackets to add a placeholder to your content. Do not include spaces in your placeholder text. For example:
 
 {% include components/inset-text.html
-    text='Hello ((firstName)), your NHS Number is ((nhsNumber))'
+    text='Hello ((fullName)), your NHS Number is ((nhsNumber))'
 %}
 
+You can use:
+
+- [Personal Demographics Service (PDS) personalisation fields](#personal-demographics-service-pds-personalisation-fields)<!-- markdownlint-disable-line -->
+- [custom personalisation fields](#custom-personalisation-fields)
+
 ## Personal Demographics Service (PDS) personalisation fields
 
 NHS Notify uses the [Personal Demographics Service (PDS)](https://digital.nhs.uk/services/personal-demographics-service) to find and populate certain personalisation fields for each recipient. This happens automatically when you [tell us who you want to message]({% link pages/using-nhs-notify/tell-us-who-you-want-to-message.md %}) using recipients' NHS numbers.
@@ -26,20 +31,15 @@ You can use the following PDS personalisation fields in your templates:
 
 - fullName
 - firstName
-- middleNames
 - lastName
-- namePrefix
-- nameSuffix
 - nhsNumber
 - date
 
 Any placeholders in your content need to match the PDS personalisation fields.
 
-## Providing your own personalisation data
+## Custom personalisation fields
 
-You can provide your own personalisation data.
-
-Do not send us personalisation data that's already available in PDS. We'll use the PDS data over your own data in this case.
+You can add custom personalisation fields that use your own personalisation data.
 
 ### If you're using NHS Notify API
 
@@ -64,3 +64,56 @@ For example, if you wanted to include 'practice' as a personalisation field, the
 {% include components/inset-text.html
     text='nhsNumber,requestItemRefId,personalisation_practice'
 %}
+
+### Providing example data
+
+The data used in your personalisation fields can affect the formatting and length of your messages. This could make some messages cost more than expected.
+
+You'll need to provide example data if you're using custom personalisation fields. This is so that we can show you what your templates will look like with different lengths of data in your personalisation fields.
+
+Download and complete our [example personalisation data spreadsheet]({% link assets/personalisationexampledata/personalisation-example-data-nhs-notify.xlsx %}).
+
+The placeholders in your content must match the fields in the 'personalisation field' column.
+
+You'll need to provide short, medium and long lengths of example data for each of your personalisation fields.
+
+For example, if you had ((hospital_address_line)) as a personalisation field, you might choose the following example data:
+
+{% include components/inset-text.html
+text='
+
+- Hospital A - short length
+- Hospital ABCDE - medium length
+- Hospital ABCDEFGHIJKLMN - long length'
+  %}
+
+It's up to you to decide how many characters to use for the different lengths.
+
+If your data will be a fixed length for a particular personalisation field, use 3 different examples of the same length.
+
+Your example data does not need to be real data.
+
+### Fields to avoid for custom personalisation
+
+If you want to use custom personalisation, do not use the following placeholders:
+
+- emailAddress
+- phoneNumber
+- addressLine1
+- addressLine2
+- addressLine3
+- addressLine4
+- addressLine5
+- addressLine6
+- addressLine7
+- [PDS personalisation fields](#personal-demographics-service-pds-personalisation-fields)
+
+Custom personalisation will not work if you try to add it using these placeholders. This includes variations such as spaces and upper or lower cases.
+
+You can include extra words in your custom personalisation placeholders to make them different from the fields to avoid.
+
+For example, if you wanted to include GP practice phone number as a custom personalisation field, your placeholder could be:
+
+{% include components/inset-text.html
+    text='((GP_phoneNumber))'
+%}

docs/pages/using-nhs-notify/personalisation.md

@@ -30,4 +30,4 @@ Use primary message cascades to send a message with a different channel as a fal
 
 ### Secondary cascades
 
-Use a secondary message cascades to send a message with another channel at the same time as your primary channel. For example, sending a text message at the same time as an email. You cannot fallback to another channel with secondary cascades.
+Use secondary message cascades to send a message with another channel at the same time as your primary channel. For example, sending a text message at the same time as an email. You cannot fallback to another channel with secondary cascades.

docs/pages/using-nhs-notify/routing-plans.md

@@ -41,13 +41,7 @@ You can also find out about:
 
 ## Personalisation
 
-To add a personalisation field, include a placeholder with double brackets around it. For example:
-
-{% include components/inset-text.html
-    text='Hello ((firstName)), your NHS Number is ((nhsNumber))'
-%}
-
-Read about the [personalisation fields]({% link pages/using-nhs-notify/personalisation.md %}) that are available in the Personal Demographics Service (PDS) and how to provide your own personalisation data.
+You can personalise your text messages by adding personalisation fields. [Learn how to use personalisation]({% link pages/using-nhs-notify/personalisation.md %}).
 
 ## Body text