From 68c35ba1d9e705747b9e99d2ba4059760c72ec2c Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Fri, 27 Feb 2015 13:55:16 +0000 Subject: add page about admin requests (really: edit metadata) Haven't added this is to the nav menu yet, just to give the dev team a chance to correct any factual howlers, will do so later --- docs/running/requests.md | 208 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 docs/running/requests.md (limited to 'docs/running') diff --git a/docs/running/requests.md b/docs/running/requests.md new file mode 100644 index 000000000..d3733b591 --- /dev/null +++ b/docs/running/requests.md @@ -0,0 +1,208 @@ +--- +layout: page +title: Managing requests +--- + +# Managing Requests + + +

+ Alaveteli makes it easy for a user to make a + request. + As an + administrator, + there are some things about that request you can change once it's been created. +

+ +A request is automatically created when a user submits and (where necessary) +confirms it. Alaveteli sends it to the authority responsible and handles any +responses. +Usually this process runs without needing any intervention from an +administrator. But sometimes you'll want to change some aspect of the +request, or the way Alaveteli is handling it. + +## What state is the request in? + +Every request moves through a series of +states, +indicating its progress. Usually a new request will be in the `waiting_response` +state until something happens to change that — for example, a response is +received. + +However, states can't always be set automatically, because they require a +decision to be made on what kind of answer the authority provided in the +response. For states like this, Alaveteli invites the original requester to +describe its state — for example, when a response is received they can +change the state to `successful`, `partially_successful` or `not_held` (if the +authority replied to say they don't have the information requested). + +
+ If a request has been waiting for over three weeks for the original + requester to describe it but has still not been described, Alaveteli + lets anyone classify it. +
+ +Internally, Alaveteli does not just record the "described state" of a request, +but also notices if anything has happened since it was last described and +sets its "awaiting description" status appropriately. + + +## Changing things about a request + + +To change any of these settings, go to the +admin interface, +click on **Requests**, then click on the title of the request you want to affect. +Click the **Edit metadata** button. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ What you can change + + Details +
+ Title + + The title is shown on the request's page, but is also used in the URL + (the text is changed to lower case, punctuation is removed and, if + necessary, a number is added for disambiguation — this is called + the "slug"). +

+ Note that changing the title changes the URL, because the slug changes + — this means any links to the old URL will no longer + work, and will return a 404 (file not found) error. +

+
+ Who can see it? + + Change the Prominence setting to one of: +
    +
  • normal
    • +
  • + backpage: request can be seen by anyone (by visiting + its URL, for example) but does not appear in lists, or search results +
    • +
  • + requester_only: request only visible to the person who + made the request +
    • +
  • + hidden: request is never shown (except to administrators) +
    • +
+
+
+ Who can respond? + + The Allow new responses from... setting can be one of: +
    +
  • anybody
    • +
  • + authority_only: responses are allowed if they come + from the authority to which the request was sent, or from any domain + from which a a response has already been accepted +
    • +
  • + nobody: no responses are allowed on this request +
    • +
+ Any response from a sender who has been disallowed by this + setting will be rejected (see next entry). +
+ What happens to rejected responses? + + The Handle rejected responses... setting specificies what happens + to responses that are not allowed (see previous entry): +
    +
  • + bounce: responses are sent back to their sender +
    • +
  • + holding pen: responses are put in the + holding pen for an administrator to deal with +
    • +
  • + blackhole: responses are destroyed by being sent to a + black hole +
    • +
+
+ What state is it in? + + See more about + request states, which can be customised for your installation. +

+ You can force the state of the request by choosing it explicitly. + Change the Described state setting. +

+

+ You may also need to set Awaiting description if, + having changed the state, you want the original requester to update the + description. For example, if the state depends on the information + within the response, and you want the requester to classify it — + see + What state is the request in? + above. +

+
+ Are comments allowed? + + The Are comments allowed? setting simply you choose to + allow or forbid annotations and comments on this request. + +
+
+ Tags (search keywords) + + Enter tags, separated by spaces, that are associated with this request. + A tag can be either a simple keyword, or a key-value pair (use a colon as + the separator, like this: key:value). +

+ Tags are used for searching. Users and administators both benefit if + you tag requests with useful keywords, because it helps them find + specific requests — especially if your site gets busy and there + are very many in the database. +

+

+ Although it's a little more complex than tags on requests, + categories + also use tags: + see + more about tags for a little + more information. +

+
+ + -- cgit v1.2.3 From d722a1df931ee0e6cc4ef2a2a3c84c08b8155319 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 10 Feb 2015 12:34:47 +0000 Subject: Add page explaining holding pen, update links in glossary and admin_guide --- docs/running/admin_manual.md | 7 ++++ docs/running/holding_pen.md | 92 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/running/holding_pen.md (limited to 'docs/running') diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index dbe8be3d1..3b05a5400 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -367,6 +367,12 @@ message under the title *Things to do*: Click on that message — you'll see a list of all the messages that need your attention. Click on any one of them to see the details. +
+ If the message does not belong to any request, you can delete it instead. + Simply click on the Destroy Message button instead of + redelivering it. +
+ When you inspect a message, you may see a guess made by Alaveteli as to which request the message belongs to. Check this request. If the guess is right — the incoming email really is a response to that request — @@ -404,6 +410,7 @@ 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 diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md new file mode 100644 index 000000000..7314b7a6b --- /dev/null +++ b/docs/running/holding_pen.md @@ -0,0 +1,92 @@ +--- +layout: page +title: The holding pen +--- + +# The holding pen + +

+ + The holding pen is where Alaveteli puts any incoming + responses + that can't be matched to a + request + automatically. +

+ + +Alaveteli works by emailing requests to the correct target +authority. +That email message is sent from a unique email address — that is, an +email address that is associated with that single request (technically, +Alaveteli hashes the request ID to generate a unique address and uses this as +the `Reply-to:` address). + +So whenever an authority replies (by email) to a request that Alaveteli has +sent, that response will be addressed to that request's unique email address. +The email is received by your installation's +MTA, +and is passed on to Alaveteli. In this way, incoming messages are easily +matched with the request they are responses to — this is important +because your site displays the responses underneath their original request, on +the request's page. + +Normally, this works fine. But sometimes things go wrong, and a message comes +in that can't be matched with a request. When this happens, Alaveteli puts the +message in the +holding +pen . + +Messages wait in the holding pen until an +administrator +redelivers them to the correct request, or else deletes them. + +## Why messages end up in the holding pen + +There are several reasons why a message might end up in the holding pen: + +* **the authority "broke" the reply-to email**
+ This can happen if the authority replies "by hand" to the incoming email — + for example if the person at the authority accidentally loses the first + letter of the email address when they copy-and-paste it. Or if they copy + it manually and simply get it wrong. + +* **the message is sent to multiple (valid) email addresses**
+ Sometimes an officer working for an authority may attempt to send email using + a collection of email addresses for you site. When this happens — + an incoming email is addressed to *more than one* valid email addresses — + Alaveteli will direct it into the holding pen because it cannot decide + which, if any, is the correct one. + +* **there's something unusual about the way it was sent**
+ For example, if it was delivered here because the address is in the `Bcc:` + field, and is not the `To:` address. + +* **a partial email address may have been guessed**
+ This may be because someone has guessed an email address either because they + have misunderstood how the addresses are formed, or due to a deliberate + attempt to send spam. + +## What to do: redeliver or delete + +You need to be an +administrator +to modify the holding pen. There are two things you can do to a message in the +holding pen: + + * **find the right request, and redeliver the message**
+ Alaveteli tries to guess the right request to help you, so sometimes + you can just accept its suggestion. + + * **delete the message**
+ If the message is not a response, you can delete it. + +For instructions, see +[removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen). + +If the message is clearly spam, you can also add its `To:` email address to Alaveteli's +spam address list. +Subsequent messages to that address will be automatically rejected — for +instructions see +[rejecting spam that arrives in the holding pen]({{ site.baseurl }}docs/running/admin_manual/#rejecting-spam-that-arrives-in-the-holding-pen). + -- cgit v1.2.3 From ed551bea6c10ddc03f99dd62cf978c61acaee0bc Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Fri, 27 Feb 2015 13:48:17 +0000 Subject: changes/fixes from @crowbots notes in PR --- docs/running/holding_pen.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) (limited to 'docs/running') diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md index 7314b7a6b..f957d4752 100644 --- a/docs/running/holding_pen.md +++ b/docs/running/holding_pen.md @@ -51,12 +51,11 @@ There are several reasons why a message might end up in the holding pen: letter of the email address when they copy-and-paste it. Or if they copy it manually and simply get it wrong. -* **the message is sent to multiple (valid) email addresses**
+* **the message is sent to multiple (valid) email addresses and one bad one**
Sometimes an officer working for an authority may attempt to send email using - a collection of email addresses for you site. When this happens — - an incoming email is addressed to *more than one* valid email addresses — - Alaveteli will direct it into the holding pen because it cannot decide - which, if any, is the correct one. + a collection of email addresses for your site. This is allowed, and the + response will be sent to each of them. However, if any of those addresses + are wrong (even just one), the response will go into the holding pen. * **there's something unusual about the way it was sent**
For example, if it was delivered here because the address is in the `Bcc:` @@ -67,12 +66,22 @@ There are several reasons why a message might end up in the holding pen: have misunderstood how the addresses are formed, or due to a deliberate attempt to send spam. +* **the response has been rejected and rejections are set to go to the holding pen**
+ Incoming mail that is correctly addressed but not accepted for the request + goes into the holding pen if the request's `handle_rejected_responses` + behaviour is set to `holding_pen` (rather than bouncing the email back to + the sender, or simply deleting it). Responses may be rejected for various + reasons — for example, if a response is sent from an unrecognised + email address for a request whose *Allow new responses from* setting is + `authority_only`. + ## What to do: redeliver or delete You need to be an administrator -to modify the holding pen. There are two things you can do to a message in the -holding pen: +to modify the holding pen. + +There are two things you can do to a message in the holding pen: * **find the right request, and redeliver the message**
Alaveteli tries to guess the right request to help you, so sometimes @@ -84,7 +93,8 @@ holding pen: For instructions, see [removing a message from the holding pen]({{ site.baseurl }}docs/running/admin_manual/#removing-a-message-from-the-holding-pen). -If the message is clearly spam, you can also add its `To:` email address to Alaveteli's +If the `To:` address does not belong to a valid request and the message is +clearly spam you can add that email address to Alaveteli's spam address list. Subsequent messages to that address will be automatically rejected — for instructions see -- cgit v1.2.3 From cb33b7c468ab01c40e2ef03ad6511f7873a881d9 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 3 Mar 2015 13:44:00 +0000 Subject: remove section: multiple to-addresses don't behave this way --- docs/running/holding_pen.md | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/running') diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md index f957d4752..d791f609c 100644 --- a/docs/running/holding_pen.md +++ b/docs/running/holding_pen.md @@ -50,12 +50,6 @@ There are several reasons why a message might end up in the holding pen: for example if the person at the authority accidentally loses the first letter of the email address when they copy-and-paste it. Or if they copy it manually and simply get it wrong. - -* **the message is sent to multiple (valid) email addresses and one bad one**
- Sometimes an officer working for an authority may attempt to send email using - a collection of email addresses for your site. This is allowed, and the - response will be sent to each of them. However, if any of those addresses - are wrong (even just one), the response will go into the holding pen. * **there's something unusual about the way it was sent**
For example, if it was delivered here because the address is in the `Bcc:` -- cgit v1.2.3 From b702d596b67d996bfb489b90293f6f39def11430 Mon Sep 17 00:00:00 2001 From: Dave Whiteland Date: Tue, 3 Mar 2015 13:49:07 +0000 Subject: rewrite to remove duplicate 'because's --- docs/running/holding_pen.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/running') diff --git a/docs/running/holding_pen.md b/docs/running/holding_pen.md index d791f609c..24d8079b0 100644 --- a/docs/running/holding_pen.md +++ b/docs/running/holding_pen.md @@ -56,9 +56,9 @@ There are several reasons why a message might end up in the holding pen: field, and is not the `To:` address. * **a partial email address may have been guessed**
- This may be because someone has guessed an email address either because they - have misunderstood how the addresses are formed, or due to a deliberate - attempt to send spam. + Someone guesses an email address which Alaveteli doesn't recognise. Perhaps + they have misunderstood how the addresses are formed, or maybe it's a + deliberate attempt to send spam. * **the response has been rejected and rejections are set to go to the holding pen**
Incoming mail that is correctly addressed but not accepted for the request -- cgit v1.2.3