Add Notify integration guidance #574

quis · 2018-08-02T08:41:48Z

Adapted from: https://gist.github.com/quis/1136d255a5cdc47f4b72bc5bf234cf97

36degrees · 2018-08-02T09:19:19Z

docs/documentation/using-notify.md

@@ -0,0 +1,48 @@
+To set it locally, run this command in your Terminal, in the root


It feels like there's some context missing here – I don't know what Notify is, and whether I want to (or need to) use it. The guidance is talking about 'setting it' but I have no idea what 'it' is.

36degrees · 2018-08-02T09:22:06Z

docs/documentation/using-notify.md

+```shell
+   echo NOTIFYAPIKEY=xxxxxxx >> .env
+````   
+(where xxxxxxx is a key you’ve created in Notify). This creates a file 


In most cases, .env should already exist thanks to

govuk-prototype-kit/start.js

Lines 46 to 52 in 9953d9d

// Create template .env file if it doesn't exist

const envExists = fs.existsSync(path.join(__dirname, '/.env'))

if (!envExists) {

fs.createReadStream(path.join(__dirname, '/lib/template.env'))

.pipe(fs.createWriteStream(path.join(__dirname, '/.env')))

}

}

If I had already customised that file and didn't know what that command did, I'd be nervous that it'd wipe out my existing env configuration.

docs/documentation/using-notify.md

36degrees · 2018-08-02T09:24:04Z

docs/documentation/using-notify.md

+(where xxxxxxx is a key you’ve created in Notify). This creates a file 
+named `.env` which contains your API key.
+
+To set it on Heroku, go to the settings page on your app, click


Is it clear that users will need to do this for Heroku (if they're using Heroku) as well as locally, because their .env file won't (shouldn't) be committed? At the minute it could be interpreted as an either/or thing.

36degrees · 2018-08-02T09:25:58Z

docs/documentation/using-notify.md

+This code goes at the bottom of routes.js:
+
+```javascript
+router.post('/page-with-email-or-phone-input', function (req, res) {


Can we call out that this needs to be the same URL that the form POSTs to?

quis · 2018-08-09T16:23:31Z

Thanks for the comments @36degrees. I will tidy this up when I have a bit more time…

quis · 2018-09-28T09:51:19Z

I’ve rewritten the instructions to add a lot more context. The previous instructions were a very bare-bones draft which assumed a lot of knowledge.

Hopefully this is enough so that someone who is confident using the prototype kit can integrate their prototype with Notify.

joelanman · 2018-10-02T15:33:34Z

docs/documentation/using-notify.md

+
+You can use GOV.UK Notify to send text messages or emails when users
+interact with your prototype. For example you could send users a
+confirmation email sent at the end of a journey.


repetition of 'sent'/'send'?

joelanman · 2018-10-02T15:38:38Z

docs/documentation/using-notify.md

+
+To save the key on your computer, run this command in your Terminal, in
+the root folder of your prototype (where xxxxxxx is a key you’ve copied
+from Notify):


I think it might be less daunting to just tell people to add this line to end of .env - and they'll use whatever tool is familiar to them. The only downside is there's a possibility .env doesn't exist (before running for the first time), though if so people just need to run the kit.

joelanman · 2018-10-02T15:40:13Z

docs/documentation/using-notify.md

+### Keeping your key safe
+
+It’s really important that you keep your key secret. If you put it in
+the `.env` file it’s safe – that file isn’t published on Github. If you


Github > GitHub

joelanman · 2018-10-02T15:44:04Z

docs/documentation/using-notify.md

+    notify = new NotifyClient(process.env.NOTIFYAPIKEY);
+```
+
+`process.env.NOTIFYAPIKEY` is a special kind of variable that Node


Not sure users need to know this? Might be simpler to leave it out

joelanman · 2018-10-02T15:46:30Z

docs/documentation/using-notify.md

+Make a page with a form to collect the user’s email address. For
+example:
+```
+{% from "input/macro.njk" import govukInput %}


Could we replace this with the HTML for now? We're not really pushing the macros as the main approach yet, as the error handling is really bad and we don't cover them in the training yet.

joelanman · 2018-10-02T15:47:56Z

docs/documentation/using-notify.md

+
+Save this page as `email-address-page.html`.
+
+Then add this code at the bottom of routes.js:


needs to be above module.exports = router

I wonder if there's a way to provide all this code as examples, though I know we can't distribute a Notify key. Hmm

joelanman · 2018-10-04T12:57:44Z

This is great, thanks Chris! It would be great for one of us to do some guerilla testing and see if someone can follow these instructions easily and send an email.

docs/documentation/using-notify.md

36degrees

Tested this and it works well – though the example form doesn't extend the layout so if you blindly copy the instructions you get an unstyled form without the header, footer, etc.

Adapted from: https://gist.github.com/quis/1136d255a5cdc47f4b72bc5bf234cf97

The previous instructions were a very bare-bones draft which assumed a lot of context. This commit attempts to rewrite them for someone without knowledge of what Notify is, or how an API works. Hopefully this is enough so that someone who is confident using the prototype kit can integrate their prototype with Notify.

36degrees reviewed Aug 2, 2018

View reviewed changes

joelanman reviewed Oct 2, 2018

View reviewed changes

36degrees reviewed Oct 8, 2018

View reviewed changes

docs/documentation/using-notify.md Outdated Show resolved Hide resolved

36degrees approved these changes Oct 8, 2018

View reviewed changes

quis added 6 commits October 29, 2018 12:08

Add first draft of Notify integration guidance

a54a9d8

Adapted from: https://gist.github.com/quis/1136d255a5cdc47f4b72bc5bf234cf97

Remove duplicate send/sent

7900a7a

Remove use of shell redirection to save key

f0a0601

Capitalise GitHub

c5d8516

Remove unneeded explanation of variable

eac9a31

kr8n3r force-pushed the patch-3 branch from 636e772 to 54e3c50 Compare October 29, 2018 12:10

quis added 2 commits October 29, 2018 12:28

Use HTML not macro for form example

531f95d

Fix line telling people where to put routing code

aa9fbb3

kr8n3r force-pushed the patch-3 branch from 54e3c50 to aa9fbb3 Compare October 29, 2018 12:28

kr8n3r added this to the [NEXT] milestone Oct 29, 2018

Add CHANGELOG entry

909b01f

quis changed the title ~~Add first draft of Notify integration guidance~~ Add Notify integration guidance Oct 29, 2018

kr8n3r merged commit 77a1205 into alphagov:master Oct 29, 2018

kr8n3r mentioned this pull request Nov 1, 2018

Release 8.3.0 #629

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Notify integration guidance #574

Add Notify integration guidance #574

quis commented Aug 2, 2018

36degrees Aug 2, 2018

36degrees Aug 2, 2018

36degrees Aug 2, 2018

36degrees Aug 2, 2018

quis commented Aug 9, 2018

quis commented Sep 28, 2018

joelanman Oct 2, 2018

quis Oct 4, 2018

joelanman Oct 2, 2018

quis Oct 4, 2018

joelanman Oct 2, 2018

quis Oct 4, 2018

joelanman Oct 2, 2018

quis Oct 4, 2018

joelanman Oct 2, 2018

quis Oct 4, 2018

joelanman Oct 2, 2018

quis Oct 4, 2018

joelanman commented Oct 4, 2018

36degrees left a comment

		@@ -0,0 +1,48 @@
		To set it locally, run this command in your Terminal, in the root

	// Create template .env file if it doesn't exist
	const envExists = fs.existsSync(path.join(__dirname, '/.env'))
	if (!envExists) {
	fs.createReadStream(path.join(__dirname, '/lib/template.env'))
	.pipe(fs.createWriteStream(path.join(__dirname, '/.env')))
	}
	}


		Save this page as `email-address-page.html`.

		Then add this code at the bottom of routes.js:

Add Notify integration guidance #574

Add Notify integration guidance #574

Conversation

quis commented Aug 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

quis commented Aug 9, 2018

quis commented Sep 28, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joelanman commented Oct 4, 2018

36degrees left a comment

Choose a reason for hiding this comment