The `body` field of the ‘preview a template’ endpoint should contain the
content of the template with the placeholders replaced.
It should not be rendered into a plain text email, which does stuff like
normalising newlines (so `\r\n` becomes `\n`). However the object that
the `create_post_template_preview_response` function receives is an
instance of `PlainTextEmailTemplate`. So we can’t just call `str()` on
it. Instead we need to call the `__str__` method of
`WithSubjectTemplate` which gives us the result we want.
We were already doing this the right way in the V1 endpoint[1] but
forgot to do it here too.
1. 0108749daa/app/template/rest.py (L181-L184)
By adding `force=True` to request.get_json() the mime type is ignore. If the data is not valid json the method will return a `BadRequestError` we catch that and throw our own error with a clear error message "Invalid JSON supplied in POST data".
If the json is valid return the json data or an empty dict if None is passed in.
This PR improves the error messages if the json is invalid, previously, the error message was "None object type" message which is not very helpful.
Because we test for the other properties in the schema.
Also sets `additionalProperties` to `False` so we’re forced to update
the schemas if we make similar changes in the future. This means
removing `created_by` from the test data because it’s not returned by
the real response.
If you’re trying to show what a Notify email will look like in your
caseworking system all the API gives you at the moment is raw markdown
(with the placeholders replaced).
This isn’t that useful if your caseworkers have no idea what markdown
is. If we also give teams the HTML then they can embed this in their
systems, and the people using those systems will be able to see how
headings, bulleted lists, etc. look.
In the future, we may want to return additional information about
placeholders.
We came up with three possible formats:
1. list of `dict`s, eg `[{'name': 'first name', 'required': True}]`
2. `dict` of `list`s, eg `{'required': ['first name']}`
3. `dict` of `dict`s, eg `{'name': {'required': True}}`
I don’t like 1. because it’s harder to traverse if all you want is the
name of the placeholders, and suggests that you could have two
placeholders with the same name (which you can’t). I don’t like 2.
because it only lets the data be sliced by one dimension (unless the
inner lists aren’t exclusive, in which case you’d need to filter
duplicates when just listing placeholders).
I think 3. has the two advantages of:
- represents that personalisation is unique, ie you can’t pass back in
two different values for the same key
- is forward compatible, ie we can add many more properties of a
placeholder without breaking anything
So this commit implements 3.
> Currently when retrieving a template via one of the clients, we do
> not return the personalisation fields that are required for that
> template.
>
> This is useful for services who want to perform template validation on
> their own systems. A service user has also requested this.
– https://www.pivotaltracker.com/story/show/150674476
This commit adds an extra attribute to the JSON response containing an
array of the placeholder names. This key is called "personalisation",
to match the argument that developers use to pass in the values of
placeholders.
The use for the public template API is for building caseworking systems
or similar, where you might need a list of templates to pick from (ie
instead of using the Notify web interface to pick from and send a
message).
Right now our API isn’t returning the template name as part of the
response. The name is a useful, human-friendly way of identifying a
template.
This commit changes the response to include the name.
Some clients will need updating before this can be useful.
