Administrator’s Manual

What is it like running a FixMyStreet site? This guide explains what you can expect, and the types of problem that you might encounter. It includes examples of how mySociety manages their own site, fixmystreet.com.

About this document

We’ll be giving suggestions and examples of problems from our experience in the UK. But there is more than one way to solve issues, and you may well find that your own solutions work best.

We hope that you will contribute to this document with your own ideas and feedback. You can do this by contacting us directly, or joining the mailing list.

The FixMyStreet mailing list is a great place to share ideas or ask questions. Everyone on there has either built, or is building, a FixMyStreet site, so they have real-life knowledge and are keen to help.

It’s a friendly community, and we recommend that you join in and ask as many questions as you need to.

Other helpful documents

• Before you decide to run FixMyStreet, you should read the “Can we fix it?” DIY Guide.

• If you are hosting FixMyStreet yourself, you must read the installation instructions first. Once you’ve done that, you’ll probably need the information about customising your site too.

• This guide is just one of several useful pages for administrators in the section about running FixMyStreet. This document is the most general, so is a good place to start.

Find your administrator

Every FixMyStreet site needs an administrator. Even when the site is running smoothly, your users will need help, and there will be regular administrative tasks to perform. So, sooner rather than later, you will need to think about who will be responsible.

Who do I need?

The team who sets up the site and those who keep it running day-to-day might (or might not) be the same people.

To set up a new installation, we recommend you have at least one developer and one administrator who can work on the site.

At the beginning you’ll be quite busy. You’ll be doing a lot of things, like customising your site, collecting the email addresses your users’ problem reports will be sent to, and perhaps promoting your project.

Once your site is up and running, you can manage with just one administrator.

The administrator deals with problems and questions from users - we call this ‘user support’. He or she will also answer questions from the bodies you send your reports to.

Each day, the administrator of mySociety’s UK FixMyStreet site spends, on average, between 15 minutes and an hour on user support.

Ideally, your administrator will work every day, as there may be urgent requests (see “Types of tasks”, below). But if you cannot manage this, a couple of sessions a week will be sufficient.

Our administrator usually checks support emails twice a day, in the morning and at lunchtime. This breaks the work into very short blocks, but also ensures that she can deal with any urgent problems promptly.

The administration pages (“admin”)

Security

By default, the administration pages — the “admin” — can be found at /admin. These pages must be secured against public access.

We strongly recommend you access your admin over a secure connection, such as HTTPS. This means that everything that goes between your computer and the server is encrypted, so can’t easily be intercepted.

It’s also a good idea to allow access to admin only from your own, trusted IP addresses.

Both of these precautions require system configuration (that is, they depend on settings outside FixMyStreet). If you’re running an Apache webserver, you can do this using htauth — see the Apache htauth documentation. If you’re using an external hosting service, their technical support staff may be willing set this up for you if you can’t do it yourself.

It’s very important that you do secure your admin: so if you really do have problems setting this up, get in touch and we’ll try to help.

Contents

The Admin interface is divided into the following sections. You can access them by clicking on the link at the top of any admin page:

• Summary page
  The summary page shows the number of live reports, updates, alerts, sent questionnaires and bodies’ contacts.

  This page is useful when the media ask how many reports your site has processed. You can also use it to motivate your team, or to prove yourself to official bodies.

• Bodies
  Bodies are the authorities that your site sends reports to. Each body has its own page in the admin, listing the categories of problem that they accept (eg, potholes, street lights, etc) and the email address associated with the category.

  Bodies sometimes change their email addresses, and dealing with this is a regular task for an administrator. You can add or edit bodies from these pages. You can also add or edit their categories and contact email addresses. Bodies are associated with one or more areas. More information on bodies.

• Reports
  The reports page lets you search for, and edit problem reports and updates.

  You will need to do this often - for example, when a user has emailed to complain about a report, or to ask you to check if the report has been sent.

  You can search by the user's name, email address, or a word or phrase from the report.

  If your database is very large — like the UK FixMyStreet, which has many thousands of reports — some searches may be a little slow. But if you know the ID of the report, you can tell FixMyStreet to find it directly, using id: first. The ID is in the URL of the live report: for example, on our site, we can find https://www.fixmystreet.com/report/391267 by searching for id:391267.

