Alaveteli

EN

Glossary

Glossary of terms for Alaveteli, mySociety's freedom of information platform.

Definitions

Active Storage
A component of Rails which facilitates uploading files to a cloud storage service. It comes with a local disk-based service for development and testing and supports mirroring files to subordinate services for backups and migrations.
admin (also: administrator)
An admin, or administrator, is an Alaveteli user who has been granted the role to use all features of the admin interface.

The only way to access the admin interface without being an Alaveteli admin is as the emergency user, which should be disabled in normal operation.

More information:

  • To grant a user admin privilege, log into the admin and check "admin" in the Roles section of their user page (or revoke the privilege by unchecking it).
  • On a newly-installed Alaveteli system, you can grant yourself the admin role by using the emergency user.
admin interface
The admin interface allows users who have the admin role to manage some aspects of how your Alaveteli site runs.

More information:

  • You can access your installation's admin interface at /admin.
  • To grant a user admin privilege, log into the admin and check "admin" in the Roles section of their user page (or revoke the privilege by unchecking it).
  • On a newly-installed Alaveteli system, you can grant yourself the admin role using the emergency user.
  • For lots more about running an Alaveteli site, see the administrator's guide.
advanced search
Alaveteli's advanced search lets users search using more complex criteria than just words. This includes Boolean operators, date ranges, and specific indexes such as status:, requested_by:, status: and so on.

More information:

  • Advanced search is available on your Alaveteli site at /advancedsearch. That page shows suggestions and examples of the searches that are supported.
  • For more about constructing complex queries, see Xapian search parser.
Alaveteli
Alaveteli is the name of the open source software platform created by mySociety for submitting, managing and archiving Freedom of Information requests.

It grew from the successful FOI UK project WhatDoTheyKnow. We use the name Alaveteli to distinguish the software that runs the platform from any specific website that it is powering.

More information:

asker agnostic
Freedom of Information (FoI) law typically considers the responses given by the authorities to be asker agnostic. This means that the reply should not be any different depending on who asked for the information. One consequence of this is that the response can be published, because in theory everyone could ask for it and expect, by law, to receive the same information.

Despite this, it's still very common all around the world for authorities to reply to FoI requests privately, instead of publishing their responses themselves. One of the functions of Alaveteli is, therefore, to act as a public repository of published answers. This also serves to reduce duplicate requests, by publishing the answer instead of requiring it to be asked again.

authority
An authority is the term we use for any of the bodies, organisations, departments, or companies to which users can send requests.

More information:

  • An administrator can add, edit, or remove authorities in the admin.
  • Authorities are usually, but not always, public bodies that are obliged by the local Freedom of Information (FoI) law to respond. Sometimes an Alaveteli site is set up in a jurisdiction that does not yet have FoI law. In the UK, we add some authorities to our WhaDoTheyKnow site that are not subject to FoI law, but which have either voluntarily submitted themselves to it, or which we believe should be accountable in this way.
  • You can organise your authorities using categories and tags.
batch request
Normally, when a user submits a request, it is sent to a single authority. A batch request is when a user submits a single request that is then sent to multiple authorities. By default, this capability is not enabled, but Alaveteli does support it. To allow batch requests to be sent, you need to both enable the feature and then grant permission to use it on a user-by-user basis.

More information:

black hole
A black hole is an email address that accepts and destroys any email messages that are sent to it. Alaveteli uses this for "do not reply" emails, which are usually automatically generated system emails.

More information:

  • Use the config setting BLACKHOLE_PREFIX to specify what this email address looks like.
  • Conversely, see CONTACT_EMAIL to specify the email address to which users' emails (such as support enquiries) will be delivered.
bounce message
A bounce message is an automated electronic mail message from a mail system informing the sender of another message about a delivery problem.

More information:

Capistrano
Capistrano is a remote server automation and deployment tool written in Ruby. Alaveteli's deployment mechanism, which is optional, uses it.

More information:

categorisation game
The categorisation game is a way that users of an Alaveteli site can help the site stay current and accurate by updating the status of old requests where the original requester has never said whether the authority responded with the information or not.

More information:

category
You can arrange your authorities into categories so that they are easier for your users to find. For example, you might put all different schools into the "School" category, and universities into "Universities". You can also group categories under headings (such as "Education").

These categories and headings appear on the list of public authorities that is displayed on your site.

Use tags to associate authorities with specific categories.

More about categories and tags
censor rule
Alaveteli administrators can define censor rules to define which parts of replies or responses should be redacted.

