Merge tag 'v3.1' into fiksgatami-devfiksgatami-dev

1 files changed, 171 insertions, 44 deletions

diff --git a/docs/_includes/admin-tasks-content.md b/docs/_includes/admin-tasks-content.md
index 7e3d47efe..410caf272 100644
--- a/docs/_includes/admin-tasks-content.md
+++ b/docs/_includes/admin-tasks-content.md
@@ -4,9 +4,11 @@
 
 <img alt="When you're logged in as an administrator the 'admin' button is in the navigation menu" src="/assets/img/pro-user-guide/navigating-as-pro-staff.png" class="admin-screenshot" />
 
-If your Administrator has already given you staff permissions, you’ll see additional admin button
-on the top menu when you’re logged in. If not, your Administrator can add these permissions at
-any time: see ‘[Creating a Staff Account](#adminstrating-staff-accounts)’.
+If your Administrator has already given you staff permissions, you may see
+additional admin button on the top menu when you’re logged in. If not, your
+access may be only in the frontend (e.g. moderation does not require any
+backend admin access), or your Administrator can add these permissions at any
+time: see ‘[Creating a Staff Account](#adminstrating-staff-accounts)’.
 </div>
 
 <div class="admin-task" markdown="1" id="viewing-reports-your-area">
@@ -18,14 +20,15 @@ any time: see ‘[Creating a Staff Account](#adminstrating-staff-accounts)’.
 If you want to view everything that’s been reported within the council area, here’s the quickest
 way.
 
-Click on ‘all reports’ in the top menu. You’ll see the boundaries of your council area on the map,
-and a list of all reports listed, with the most recent reports at the top, on the left hand panel.
+Click on ‘all reports’ in the top menu. You’ll see the boundaries of your
+council area on the map, and a list of all reports listed, with the most
+recently updated reports at the top, in the left hand panel.
 
 <img alt="Click all reports in the top menu to view all reports in an area" src="/assets/img/pro-user-guide/viewing-reports-your-area.png" class="admin-screenshot" />
 
 Note that staff members can be allocated one or more category (e.g. potholes, streetlights, etc) by
 the Administrator — see ‘[Creating a Staff Account](#adminstrating-staff-accounts)’ for more details. When logged in, these staff
-members will see reports within these categories by default.
+members will only see reports within those categories by default.
 
 </div>
 
@@ -111,25 +114,16 @@ to access the full report admin editing page.
 
 <div class="admin-task" markdown="1" id="search-user">
 
-### Searching for a user
+### User admin
 
 <span class="admin-task__permissions">Permissions required: User must be marked
 as staff; “Edit users' details/search for their reports” must be ticked</span>
 
-Click on ‘admin’ in the top menu bar.
-
-Enter any part of the user’s name or email address in the ‘Search users’ box.
-
-</div>
-
-<div class="admin-task" markdown="1" id="editing-users-information">
-
-### Editing a user’s information
-
-<span class="admin-task__permissions">Permissions required: User must be marked as staff; "Edit users' details/search for their reports" must be ticked.</span>
-
-Click on ‘Edit’ beside any user to view or change their account details.
-Or, click the user’s email address to view a list of all reports and updates made by that user.
+In the admin, enter any part of the user’s name or email address in the ‘Search
+users’ box. You may click on ‘Edit’ beside any user to view or change their
+account details, click the user’s email address to view a list of all reports
+and updates made by that user, or click ‘Timeline’ to see a timeline of that
+user’s activities on the site.
 
 </div>
 
@@ -153,20 +147,22 @@ recognition of your staff role.
 
 <div class="admin-task" markdown="1" id="create-reports-behalf-user">
 
-### Creating reports on behalf of another user/ the council
+### Creating reports/ updates on behalf of another user/ the council
 
 <span class="admin-task__permissions">Permissions required: User must be marked
-as staff; one or more of ‘Create reports/updates on a user's behalf’, ‘Create
-reports/updates as anonymous user’ and ‘Create reports/updates as the council’
-must be ticked.</span>
-
-If a resident makes a report by phone or in person, staff members with the appropriate
-permissions can add it to FixMyStreet on their behalf. The report may bear the resident’s name; or
-it may be anonymous (i.e. the report-maker’s name is not published on the site, but will still be
-available in the admin interface). Alternatively, reports can be made as if from the council itself.
-In such cases, staff should make a new report just as a member of the public would — see ‘[The
+as staff; optionally, one or more of ‘Create reports/updates on a user's
+behalf’, ‘Create reports/updates as anonymous user’ and ‘Create reports/updates
+as the council’ can be ticked.</span>
+
+If a resident makes a report or update by phone or in person, staff members
+with the appropriate permissions can add it to FixMyStreet on their behalf. The
+report will be anonymous on the site, but the resident’s name will still be
+available in the admin interface. Reports can also be made as if from the
+council.
+
+Staff should make a new report just as a member of the public would — see ‘[The
 citizen’s experience](/pro-manual/citizens-experience/)'. Those with the appropriate permissions will see a dropdown box in
-the report-making interface, labeled ‘Report As’. Select ‘the council’, ‘yourself’, ‘anonymous’ or
+the report-making interface, labeled ‘Report As’. Select either the council, ‘yourself’, ‘anonymous’ or
 ‘another user’.
 
 If a user has the ‘Default to creating reports/update as the council’
@@ -174,6 +170,12 @@ permission then the dropdown will default to reporting as the council.
 Staff with the ’Markup problem details’ permission will also default to
 reporting as the council.
 
+When a staff member makes an update on the site, it will not be publicly
+displayed with the staff member’s name, but the name of the body to which the
+user is attached. Staff members with the ‘See user detail for reports created
+as the council’ permission will be able to see the staff user’s name on the
+report or update, but other staff and the public will not.
+
 </div>
 
 
@@ -356,6 +358,9 @@ If ‘Create reports/updates as the council’ is ticked in the staff user’s a
 updates will be labeled as from the council rather than the staff member’s name. For the sake of
 staff privacy, this is usually preferable.
 
+Staff with appropriate permissions can also attach an image to the update, which will then be
+displayed publicly alongside the text update.
+
 This option is also available via the general 'Update' box under the main report.
 
 #### Requests for more information
@@ -523,11 +528,36 @@ maintenance) to a staff user by editing the user and checking the relevant categ
 staff user, when logged in, will then only see reports within those categories. This is useful where a
 staff user only deals with reports of a specific type.
 
+#### Removing staff status from accounts
+
+To remove the staff status from an account visit the user page and
+uncheck the ‘staff’ checkbox. To prevent a user from logging in uncheck
+the ‘email verified’ checkbox.
+
+You can do this in bulk on the Users screen by selecting the checkbox
+next to the user's name on the users page, selecting the ‘Remove staff
+permission’ checkbox and clicking submit.
+
+Note that if a user has access to the email address associated with an
+account they can re-enable their account, but will not have staff
+permissions.
+
 #### Removing accounts
 
 To remove an account, the Administrator-level member of staff should make contact with
 mySociety.
 
+#### Two-factor authentication
+
+Any staff user can choose to set up two-factor authentication on their account.
+To do this, they will need an app on their phone that can generate time-based
+authentication keys, such as Google Authenticator or a password manager. Then.
+they can visit their account page on the site and select ‘Activate two-factor
+authentication’ to receive a QR code to scan with the app.
+
+If you wish your organisation to have mandated two-factor authentication,
+please get in touch.
+
 </div>
 
 <div class="admin-task" markdown="1" id="creating-editing-categories">
@@ -538,9 +568,11 @@ mySociety.
 
 #### Note
 
-If your FixMyStreet Pro installation has been integrated with a CRM system, this
-section does not apply. In such cases, categories are managed from within the CRM, and
-FixMyStreet will be set up to work with these.
+If your FixMyStreet Pro installation has been integrated with a CRM system,
+this section might not fully apply; it is possible categories are managed from
+within the CRM, and FixMyStreet will be set up to work with these. Some
+installations only integrate on some categories, and some sections such as form
+disabling can still be used on top of an integration.
 
 </div>
 
@@ -560,17 +592,27 @@ and staff users — can filter reports when viewing them on the site.
 From the Admin menu, click on ‘Categories’. You’ll see a table of existing categories, and below
 that, a form by which you can create new ones.
 
-
 Input a title for the category, and the email address to which reports in that category should be
 forwarded. When creating a category, these are the only fields required.
 
 You can also choose a variety of options – whether to automatically hide any
 reports made in this category, whether to prevent form submission when this
-category is selected, or what parent category or categories a particular
-category is in. See below for information on <a
+category is selected, whether updates are allowed on reports in this category,
+whether members of the public can reopen fixed/closed reports in this category,
+or what parent category or categories a particular category is in. See below
+for information on <a
 href="#creating-editing-notices">creating/editing extra notices and
 questions</a> for a category.
 
+You may also be able to configure categories to allow anonymous
+reporting if you have this option available. If this is not available then
+contact us to discuss it.
+
+Categories can be made ‘staff only’, where they are only available to logged-in
+members of staff, not members of the public. This could be used for e.g.
+contact centre staff to leave reports in categories that you still want to be
+phoned in.
+
 You can set up as many or as few categories as you like, and each category can have its own email
 address attached to it, so for example, reports about potholes may go to one council email
 address, while reports about road signs go to another. More than one category may share the
@@ -636,6 +678,50 @@ selected. This can be used to provide extra information about the category,
 point specific cases elsewhere (e.g. a phone number for urgent enquiries), or
 anything else you think the reporter may find useful.
 
+##### HTML content in notices
+
+Sometimes it can be helpful to use different text formatting or include images
+in the notices shown to users. You could, for example, include photos that
+illustrate the sorts of issues users should report in a particular category.
+
+<img alt="Screenshot illustrating how the notice can include guidance for the user as well as a comparison photo."
+    src="/assets/img/pro-user-guide/blocked-drains-guidance.png" class="admin-screenshot" />
+
+The **Notice text** field allows you to include HTML tags to apply text
+formatting, add links, or include images in the notice shown to the user. The
+above notice was generated from this HTML:
+
+```html
+We take different action depending on how a drain is blocked.<br>
+
+<span style="font-weight: normal">A blockage on the surface of a drain could be caused by leaves or litter. These blockages can usually be cleared by carrying out street sweeping.</span><br>
+
+<img src="https://www.borsetshire.gov.uk/images/BlockedDrainExamples.jpeg" alt="Compared with a surface blockage, an internal blockage could be caused by leaves, mud, or stones and need specialist equipment.">
+
+```
+
+The following HTML tags are allowed for use:
+
+ - `p`
+ - `ul`
+ - `ol`
+ - `li`
+ - `br`
+ - `b`
+ - `i`
+ - `strong`
+ - `em`
+ - `a`
+   - The following attributes are allowed: `href`, `style`, `target="_blank"`, `title`
+ - `img`
+   - The following attributes are allowed: `src`, `alt`, `width`, `height`, `hspace`, `vspace`, `align`, `sizes`, `srcset`
+   - **NB** The `alt` attribute is required if you're giving information only present in the image.
+ - `span`
+   - The following attributes are allowed: `style`
+
+Any other tags or attributes not allowed by the above list will be stripped out
+when you save your changes on the form.
+
 #### Questions
 
 A question can ask the user to provide some specific additional information
@@ -761,6 +847,19 @@ Click on ‘Templates’ in the admin menu. You will see a table of existing tem
 beside the status you wish to change. You may alter any of the fields as described in the section
 above, ‘Creating a template’. Additionally you can delete the template from this page.
 
+
+#### HTML content in templates
+
+HTML tags are permitted in response templates, which makes it possible to include
+hyperlinks or rich text formatting in the updates which are added to reports.
+
+Be aware that response templates are emailed to users as well as being shown on
+the site, so it's best to keep any HTML formatting quite light-touch due to the
+quirks of email clients' rendering of HTML message.
+
+Refer to the section ["HTML Content in notices"](#html-content-in-notices) above for details of
+what tags and attributes are allowed.
+
 </div>
 
 <div class="admin-task" markdown="1" id="view-statistics">
@@ -769,12 +868,13 @@ above, ‘Creating a template’. Additionally you can delete the template from
 
 <span class="admin-task__permissions">Permissions required: User must be marked as staff</span>
 
-When you first log in to the Admin area, you’ll see some top-level stats at the foot of the page,
-including the number of reports published on the site, the number of updates, the number of
-alerts set up and the number of user questionnaires sent out. This can be useful for a quick
-snapshot of activity.
+When you log in to the Admin area and click Stats in the admin navigation,
+you’ll see some top-level statistics, including the number of reports published
+on the site, the number of updates, and the number of alerts set up. This can
+be useful for a quick snapshot of activity.
 
-For a more detailed breakdown, visit the stats dashboard. This can be accessed by typing
+For a more detailed breakdown, visit the stats dashboard. This can be accessed
+by going to "Summary statistics" from the admin stats page, or by typing
 ‘/dashboard’ on the end of your FixMyStreet url.
 
 From here, you can access statistics on:
@@ -796,6 +896,33 @@ You can also group the results by:
 Android device or via an iOS device).
 
 These statistics can be downloaded as a CSV document, suitable for use in a spreadsheet program
-such as Excel.
+such as Excel or your own reporting tools.
+
+#### Importing dashboard data automatically
+
+You may wish to automatically import data from the dashboard into your system on a regular basis.
+Once you set your chosen criteria on the dashboard page, make a note of the URL of the "Reports"
+or "Updates" link in the "Export as CSV" section.
+Then you should generate an access token by visiting your account page and then "Security" and
+generating a token from there.
+
+You can then specify that token either by appending it to the URL as an `access_token` parameter,
+or including it as an `Authorization: Bearer <token>` HTTP header in the request from your system.
+
+The `export` must be present in the URL, and controls how the CSV is generated.
+Reports can take some time to generate, so there are two different values for the parameter:
+
+ - `export=1`: the response will wait until the file is ready and then provide it
+ - `export=2` (the default): you will immediately get a 202 HTTP response with a redirect to the location where the file will be once it has finished processing. This is more robust.
+
+#### Heatmap
+
+Also accessible from the admin stats page is our heatmap. This can provide an
+overview of reporting in your area, filtered by state, category, or ward, for a
+particular date range:
+
+<img alt="Screenshot of Bromley heatmap showing clusters in the north and north west."
+    src="https://user-images.githubusercontent.com/4776/72752804-0eb6b700-3bbb-11ea-915b-5afde5235014.png">
+
 
 </div>