• Timeline
  The timeline is a log of FixMyStreet activity: report updates, status changes, and so on.

• Survey
  By default, FixMyStreet sends out surveys (also called questionnaires) to users four weeks after they reported a problem.

  We use these surveys to collect data on the performance of the bodies. The survey page shows statistics based on the responses, which again can be useful for the media, or for research when you are looking at how effective your site has been.

  If you don't want your FixMyStreet site to send out surveys, you can switch off this behaviour in a cobrand module.

• Users
  You can manage users from this section. For example you can edit a user’s email address, or flag or ban or abusive one.

  Each user has an individual page in the admin, and it is sometimes quicker to search for a user than a report, if they have contacted you by email and have not mentioned which report they are talking about. Each user's page lists all their activity on the site.

  By default, any staff users (those that belong to a body) are listed on this page.

• Flagged
  You can flag any report or user. This does not ban the user or delete the report - it is just a way of marking a person or a situation as potentially troublesome. Note that you can only flag a report or user from the report or page.

  This can be useful if your team has more than one administrator. More information about managing users.

• Stats
  The stats page lets you analyse the number and types of report over a particular date range. Optionally, you can restrict it to report on a single body.

  You might use this if you want to know how many reports have been sent within, for example, the last three months, or how many reports have been sent to a specific body since launch.

• Configuration
  This page shows you a summary of the live configuration information for your site.

• Site message
  This page allows you to set a site message which will be displayed on the homepage.

  To clear the message simply delete any contents in the box.

Report states

A problem report can be in one of these states:

Unconfirmed

Until FixMyStreet is certain that the report's creator is genuine, its state remains unconfirmed. Unconfirmed reports do not appear on the website. A report is confirmed (and its state becomes open) when:

• its creator clicks on the link in FixMyStreet's confirmation email, or
• its creator was already logged in when the report was created, or
• an administrator confirms it (by searching in Reports and changing the state by clicking edit).

Open

An open report is one that has not been fixed or closed. This generally means that the body has not yet attended to the problem. Also, this implies that the report is not unconfirmed (see above). Staff users can set problems to have alternative "open" states, which by default are:

• investigating
• in progress
• action scheduled

This list of states can be edited in the admin interface.

Fixed

Fixed reports are marked in two possible ways:

• fixed - user
  If a user marks them as fixed in an update, or (for the report creator only) as part of the process of answering the 4-week survey.
• fixed - council
  If updated by a staff user from the body responsible for that report.

Closed

A staff user associated with the report's body (or an administrator) can mark a report as closed without declaring it to be fixed. Possible states by default are:

• no further action
• not responsible
• duplicate
• internal referral

This list of states can also be edited in the admin interface.

Hidden

Reports can be hidden by an administrator, or (if the cobrand allows it) by a staff user associated with the body to which it was sent.

Hiding a report means that it is unpublished, and can no longer be seen on the live site - usually because it is abusive or inappropriate. Hidden reports remain in the database, and can be republished if necessary.

Remember that a hidden report will probably have been sent to the body responsible (so it can still be fixed) — hiding a report simply prevents it being displayed.

Types of Tasks

There are two main types of tasks for FixMyStreet administrators.

• Maintenance tasks can be fixed through the FixMyStreet admin interface.

• User support is generally handled by email.

The most common maintenance tasks are described below, based on our own experience with the UK site.

Bounce-backs / dead email addresses from the bodies

When FixMyStreet sends a problem report to the body responsible, sometimes that email bounces back. This usually means the contact email address you've got for that body (and that category) is wrong, or has changed.

You can tell which report — and which body and category — caused the problem by looking at the returned email.

Then, in admin, go to Bodies and look at the contact email addresses for that body. Check that the email address looks correct (for example, if there are several, see if they adhere to the same format).

If everything looks OK, you can check online to see if you can find a better address. Otherwise, you'll need to contact the body and confirm the correct email address to use.

Sometimes the email address may be correct, but there's another problem which prevents it receiving the email (such as a full mailbox). Be sure to check the error message that the mail server returned in the bounce-back message.

When you have found the correct email address, make sure that you re-send the report which bounced. And if you can't find an address, you should contact the user to let them know that unfortunately you couldn't deliver their report.

Removing personal data from reports or making them anonymous

Sometimes people include personal details such as their address in their report. Or they forget to tick the box to make their reports anonymous. Sometimes a user decides to make their report anonymous after they have submitted it.

In all cases, you can edit the report in admin by going to Reports. Find the report you want, then click on Edit.

Remove the details that should not be shown (we recommend replacing them with something like “[address removed, but sent to name-of-body]”).

If necessary, you can mark the report as anonymous with the yes/no selection box.

Be sure to save your changes (click submit changes) when you've finished editing.

Removing reports when users say they didn't realise their report would be public

Occasionally people who are reporting issues don't understand that the site is public, and they don't want their name associated with the report.

In the UK, mySociety's first step is to anonymise the report. If the user insists that the report must be removed, you can hide it instead - then let your user know that you've made the changes they asked for.

We're generally happy to hide such reports because we don't want to anger our users. And although this removes them from the website, the problem report will still have been sent to the body responsible.

Removing inappropriate reports

There is a 'report abuse' link at the foot of every report, which any user can use to alert you to a report. You will sometimes receive emails to tell you that a report or update is inappropriate or potentially libellous.

UK law states that we can be held legally responsible for the content, but only if we have been made aware of it. You should make yourself familiar with the law in your own jurisdiction, and how it may affect your liability.

In most cases, if a report has been brought to your attention, you should hide it - unless there is clearly nothing wrong with it.

Abuse report emails contain the admin URL of the problem report, so you can click on it and change its state to hidden.

It's generally a good idea to then tell the user who reported the abuse that you have removed it. You may also wish to contact the abusive site member to explain why their report has been removed.

Users who send a report to the support email address

On the UK FixMyStreet site we are careful to explain that we are an independent organisation, and we do not fix street problems ourselves.

But we still frequently receive email that should have gone to a local council. In other words, people click on the 'support' button and submit a report, rather than going through the normal report-making process on the site.

We send a carefully-worded response like this:

You have emailed the technical support team behind FixMyStreet, when it looks as though you intended your message to go to your council. FixMyStreet is an independent website through which you can contact any council in the UK.

If you wish to report a problem please visit www.fixmystreet.com and enter a postcode or street name near where the problem is located. You will then be invited to click on a map to show where the problem is occurring.

Your message is below so that you can copy and paste it into the form. *Note that all messages appear on our website, as well as going to the council*.

If you are able to take the time to let us know why you emailed this address rather than file a report on the site, it would really help us to make the process clearer for future users.

You are welcome to adapt this text to your own site's needs.

Manually changing users' email addresses

Users cannot change their email addresses themselves. In admin, go to Users, find the user (search by their name or the old email address) and edit the email address to be the new one.

Common user support queries

Here is a list of the most common user support queries we get on the UK FixMyStreet site.

A body wants to know what email addresses you have on file

In the UK, it's common for each body to have multiple contacts (usually email addresses) — for more information, see About bodies and contacts. Your site may be the same.

Often, a body will make contact to ask where your reports are being sent. Perhaps they are changing addresses, or they are puzzled because they can see reports on the site but don't know who is receiving them.

It's worth being friendly and helpful - if you have a good relationship with the body, they will inform you when their contact details change, and are more likely to treat your users' reports with respect.

Note that you can quickly copy and paste all email addresses for a body by clicking on text only version on that body's page.

Body replies to you, not the user

This can happen if the body has set up their auto-response system incorrectly, for example, the body has used your support email address instead of responding directly to a user.

Forward the email to the user. Let the body know you've had to do this, and point out the correct email address to use (FixMyStreet sends its emails with the reply-to field set to that of the user who reported the problem).

Press enquiries or data/statistic enquiries

Currently any requests for data or statistics that cannot be seen on the admin summary page have to be handled by a developer, by making SQL queries directly on the database.

Staff users can see the dashboard for their own body by going to /dashboard when they are logged into the public site. If they don't have a staff user set up, offer to do this for them: see managing users.

User needs help on how to make a report on the site

Sometimes you may get an email from a user saying the site isn't working, or they can't use it. Remember that your users come from all sectors of society, including the very elderly or those who are not used to computers.

You will often need to write back to clarify the problem. Ask for as much detail as possible about their operating system and browser - in simple words - and ask them to describe the issue precisely.

Often there is no problem with the site (although you should never be certain of that until you have checked). Maybe the user has not seen the submit button, or doesn't understand how to upload a photo, or has not understood how the site works for some other reason.

Step-by-step instructions by email can almost always help.

User does not receive report confirmation email

This is almost always because the automated confirmation email has gone into the user's spam folder.

Ask the user to look in their spam folder (and mark email coming from your domain as "not spam" so future emails don't get caught in the same way). If they still can't find it, you can confirm the report from within admin (see Report States, above).

If you're running FixMyStreet on your own server, you (or your system administrator) can check your outgoing email logs to confirm that the user's mail server accepted delivery from your end.

User wants to know how to change their password

Users don't need a password to use FixMyStreet - they can click the link in the confirmation email instead. But if a user makes a large number of reports, it makes sense to have a password. If they are logged into the site, they do not have to confirm reports via the email link.

Any user can set a new password at any time.

We send this response to requests to change the password:

When you next create a problem report or update, simply choose the option that says 'No, let me confirm by email'. You will be able to create a new password at that point. This will send you a confirmation email. Clicking the link in that email will update your password for you.

Alternatively, you can visit https://www.fixmystreet.com/auth and do the same (that is, choose the 'no' option and input your new password).

Of course, make sure you change the URL in that message to match your own installation.

Note that there's no need to provide the old password, because the change requires the user to click on the confirmation link in the email.

User wants to edit their problem report

A user cannot change their message once they have submitted it — and remember that the report will have already been sent to the body responsible.

However, if there is a good case for changing the post on the website, you can do this in the admin. Go to Reports, find the report you want, and click on Edit.

Be sure to save your changes (click submit changes) when you've finished editing.

User requests a new feature or reports a bug

You can log feature requests and bug reports by submitting (or, if you prefer, by asking your developer to submit) an issue to the public FixMyStreet GitHub repository.

Always search the issues first to check that it hasn't already been raised. If it has, you can add a comment noting that it's been requested again by another user.

When users in the UK contact FixMyStreet support with a request for a new feature, we also reply to thank the person for taking an interest in the site. We really do change FixMyStreet in response to user feedback!

User can't find a relevant category for their problem

FixMyStreet constructs the list of categories of report (for example, "Pothole" or "Graffiti") based on what services the body (or bodies) in that area provide. See Managing bodies and contacts to see how this works.

This has two important consequences: it means the list of categories may be different depending on where the user is reporting the problem, and it means that sometimes the category the user wants is not available.

When you add categories for the bodies in your FixMyStreet installation, you should consider adding an "Other" category — provided, of course, that the body has a general email address for such requests to go to.

Be careful, though, because if multiple bodies at the same location offer a category called "Other", FixMyStreet — correctly — will send such reports to all of them.

To understand more about about this, see Managing bodies and contacts.

Report has gone to wrong body

Sometimes a report is sent to the wrong body because the user has placed the pin wrongly, putting the report in a different administrative jurisdiction. Or perhaps the user has chosen the wrong category, routing the report to a different body.

mySociety replies to the user asking them to resubmit the report with the pin more correctly positioned, or the right category selected.

This problem may indicate that the boundary data you are using is either incorrect, or not accurate enough — for more information, see How FixMyStreet uses MapIt.

User wants to unsubscribe from local alerts

Alerts are sent as emails: there's an unsubscribe link at the foot of each one, so usually you just need to point this out politely.

User just wants to send praise or thanks

It's nice to hear! mySociety's FixMyStreet administrator shares these with the team and will always write back to the user to thank them.

The maps are out of date because there's been new development in the user's area

Your FixMyStreet installation will normally be using maps from an external source — by default this is OpenStreetMap.

For the UK FixMyStreet, we use maps produced by the government (Ordnance Survey), and we advise our users to contact them with any errors. Other installations use custom maps too, so the remedy to this problem will be different in different locations.

OpenStreetMap is an editable project, so it is possible to encourage users — or your own team — to update the map information. It will take a while for the map tiles to update, so these changes might not appear on your own site immediately.

How the site may be abused

Any website that accepts input from the public can attract abuse - but our experience from the UK FixMyStreet site is that it’s rare. The following section discusses some issues you should be aware of.

Obscene, rude or illegal material

People may occasionally post rude, defamatory or vexatious material. Here’s our official policy from the UK FixMyStreet site:

If a user gets in touch to complain about a report, it is sometimes because they are offended or distressed by the content. Sometimes a report will contain their name and address, and may be a top result when they search for themselves on Google.

Understandably, they may be upset or angry. Once you have made any necessary modifications to the report - or removed it completely - you should reply politely and calmly. Tell the user what action you have taken, and let them know about the site policy.

It is important to make it clear that the views our users post on FixMyStreet are not the views of mySociety.

We don’t perform proactive moderation (that is, checking everything before publishing it on the site) for two reasons.

First, for the quantity of traffic we handle, it would be impractical. Second, doing so would make us liable for the content under UK law. You will need to check what the law is in your country, and how best to deal with issues such as these.

The FixMyStreet code does support moderation-before-publication, although this is currently only enabled in the Zurich cobrand.

Spam reports

Many sites which publish user-generated content suffer from spam - that is, automated bots posting messages.

On the UK FixMyStreet site, we do not receive many spam reports. Currently it is almost entirely prevented by the confirmation link process.

However, we cannot say that this will always be true, and you will need to be aware of this possibility.

If your site does start to suffer from spam, please share your experience with mySociety and the community, because it’s likely that solutions and responses to the problem will be useful to everyone.

Silly or time-wasting reports

Occasionally a user will post a nonsensical report, just for amusement.

Although such things generally seem harmless, remember that, in the age of social media, a link to amusing content can spread fast.

In the UK, we’ve had one memorable case where the comedy report was publicised in many media, and was eventually reported on the BBC website.

You may be thinking that it’s great publicity for your site, but remember that these reports do get sent through to the bodies responsible. FixMyStreet’s role as a credible source of reports may be undermined if this happens too often.

Also, unfortunately, once one silly report has been made, it often gives other users the idea to do the same.

Consequently, on the UK FixMyStreet site we have a policy of hiding such reports as soon as we are aware of them, to prevent other users being encouraged to copy the behaviour.

Abuse: conclusion

In practice, “problem users” are judged on a one-by-one basis. You can flag a user or a report as problematic, and then, if they transgress again, you can ban their email address by adding it to the “abuse list”. See managing users for details.

It’s a good idea to agree on a policy for dealing with abuse issues, and to make sure all your administrators know what it is.

Software updates

The FixMyStreet platform is under constant development. This means that new features and improvements are made from time to time: we announce new releases (which have version numbers) on the fixmystreet.org blog, and on the mailing list (see more about staying in touch).

Updating is a technical activity, and you’ll need to log into the server’s “command shell” to do it — so ask your developer to do this for you if you’re not confident.

If you’ve installed FixMyStreet as a git repository cloned from github.com/mysociety/fixmystreet — which will be the case if you’ve followed our installation instructions — your developer should find it easy to update. Make sure they know that sometimes these updates do require changes to the database schema too (look for new migration files in the db directory). Always check the version release notes (for example, on the blog) because we’ll mention such things there.

And finally…

We wish you all the best with your FixMyStreet problem reporting site.

If you have any questions, don’t hesitate to contact us and we’ll get back to you as soon as possible with an answer.