More information:

development site (also: dev, development server)
A dev server is one that is running your Alaveteli 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.

disclosure log
Some authorities routinely publish their responses to Freedom of Information requests online. This collection of responses is called a disclosure log, and if an authority has such a log on its website, you can add the URL so Alaveteli can link to it.

More information:

emergency user
Alaveteli ships with a configuration setting for an emergency user. This provides a username and password you can use to access the admin, even though the user doesn't appear in the database.

When the system has been bootstrapped (that is, you've used the emergency user to grant a user account full admin privileges), you must disable the emergency user.

More information:

Freedom of Information (also: FOI)
Freedom of information laws allow access by the general public to data held by national governments. They establish a "right-to-know" legal process by which requests may be made for government-held information, to be received freely or at minimal cost, barring standard exceptions.
[from wikipedia]

More information:

gaze

In the absence of a GeoIP database, Alaveteli uses mySociety's gazetteer service, called Gaze, to determine each user's country from their incoming IP address. This lets the site suggest an Alaveteli site in their country, if one exists.

More information:

GeoIP database

A GeoIP database is a local store of geographical information about IP addresses. By default, Alaveteli uses a GeoIP database to determine each user's country from their incoming IP address. This lets the site suggest an Alaveteli site in their country, if one exists.

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 (Alaveteli is mostly written in the programming language Ruby), report bugs, suggest features and many other useful things.

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

More information:

holding pen
The holding pen is the conceptual place where responses that could not be delivered are held. They need attention from an administrator.

In fact, the holding pen is really a special "sticky" request that only exists to accept unmatched responses. Whenever Alaveteli receives an email but can't work out which request it is a response to, it attaches it to the holding pen instead.

More information:

  • See more about the holding pen, including why messages end up there, and instructions on what to do with them.
  • The most common reason for a response to be in the holding pen is that an authority replied to a request with the wrong email address (for example, by copying the email address incorrectly).
holidays
Alaveteli needs to know about public holidays because they affect the calculation that determines when a response is overdue. Public holidays are different all around the world, so Alaveteli lets you specify the dates for the jurisdiction relevant to your site in the admin interface.

More information:

  • See more about adding public holidays. It's possible to load dates from an iCalendar feed or accept Alaveteli's suggestions.
internationalisation (also: i18n)
Internationalisation is the way Alaveteli adapts the way it presents text based on the language or languages that your website supports. It's sometimes abbreviated as i18n (because there are 18 letters between i and n).

Often you don't need to worry about the details of how this is done because once you've configured your site's DEFAULT_LOCALE Alaveteli takes care of it for you. But when you do need to work on i18n (for example, if you're customising your site by translating it, or uploading names of the public bodies in more than one language) at the very least you may need to know the language codes your site is using.

More information:

Mail Transfer Agent (MTA)
A Mail Transfer Agent is the the program which actually sends and receives email. Alaveteli sends email on behalf of its users, and processes the responses and replies it receives. All this email goes through the MTA, which is a separate service on your system.

More information:

  • see these instructions for configuring your MTA (examples are for exim4 and postfix, two of the most common)
.po file (and .pot file)
These are the files needed by the gettext mechanism Alaveteli uses for localisation. A .pot file is effectively a list of all the strings in the application that need translating. Each .po file contains the mapping between those strings, used as keys, and their translations for one particular language. The key is called the msgid, and its corresponding translation is the msgstr.

More information:

production site (also: live, production server)
A production server is one that is running your Alaveteli 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, caching is enabled, and debugging switched off. Rails has a "production mode" which does this for you: set STAGING_SITE to 0. Note that if you change this setting after you've deployed, the rails_env.rb file that enables Rails's production mode won't be created until you run rails-post-deploy.

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 strongly recommend you use Alaveteli's deployment mechanism (using Capistrano) to make changes to your production site.

publication scheme
Some authorities have a publication scheme which makes it clear what information is readily available from them under Freedom of Information law, and how people can get it. This may be a requirement for their compliance with the law, or it may simply be good practice. If an authority has published such a scheme on its website, you can add the URL so Alaveteli can link to it.

More information:

publish
Alaveteli works by publishing the responses it receives to the Freedom of Information requests that its users send. It does this by processing the emails it receives and presenting them as pages — one per request — on the website. This makes it easy for people to find, read, link to, and share the request and the information provided in response.
recaptcha
Recaptcha is a mechanism that deters non-human users, such as automated bots, from submitting requests automatically. It requires the (human) user to identify a pattern of letters presented in an image, which is difficult or impossible for a non-human to do. Alaveteli uses this to prevent incoming spam.

More information:

redacting (also: redaction)
Redacting means removing or hiding part of a message so it cannot be read: you are effectively removing part of a document from your site.

This may be necessary for a variety of reasons. For example, a user may accidentally put personal information into their request, or an authority may include it in their response. You may also need to redact parts of requests or responses that are libellous or legally sensitive.

More information:

  • redaction is just one way to hide sensitive information — see more about hiding information on Alaveteli
  • more about redacting, including instructions for setting up censor rules
  • some things are easier to redact than others — especially in PDFs, things like signatures or images can be difficult to partially remove. In such cases, you may need to remove the document entirely.
regular expression (also: regexp)
A regular expression is a concise way to describe a pattern or sequence of characters, letters or words. As an administrator, you may find regular expressions useful if you need to define censor rules. For example, instead of redacting just one specific phrase, you can describe a whole range of similar phrases with one single regular expression.

Regular expressions can be complicated, but also powerful. If you're not familiar with using them, it's easy to make mistakes. Be careful!

More information:

  • for example, the regular expression Jo(e|ey|seph)\s+Blogg?s would match names including "Joe Bloggs", "Joey Bloggs" and "Joseph Blogs", but not "John Bloggs".
  • see Regular Expressions on wikibooks for more information
release (also: release manager)
We issue new releases of the Alaveteli code whenever key work (new features, improvements, bugfixes, and so on) have been added to the core code. Releases are identified by their tag, which comprises two or three numbers: major, minor, and — if necessary — a patch number. We recommend you always use the latest version. The process is handled by the Alaveteli release manager, who decides what changes are to be included in the current release, and the cut-off date for the work. Currently this is Alaveteli's lead developer at mySociety.

More information:

request
In Alaveteli, a request is the Freedom of Information request that a user enters, and which the site then emails to the relevant authority. Alaveteli automatically publishes the responses to all the requests it sends.
response
A response is the email sent by an authority in reply to a user's requests.
Ruby on Rails (also: Rails)
Alaveteli is written in the Ruby programming language, using the web application framework "Ruby on Rails".

More information:

Sass (for generating CSS)
Alaveteli's cascading stylesheets (CSS) control how the pages appear, and are defined using Sass. It's technically a CSS extension language, and we use it because it's easier to manage than writing CSS directly (for example, Sass lets you easily make a single change that will be applied to many elements across the whole site). Rails notices if you change any of the Sass files, and automatically re-generates the CSS files that the website uses.

More information:

spam address list
Alaveteli maintains a spam address list. Any incoming message to an email address on that list will be rejected and won't appear in the admin interface.

This is mainly for email addresses whose messages are ending up in the holding pen, because those are typically addresses that can be safely ignored as they do not relate to an active request.

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 production or staging servers. We strongly recommend you use Alaveteli's deployment mechanism (using Capistrano) to make changes to these sites.

state
Each request passes through different states as it progresses through the system. States help Alaveteli administrators, as well as the public, understand the current situation with any request and what action, if any, is required.

The states available can be customised within your site's theme.

More information:

tag
A tag is a keyword added to an authority. Tags are searchable, so can be useful to help users find authorities based by topic or even unique data (for example, in the WhatDoTheyKnow we tag every registered charity with its official charity number). You can also use tags to assign authorities to categories.

More information:

takedown request
A takedown request is an appeal from someone asking or demanding that you remove information from your site. This may be because a response you have published contains illegal, personal, or sensitive information. Takedown requests may be made by people involved in the request or response, but can also be from third parties who are affected in some way by the information published.

Because Alaveteli automatically publishes messages, if a response or message contains inappropriate information, it will be published. So takedown requests often have merit, and part of the role of the admin team is to handle them quickly and fairly.

More information:

theme
A theme is the collection of changes to the templates and the code that causes the site to look or behave differently from the default. Typically you'll need a theme to make Alaveteli show your own brand.

More information:

Transifex
Transifex is a website that helps translators add translations for software projects.

More information:

WhatDoTheyKnow
The website WhatDoTheyKnow.com is the UK installation of Alaveteli, run by mySociety.

In fact, WhatDoTheyKnow predates Alaveteli because the site started in 2008, and was the foundation of the redeployable, customisable Alaveteli platform released in 2011.

More information: