How to use the escalation macros to do a structured escalation

Answer

This page documents how to use the escalation macro to create a structured escalation form, based on a standard template that's been set up for a particular escalation, and related to an existing RT ticket that should trigger an escalation ticket with another group.

0. Assumptions & Best Practices

The macro assumes an escalation process and steps currently considered best practices by the MIT IS&T Help Desk. In particular, it includes the following:

• Escalations must be based on an existing RT ticket, for which the end-user is usually the requestor
• Escalations include standard template text and a check-list of info that should be collected before escalation
• Escalations usually create new tickets in RT, but may rarely also only consist of email to the team being escalated to

1. Framework

Although anyone can create a stand-alone escalation page, these pages are usually end-points in a short tree of pages leading a staff member to the right escalation procedure. A sample tree might consist of a series of short informational "node" pages, in a parent-child hierarchy, each ending in a special escalation page with a properly configured escalation macro on it.

Setting this up requires some familiarity with creating parent-child relationships between pages in the Knowledge Base.

Example framework:

• Node article: "Getting help with the Knowledge Base"
  • Child node article: "Getting help with creating articles"
    • Escalation article: "Request authoring permissions for the Knowledge Base"
    • Escalation article: "Request that someone's authoring permissions be revoked"
  • Child node article: "Getting help with common problems while authoring"
    • Escalation article: "Request that an article be permanently deleted"
    • Escalation article: "Request that an article with errors be fixed by an administrator"

In the above example, each "node article" and "child node article" is a simple Knowledge Base article, usually consisting of a title and a short body with a description to help the reader decide that they navigated to the right place. The "escalation article" is described in detail in section 2 below.

2. Escalation article format

An escalation article usually has three parts:

1. A unique title
2. A short description to let the reader know that they are on the right escalation article
3. An embedded escalation macro that has been configured correctly for this particular escalation

The escalation macro

The escalation macro needs to be inserted by the article author using wiki markup. It has several required and option parameters. See the info box for full usage information:

Escalation macro usage {escalation:to=emailaddress|cc=emailaddress|requestor=emailaddress|subject=subject} Template text for the escalation email goes here. This is also called the "body" of the macro. {escalation} to=emailaddress This parameter is required, and specifies the email address this escalation is sent to. This value cannot be edited by the submitter. cc=emailaddress This parameter is optional, and specifies a default email address to put in the Cc line. The special value "self" can also be used instead of an email address, which will always put in the submitter's email address, if they authenticated to the Knowledge Base. requestor=emailaddress This parameter is optional. It specifies an email address to use for the requestor. This email address will be put in the "Reply-To" header line of the escalation email. The value can be left blank or the parameter omitted entirely, in which case the submitter can manually enter a requestor email on the subsequent escalation screen. If this value is set in the macro, it cannot be edited by the submitter. subject=subject This parameter is optional, and will specify an initial value for the subject line. This value can be edited by the submitter before sending the escalation email. body This macro expects a body, which will be used as the template text in the body of the escalation email. It can be edited before submission. A body is optional but strongly recommended. If a body is not present, the submitter will have little guidance on what to put in the escalation email.

3. Steps the "submitter" goes through

After the escalation article page containing the escalation macro has been set up, it can be used by anyone who has read access to that page in the Knowledge Base. Here are the steps the "submitter" or user of the macro page goes through.

a. Beginning the escalation

On the escalation article page, the submitter/escalater can review the body template text to confirm that the proposed escalation is the right one. She is prompted to enter a related end-user ticket number. This is required to proceed. She would then click the "Perform escalation on this topic" button at the bottom of the page.

b. The "Perform escalation" page

After clicking the "Perform escalation on this topic" button, if the macro was set up correctly, the submitter/escalater will be taken to a special, central escalation page in the Knowledge Base, which presents several things to actually submit the escalation email. On this special page are:

• An email-like web form showing some editable and some read-only fields that will be used in the escalation email
• An editable body text area showing the initial template text, to be edited and filled out before submission
• A read-only email footer that includes a reference to the original ticket
• Two iFrames on the right side of the page which will attempt to pull in meta data and history from the original ticket (presented for reference and to allow easy copying and pasting of material from the original ticket)
• A "Send escalation" button at the bottom of the page

After editing and reviewing the form, the submitter/escalater will generally click the "Send escalation" button and be presented with a results screen from the cgiemail program on web.mit.edu, showing the email that was sent as a result of the action.

What happens next will depend on the nature of the escalation and is independent of the Knowledge Base.