diff options
Diffstat (limited to 'docs/running')
| -rw-r--r-- | docs/running/admin_manual.md | 61 | ||||
| -rw-r--r-- | docs/running/categories_and_tags.md | 196 |
2 files changed, 256 insertions, 1 deletions
diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index d18c1c8f9..dbe8be3d1 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -31,6 +31,7 @@ In this guide: <ul> <li><a href="#administrator-privileges-and-accessing-the-admin-interface">Administrator privileges and accessing the admin interface</a></li> <li><a href="#removing-a-message-from-the-holding-pen">Removing a message from the 'Holding Pen'</a></li> + <li><a href="#rejecting-spam-that-arrives-in-the-holding-pen">Rejecting spam that arrives in the holding pen</a></li> <li><a href="#creating-changing-and-uploading-public-authority-data">Creating, changing and uploading public authority data</a></li> <li><a href="#banning-a-user">Banning a user</a></li> <li><a href="#deleting-a-request">Deleting a request</a></li> @@ -403,6 +404,65 @@ another request** button. The message will now be associated with the correct request. It is no longer in the holding pen, and is shown instead on the public request page. +### Rejecting spam that arrives in the holding pen + +Alaveteli maintains a +<a href="{{ site.baseurl }}docs/glossary/#spam-address-list" class="glossary__link">spam address list</a>. +Any incoming message to an email address on that list +*that would otherwise be put in the holding pen* will be rejected and won't +appear in the admin. + +If you see spam messages in the +<a href="{{ site.baseurl }}docs/glossary/#holding_pen" class="glossary__link">holding pen</a>, +check if they are being sent to a *specific* email address. If they are, that +email address has become a "spam-target" and you should add it to the spam +address list. Thereafter, Alaveteli will automatically reject any messages that +come to that address. + +An email address that is not associated with a request (that is, one whose +messages end up in the holding pen) becomes a spam-target once it's been +harvested by spammers. There are several reasons why such an invalid address +might exist — perhaps it was mis-spelled in a manual reply, for example. +Our experience from running +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +is that you can safely dismiss incoming email to such addresses once they have +been targeted in this way. Legitimate emails that arrive in the holding pen +tend to be unique errors (for example, missing the last character of the email +address due to a cut-and-paste mistake) and the nature of the lifecycle of +requests means they don't typically get used for spam until they are +effectively dead. + +To add an email address to the spam address list you need to copy it from an +incoming message and paste it into the spam addresss list. The easiest way to +do this is to click on **Summary** at the top of any admin page, and then click +on **Put misdelivered responses with the right requests** to see the contents +of the holding pen. + +<div class="attention-box info"> + If there are no messages in the holding pen, Alaveteli won't show you this + link. Great — there are no misdelivered responses needing your + attention right now! +</div> + +Inside the holding pen, you'll see the list of emails awaiting attention +— click on an email's subject line to see the whole message and its +details. Copy the `To:` email address, then click on the **Spam Addresses** +link under *Actions*. Paste the email address into the text input and click the +**Add Spam Address** button. + +You can see the spam address list (that is, all known spam-target email +addresses) at any time by going to the admin interface at `/admin/spam_addresses`. + +You can remove any address from the list by clicking the **Remove** button +next to it. Of course, this won't restore any messages that have been +rejected, but Alaveteli will not reject any new messages that are sent to +this address. + +Note that if you are seeing consistent spam email in your holding pen, you +should also consider implementing (or increasing) the anti-spam measures +running in your +<a href="{{ site.baseurl }}docs/glossary/#mta" class="glossary__link">MTA</a>. + ### Creating, changing and uploading public authority data There are three ways to change public authority data on your site: @@ -719,4 +779,3 @@ text you wish to replace it with e.g. '[personal information has been hidden]', and a comment letting other admins know why you have hidden the information. - diff --git a/docs/running/categories_and_tags.md b/docs/running/categories_and_tags.md new file mode 100644 index 000000000..f34c8fec3 --- /dev/null +++ b/docs/running/categories_and_tags.md @@ -0,0 +1,196 @@ +--- +layout: page +title: Categories & tags +--- + +# Categories and tags for authorities + +<p class="lead"> + + Use tags to arrange + <a href="{{ site.baseurl }}docs/glossary/#authority" + class="glossary__link">authorities</a> into categories, or to associate + related authorities with each other. This helps your users find the right + authority for the + <a href="{{ site.baseurl }}docs/glossary/#request" class="glossary__link">request</a> + (or <a href="{{ site.baseurl }}docs/glossary/#response" class="glossary__link">response</a>) + they are interested in. +</p> + +## Categories & category headings + +Alaveteli lets you organise your authorities into *categories*. Categories can +themselves belong to *category headings*. For example, some of the categories +and headings on +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>'s +<a href="https://www.whatdotheyknow.com/body/list/all">View authorities</a> page look like this: + +> * **Media and culture** +> * Media +> * Museums and galleries +> * **Military and security services** +> * Armed Forces +> * Military colleges +> * Security services +> * **Emergency services** +> * Police forces +> * Fire & rescue services + + +In this example, "Emergency services" is a heading which contains the categories +"Police forces" and "Fire & rescue services". + +Tags are simply searchable words that you can add to an authority. Nominate a +tag for each category: any authority which has that tag is automatically +assigned to the category. For example, if the tag `police` is associated with +the category "Police forces", any authority which has the tag `police` will +appear in that category. + +Make sure you choose good category headings and names, because they help your +users find the specific authorities they are looking for. + +<div class="attention-box info"> + Try to use simple but descriptive words for tags. Tags cannot contain spaces + (use an underscore if you need to, <code>like_this</code>). + Remember that tags will be seen and used by the public (for example, in the + <a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a>). +</div> + +### Adding a new category + +In the admin interface, click on **Categories**. It's a good idea to create +category headings first (but don't worry if you don't — you can change +them later). + +Click on **New category heading**, enter a name (for example, "Emergency +services") and click **Create**. + +To create a category, click on **New category**. As well as providing a title +and a description, you must enter a category tag. Any authority with this tag +will be assigned to this category. + +Select the checkbox next to the category heading under which you want this +category to be listed. It's common for a category to be under just one heading. +But sometimes it makes sense for a category to go under more than one, so you +can select multiple checkboxes if you need to. + +Click **Save** to create the category. + +### Editing or deleting a category + +Click on **Categories** then find the category in the list (if the category is +under a heading, you may need to click on the heading's chevron to expand the +list to show it). Click the name of the category to select it. You can edit it +and click **Save**. + +If you want to destroy a category, go to edit it but instead of saving it, +click on the **Destroy** button at the bottom of the page. This does not +delete any authorities in that category — they simply no longer belong to +it. + +## Special tags + +Some tags are special. Alaveteli behaves differently when an authority has one +of these tags. + +<table class="table"> + <tr> + <th> + Tag + </th> + <th> + Effect + </th> + </tr> + <tr> + <td> + <code>site_administration</code> + </td> + <td> + This is a test/dummy authority. It is not displayed to the public on your + main site, and it is not included when you + <a href="{{ site.baseurl }}docs/running/admin_manual/#creating-changing-and-uploading-public-authority-data">export authorities in CSV format</a>. + </td> + </tr> + <tr> + <td> + <code>defunct</code> + </td> + <td> + This authority no longer operates: new requests cannot be sent to an + authority with this tag. + </td> + </tr> + <tr> + <td> + <code>not_apply</code> + </td> + <td> + <a href="{{ site.baseurl }}docs/glossary/#foi" class="glossary__link">Freedom of Information</a> + law does not apply to this authority: new requests cannot be sent to an + authority with this tag. + </td> + </tr> + <tr> + <td> + <code>eir_only</code> + </td> + <td> + <em>Custom example:</em> (see below)<br> + On our UK installation of Alaveteli, + <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a>, + this tag indicates that the authority is subject to an alternative law + (Environment Information Regulations, rather than the Freedom of + Information), which means Alaveteli must change the wording of these + requests appropriately. + </td> + </tr> + <tr> + <td> + <code>school</code> + </td> + <td> + <em>Custom example:</em> (see below)<br> + <a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> + applies a different definition of "late" if an authority has the <code>school</code> tag. + </td> + </tr> +</table> + +## Custom tags and custom behaviour + +You can add any tag you want — they don't have to be associated with +categories. + +If you are a developer, and you want to add special behaviour to your site +based on your own tags, you need to add custom code, which should probably go +in your own +<a href="{{ site.baseurl}}docs/glossary/#theme" class="glossary__link">theme</a>. +For example, in the UK, schools are granted special concession in the law to allow for +requests that are made out of term-time. Alaveteli handles this by using the +[`SPECIAL_REPLY_VERY_LATE_AFTER_DAYS`]({{ site.baseurl }}docs/customising/config/#special_reply_very_late_after_days) +config value if the authority has the `school` tag. +See +[`is_school?`](https://github.com/mysociety/alaveteli/blob/f0bbeb4abf4bf07e5cfb46668f39bbff72ed7210/app/models/public_body.rb#L391) +and +[`date_very_overdue_after`](https://github.com/mysociety/alaveteli/blob/81b778622ed47e24a2dea59c0529d1f928c68a58/app/models/info_request.rb#L752) +for the source code. + +## Searching with tags + +Alaveteli's +<a href="{{ site.baseurl }}docs/glossary/#advanced-search" class="glossary__link">advanced search</a> +feature (which is available to all your users) can search for specific tags. So +if you add useful tags and publicise them, your users can use them to find +related authorities. For example, see the <a +href="https://www.whatdotheyknow.com/advancedsearch">advanced search on +WhatDoTheyKnow</a> to see this at work. + +You can add reference numbers or specific values to tags using a colon. On +<a href="{{ site.baseurl }}docs/glossary/#wdtk" class="glossary__link">WhatDoTheyKnow</a> +we tag all authorities that are charities with the tag `charity:123456` (where +123456 is the authority's registered charity number). + + + + |