Glossary of terms for Alaveteli, mySociety's freedom of information
platform.
Definitions
-----------
-
admin interface (also: admin)
-
The admin interface allows users who have
super
administrator privilege 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 change
their Admin level to "super" (or revoke the privilege
by changing it to "none").
-
On a newly-installed Alaveteli system, you can grant yourself
emergency
user.
-
For lots more about running an Alaveteli site, see the
adminstrator'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.
-
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 authorites 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.
-
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.
-
Capistrano
-
Capistrano is a remote server automation and deployment tool written in Ruby.
Alaveteli's deployment mechanism, which is optional, uses it.
-
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
-
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.
-
censor rule
-
Alaveteli administrators can define censor rules to define
which parts of replies or responses should be
redacted.
More information:
-
see the
admin manual
for more about censor rules
-
censor rules may simply redact text that exactly matches a
particular sentence or phrase, or may use
regular expressions
-
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.
-
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 super privileges), you must disable the emergency
user.
-
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]
-
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.
-
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 you're site is using.
-
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 seperate service on your system.
More information:
-
see these instructions for configuring your MTA
(examples are for exim4 and postfix, two of the most common)
-
New Relic
-
Alaveteli can use New Relic's application monitoring tool to track the
performance of your production site. If enabled,
data from your application is gathered on the New Relic website, which you can inspect with
their visual tools. Basic use is free.
More information:
-
use the
agent_enabled: setting in the
the newrelic.yml config file to enable the New Relic analytics.
See the manual installation instructions.
-
see also the New Relic Ruby Agent github repo and
documentation
-
the New Relic website: if you've enabled the service,
you can log in to inspect the perfomance analytics
-
.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.
-
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.
-
publish
-
Alaveteli works by publishing the
responses it recieves 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.
-
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.
-
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.
-
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:
-
see the
admin manual
for more about how and when you may need to redact information
-
you can do text-only redaction with Alaveteli's
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.
-
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".
-
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.
-
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.
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.
-
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.
-
superuser (also: super privilege, administrator)
-
A superuser, or administrator, is an
Alaveteli user who has been granted the privilege to use all features of the
admin interface.
The only way to access the admin without being an Alaveteli superuser
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 change
their Admin level to "super" (or revoke the privilege
by changing it to "none").
-
On a newly-installed Alaveteli system, you can grant yourself
admin privilege by using the
emergency
user.
-
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.
-
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.
-
Transifex
-
Transifex is a website that helps translators add translations for software projects.
-
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 plattorm released in 2011.