FixMyStreet: Platform

FixMyStreet glossary

Glossary of terms for FixMyStreet, mySociety's geographic problem reporting platform.

The FixMyStreet Platform is an open source project to help people run websites for reporting common street problems such as potholes and broken street lights to an appropriate authority. For technical information, see fixmystreet.org.

Definitions

abuse list (also banning)
The abuse list is a list of email addresses that are banned from using the site for misuse. In our experience, this is rare; but, for example, a user who repeatedly posts offensive or vexatious problem reports may be blocked in this way.

More information:

  • See About users for more about managing abusive users.
administrator
An administrator is a user who has access to the back-end admin (so can do things like add or edit bodies, modify problem reports, and manage users). An administrator should also have access to the email account to which user support emails are sent.

Depending on how the site has been configured, this may be a regular FixMyStreet user. However, often it's an htauth user instead (which is a user managed by the webserver, rather than the FixMyStreet application itself).

More information:

alert
FixMyStreet users can subscribe to emails (or RSS feeds) which will notify them when reports or updates are made within a certain area. These notifications are called alerts.

Users can subscribe to various alerts - for example, all reports made within a body, or within a certain distance of their chosen location

Alerts are available on the FixMyStreet site at /alert.

area (also administrative boundary)
FixMyStreet uses areas to determine which bodies are responsible for handling problems at a specific location. When a user clicks on the map, FixMyStreet finds all the bodies that are responsible for that area. Technically, an area comprises one or more polygons on a map — either those areas already exist (from OpenStreetMap, for example) or you can provide your own. You can add your own areas to MapIt by drawing them on a map, or importing shapefiles from other mapping applications.

The MAPIT_ID_WHITELIST config setting can explicitly list the only areas your installation will recognise — alternatively, you can limit them by area type instead.

More information:

area type
The areas that MapIt returns are administrative boundaries. In addition to each boundary's geometry (that is, its actual shape on the map), MapIt also identifies what area type it is. The area type indicates what level of administrative boundary that area represents — for example, a national border, or the boundary of a province, or a ward, and so on.

The MAPIT_TYPES config setting specifies the area types your installation uses.

These types' actual values vary depending on the source of the data. For example, if you're using our global MapIt, these will look like O02, O03, O04 and so on (because those are the values OpenStreetMap uses, from where global MapIt gets its data). OpenStreetMap's codes get higher as the boundaries get more local: O02 indicates a national boundary, codes O03 and above are for subnational areas. The exact meaning of such boundaries varies according to the administrative hierarchy of the specific country.

More information:

body
A body is the authority responsible for a problem. Bodies can be councils, local government departments (such as the Department of Public Works, or the Highways Department), or even private companies that are paid to fix particular problems.

More information:

Catalyst (Perl framework)
FixMyStreet is written in Perl, and uses the Catalyst framework. For basic customisation you don't need to write any Perl — you can get a site up and running with your own colours, logo, and location without needing to do any programming. But if you do need to look into the source code, you'll find the Catalyst framework helps, because it's a "Model-View-Controller" framework (which is common in web applications).

More information:

category
Categories describe the different types of problem that a user can report, for example, "Pothole", or "Graffiti". The names of these categories are displayed in the drop-down menu when the user reports a problem. FixMyStreet uses the category, together with the area, to determine which contact will be sent the report.

More information:

cobrand
FixMyStreet uses a system of cobranding to customise the way the site looks and behaves. This can be as simple as changing the colour scheme and logo, right through to overriding specific behaviour with custom Perl code. Each cobrand has a name which the FixMyStreet code uses when deciding which style and behaviour to apply.

For a live example of cobranding, consider two sites in the UK. Our FixMyStreet site runs with the fixmystreet cobrand, which has a yellow-and-asphalt appearance, and has an example street from the city of Manchester in the "enter a street name" box. But the Oxfordshire site is running the oxfordshire cobrand, which makes the site green and suggests a street name from Oxfordshire.

More information:

config variable (also config setting, or config option)
A config variable is one of the settings in the configuration file conf/general.yml. Config variables affect the way your FixMyStreet installation behaves, and you must make sure they are correct when you install and customise your site.

Note that conf/general.yml is not in the git repository (it cannot be, because it would contain your own private config settings, such as your database password). Instead, there is an example file, cong/general.yml-example you can copy and edit. If you install using an automated method such as the installation script or Docker, this file will automatically be created for you.

More information:

contact
Each body has one or more contacts to which reports are sent. Typically these are email addresses (but if you have integrated with the body's back-end, these may be codes or IDs used by that instead of email addresses). It's not uncommon for a body to have many contacts with the same email address, but with different categories.

More information:

council
A council is an example of a body. We sometimes use the term because in the UK, where we first launched FixMyStreet, the bodies to which the site sends its problem reports were all called councils.
dashboard
The dashboard shows a summary of statistics (numbers of problem reports by state, and so on) for a single body.

The dashboard is shown on the FixMyStreet website at /dashboard, but can only be accessed by a staff user.

development site (also: dev, development server)
A dev server is one that is running your FixMyStreet site so you can customise it, experiment with different settings, and test that it does what you expect. This is different from a production server, which is the one your users actually visit running with live data, or a staging server, which is used for testing code before it goes live.

On your dev server, you should set STAGING_SITE to 1.

devolved contacts
Normally, you specifiy the send method for a whole body, so all its problem reports will be sent in that way. But you can devolve the decision of which send method to use to the body's contacts instead. For example, this lets you mix both email addresses and Open311 service codes within the same body.

More information:

flagged
A report or a user can be flagged if an administrator wants to mark it as for special attention, typically because it may be abusive or inappropriate. Flagged items are shown in the admin on their own page (/admim/flagged) so can be more easily managed. This is especially useful if you have more than one administrator, as you can see whether other administrators have marked the user or report as problematic.

Flagging users is only advisory: it marks them for attention, but does not ban them. You can ban a user who persists in abusing your FixMyStreet site by adding them to the abuse list.

More information:

  • See About users for more about managing abusive users.
geocoder
The geocoder turns the name of a place into a long-lat position. FixMyStreet then uses this to display the appropriate region on the map.

FixMyStreet can use the OpenStreetMap, Google, or Bing geocoders, or a custom one. The GEOCODER setting controls which one your site uses.

More information:

gettext
gettext is a set of utitlies provided by the GNU project to help get translations into software. We use it throughout FixMyStreet so that anywhere English text appears (the default), it can be replaced with an appropriate translation in a different language. This presupposes the text has been translated — the alternative translations are storied in .po files.

More information:

git (also GitHub, git repository, and git repo)
We use a popular source code control system called git. This helps us track changes to the code, and also makes it easy for other people to duplicate and even contribute to our software.

The website github.com is a central, public place where we make our software available. Because it's Open Source, you can inspect the code there (FixMyStreet is mostly written in the programming language Perl), report bugs, suggest features and many other useful things.

The entire set of files that form the FixMyStreet platform is called the git repository or repo. When you install FixMyStreet, you are effectively cloning our repository on your own machine.

More information:

integration with bodies' back-end systems
By default, FixMyStreet sends problem reports by email. The disadvantage of using email is that many bodies then need to transfer the information in the email into their own back-end systems, such as their works database or customer management system. But FixMyStreet can be integrated with those back ends so the data is passed directly into them, instead of via email.

There are three levels of integration:

  1. problems reports are injected directly into the back end
  2. updates made in the back end are automatically passed back into FixMyStreet
  3. problem reports created in the back end (that is, not initiated on FixMyStreet) are passed into FixMyStreet

Integration is often related to cobranding, which is how you can customise the look and behaviour of your FixMyStreet installation.

More information:

KML (Keyhole Markup Language)
KML is an open standard XML format for geographic data. MapIt can read KML files. If you need to provide your own admin boundary data, you can use common GIS software (such as Google Earth) to create a KML "shape file" containing the boundaries, and then import them to MapIt.

More information:

lat-long
A lat-long is a pair of coordinates (latitude and longitude) that describe a location. FixMyStreet sends a lat-long to MapIt when the user clicks on the map.

Example lat-long for London, UK: 51.5072759,-0.1276597

locale
A locale defines the way things like language, date formats, and currency should be handled. Locales are identified by codes like en_GB or hr_HR (these are actually language and region codes). If you need your installation to present FixMyStreet using anything other than the default English translations, then the locale you want must be installed on your server (note — this is about your server's configuration, not a FixMyStreet setting). It's common for servers to support many locales, but not all locales are installed by default.

More information:

  • See more about customising your installation, which includes language and translation considerations
  • To see what locales your server currently supports, do locale -a. You can generate missing locales with locale-gen — for example, sudo locale-gen fr_FR.UTF-8
map
FixMyStreet displays a map so users can easily pinpoint the location of the problem they are reporting. By default, these are OpenStreetMap tiles displayed using OpenLayers, but you can configure your installation to use other maps, including your own custom tiles.

More information:

  • OpenLayers, the JavaScript map library FixMyStreet uses by default
  • Leaflet, another JS map library
MapIt
MapIt is a web service that manages administrative boundary areas. More specifically, FixMyStreet uses this to determine which areas (and hence which bodies) cover any given location.

In a nutshell, MapIt accepts a lat-long position, and returns a list of areas.

Like FixMyStreet, MapIt is a product by mySociety.

More information:

Message Manager
Message Manager is a mySociety web application that can integrate an SMS gateway with FixMyStreet.

More information:

Open311
Open311 is an open standard for making online requests for a civic service (such as fixing a pothole). FixMyStreet implements Open311 so it's easy to integrate with bodies whose back-ends also support it.

Open311 is effectively a more efficient alternative to email as a send method.

More information:

OpenStreetMap (OSM)
OpenStreetMap is a project that creates and distributes free geographic data for the world, with an open license. By default, FixMyStreet's map uses OSM maps.

More information:

partial report
Some external applications might create a report by first uploading a photograph and capturing a description, without identifying the location. This is a partial report and is not shown until it has been completed.

FixMyStreet itself does not create partial reports, because all problem reports created within the application always include a location.

More information:

problem report
When a FixMyStreet user reports a problem (for example, a pothole or a broken streetlight), that problem report is sent to the body responsible. Problem reports remain unpublished until the user confirms them; they may also be hidden by an administrator. In both cases, the report is still stored in FixMyStreet's back-end database.

Users may choose to submit their report anonymously. This means that their name is not displayed on the website, although it is still sent to the body.

A report may include a photograph.

More information:

production site (also: live, production server)
A production server is one that is running your FixMyStreet site for real users, with live data. This is different from a development server, which you use make your customisation and environment changes and try to get them to all work OK, or a staging server, which is used for testing code and configuration after it's been finished but before it goes live.

Your production site should be configured to run as efficiently as possible: for example, with caching disabled, and debugging switched off. Make sure you set STAGING_SITE to 0.

If you have a staging server, the system environment of your staging and production servers should be identical.

You should never need to edit code directly on your production server. We recommend you make any changes to the program code on your development server, add it to the appropriate branch, test it on a staging server, and then deploy it directly — that is, from the repo — on production.

send method
The send method is the way that a problem report is sent to the body responsible for fixing it. By default, the send method is email.

Alternatives to email are only available if some integration with the target body's back-end is available (for example, if they are using Open311).

More information:

staging server (also: staging site)
A staging server is one that you use for testing code or configuration before it goes live. This is different from a development server, on which you change the code and settings to make everything work, or the production server, which is the site your users visit running with live data.

On your staging server, you should set STAGING_SITE to 1.

If you have a staging server, the system environment of your staging and production servers should be identical.

You should never need to edit code directly on your staging or production servers. We recommend you make any changes to the program code on your development server, add it to the appropriate branch, and then deploy it directly — that is, from the repo — on staging.

state
A problem report can go through several states in its lifetime. Problems typically start as unconfirmed, then open, then fixed. There are other states, including those that can only be allocated by a staff user or an administrator.

More information:

staff user
A staff user is someone on FixMyStreet who works for a body. This means their user account is marked as belonging to that body. This differentiates such accounts from normal users, who are members of the public.

A staff user is not the same thing as an administrator. A staff user logs into the public website, like a normal user, but has additional powers over some reports. An administrator logs into the private admin and has access to how the whole FixMyStreet site is run.

A staff user has additional powers that only apply to problem reports for their own body, such as:

  • hiding reports
  • setting state of reports to things other than just fixed and not fixed
  • viewing a dashboard showing the body's statistics

Actually, the distinction between an administrator and a staff user, and the powers staff users have, can vary depending on your installation's cobrand.

More information:

  • compare staff user to administrator
  • See About users for more about managing users, including how to create a staff account.
SMS (Short Message Service, or texting)
SMS is the service for sending text messages across a phone network. FixMyStreet is primarily a web-based application, but it is possible to run it so that it can accept problem reports over SMS too.

An SMS gateway is a service that passes SMS messages between the phone network and the internet. This allows you to receive or send messages from a web application, such as FixMyStreet.

More information:

survey (or questionnaire)
By default, FixMyStreet sends out surveys (also called questionnaires) to users four weeks after they reported a problem. The surveys encourage the users who reported each problem to indicate whether or not the problem has been fixed (if it hasn't already been marked as such). These surveys help you collect data on the performance of the bodies.

More information:

  • more about surveys
  • Survey data is available to administrators on the Survey page of the admin
  • Survey templates are in /templates/email/default/questionnaire.txt and /templates/web/base/questionnaire
  • If you don't want your FixMyStreet site to send out surveys, you can switch off this behaviour in a cobrand module.
template
FixMyStreet creates its web pages (and emails) using templates. If you want to customise your installation beyond just changing the colours and logo (that is, using CSS), you can add new templates for your own cobrand. You only need to create templates that are different from the default ones.

Templates are in the templates/web and templates/email directories — themselves containing directories for every cobrand.

The web templates use the popular Template Toolkit system. You can change the templates without needing to know how to write Perl (the programming language the rest of FixMyStreet is written in).

More information:

token (also confirmation link)
By default, FixMyStreet uses confirmation emails containing links as authorisation where the user is not already logged in. The links contain unique tokens (these look like runs of random letters and numbers).

If text authentication is switched on, authentication can also be performed by text, sending a numeric code to enter in order to proceed.

Tokens are typically used to confirm the final part (authorisation) of an action, and are therefore often related to a specific report. FixMyStreet generally doesn't delete tokens after they've been used because (as they often live on in email inboxes) people sometimes click on old confirmation links to access reports — so the mapping between token and report is still useful.

More information:

  • Tokens are implemented using AuthToken from mySociety's commonlib common library.
  • For details about authorisation and how sessions work, see more about users.
update
Anyone can add an update to an existing problem report. The update can contain a message, a picture, and even change the report's state.

For example, someone can leave an update on a pothole report to say, "I think the hole is getting bigger!", and add a photograph. Or they can mark the problem as fixed.

Staff users can add more specific states if they update a problem that belongs to the body they work for.

More information:

  • FixMyStreet supports integration, which can enable automatic updates whenever a body fixes a problem.
user account
FixMyStreet creates a user account for every user, identified by the user's email address. An administrator can change the email address, and the name, of a user account. Optionally, a user account can have a password associated with it too.

More information: