Fixit

From Artisan's Asylum

Jump to: navigation, search

The fixit system describes a collection of code and conventions that allows you to check on and update the status of all of our shop equipment. This means that if you need a particular tool to work on your project, you can find out if it's operational before even leaving home. And if you're standing at a tool wondering whether anyone has already reported a problem with it, you can check immediately.

Contents

Basic overview

Every important tool in the shop has a page in this wiki. When a new tool is acquired, a volunteer (this means you, if you want) builds a new page describing the tool.

Each such page is built on a template that defines certain important URLs, and following those URLs interacts with fixit. You can use those URLs to check on the status of an individual tool, or every tool in a particular category---including every tool in every shop, if you so desire. Tool status is recorded by opening, modifying, or closing tickets in RT, an issue-tracking system---fixit provides a convenient front-end that glues the wiki pages describing tools to the RT issue-tracker, without requiring users to understand RT itself or have an account in that system.

Checking the status of a tool searches for tickets about that tool. If you tell fixit that a tool is down, fixit creates a ticket in RT which says so. RT also sends mail to ticket creators and tool maintainers; replying to that mail tells RT to add more information to the ticket. People who maintain tools have additional access which allows them to alter other fields of the ticket, or to close the ticket when the tool is repaired.

In addition, each tool mentioned in the wiki has a QR code physically attached to it. Thus, if you have a smartphone, you can immediately jump to the tool's "check tickets" page, so you can check on its status or open a new ticket. From that page, you can also go directly to the wiki page for the tool, enabling you to look up the tool's basic instructions, find manuals and rubrics, and so forth.

How to quickly find a tool in the wiki

If you're standing at the tool already, and you have a smartphone, scan the QR code attached to the tool. You'll get a page which will tell you immediately if the tool is up or down. You can follow the top link on the page (in the heading) to find the wiki page for that tool.

If you're not standing at the tool, you have a couple choices:

  • Search for it
  • Walk the category hierarchies

Searching for a tool

Every page on the wiki has a box labelled search on the lefthand side of the page. If you type in some substring of the tool name (such as "angle grinder"), you'll see pages that mention that tool.

Walking the category hierachies

You have several choices:

All of these categories let you drill down to subcategories and individual tools, so you can get an idea of what we have, and you can also get reports on the health of all tools in the category at once.

You can find more details about how categories work below.

Getting the status of a single tool

The important fields for fixit are listed in the box on the right of each tool page, near the bottom of the box, under the heading Operational Status. There are three fields:

  • Latest Status
  • ?s/Problems
  • QR Code

The "Latest Status" field

The operational status of a tool is determined by scanning the ticket database for all open tickets on the tool, and can be one of Up, Advisory, or Down.

The various states a tool may be in are mapped to the ticket-priority system in RT, where "down" has the highest priority, and other states have lower priorities. (When you see the word "priority" used on this page or on the various tool-status pages and forms, that's what is meant---the priority is used to indicate how operational this tool really is. It is not used to indicate how important this tool is relative to other tools, or how important this particular repair is, but merely how broken the tool is.)

If there are any open tickets with a priority of "down," the tool is declared to be down. If there are no such tickets, but there are "advisory" tickets, then the tool is in an advisory state. If there aren't any advisory tickets either, then the tool is completely up.

So what's an "advisory" state? It means that the tool might be out of adjustment, have dull cutters, be almost out of some consumable, etc, but is generally usable. In short, go ahead and use it, but be aware that it is operating in a degraded state.

A tool may also have open tickets with a priority of "wishlist." Wishlists aren't the same as advisories. An advisory means that there is definitely something wrong with the tool, though it is usable. A wishlist priority is just something that would be nice to have, but which doesn't impede work. This can include extra consumables, a different sort of jig, better documentation, and so forth.

The "?s/Problems" field

This is the link for checking detailed status of the tool, or for opening a ticket on the tool. If you click on it, you'll be taken to a form that shows all open tickets (of any type) on that particular tool. Please read the existing tickets before opening a new one. If you need to open a new ticket anyway, you can do so by filling in the fields---follow the instructions on that page.

The instant you open a ticket, or any time you amend it, the issue-tracking system sends mail to a list of people who help maintain tools, so they know the ticket's status has changed. (Not everyone who maintains tools is on that list, but those who maintain tools are welcome to join it if they want.) Also, if you are the one who opens a ticket, and you supply your email address, the system will send you mail any time the status of the ticket changes.

Note that the very top line, "Tool status for tool," includes a link pointing back at the page you came from. This is useful if you got to this page via scanning a QR code (see below) and want to get back to the actual wiki page about the tool.

The "QR Code" field

Clicking this link presents you with a QR code, suitable for printing, which is the URL to the page for opening a ticket for the tool. In general, you should only need this if you've just written a page describing a new tool, and need a QR code to stick on the tool itself. [The office has several hundred sheets of 8.5 x 11" sticky-backed label material, suitable for laser printers, so your new QR code can be printed on the printer in there, or any other suitable printer. Just print it out, trim it, and attach it to the tool.]

Getting the status of many tools at once

Suppose you're planning on using most of the tools in a craft area or shop during your visit. How do you know which ones are up or down without checking them each individually? By using the wiki's category system.

Note: Because the categories form an inheritance tree, it's easily possible to walk the tree to find tools. See the discussion above for some good starting points. You can survey every tool in every shop this way, but be careful---categories such as "Tools", which include every tool in the shop, or large craft areas such as "Woodworking", have a lot of tools in them. Querying for every tool in such categories may take a minute or more to compute for so many tools, because RT is slow.

How the wiki uses categories

Every tool is simultaneously a member of at least two categories:

  • Its species.
  • Its craft area.

Tool species

A tool's species define which other tools are similar to it. In particular, tool species answer the question, "If I'm trained on this tool, am I allowed to use this other tool?" The short answer is, "If you're trained on any tool in a species, you are allowed to use all tools in that species." For example, all angle grinders are pretty much alike, so if you're trained on one, you're trained on them all. As a result, they're all in the same species. On the other hand, CNC milling machines are mostly not alike, so training on one doesn't necessarily carry over to another. Thus, each of our different pieces of CNC equipment is typically in a species composed only of itself.

Craft areas

Craft areas are a functional grouping of tools based either on where they are (Hot Craft Studio), or what they're used for (Welding). Often, of course, these are one and the same thing, since it makes sense to put tools that are used for the same types of work in the same shop.

Using categories to check tool status

Every tool page has two category links in the chart on the right:

  • Tool Species. What other tools are like this tool.
  • Location. Which shop this tool lives in.

Tool species categories

If you click on Tool Species, you're taken to the category page for that tool's species. On that page, in the box on the right, you'll see links for

  • Operational Status and
  • Maintenence Tickets

Clicking on Operational Status will show you a quick summary of all tools in that species and what their status is. For each tool, only the most-severe ticket is shown---it doesn't matter if there's an advisory or wishlist item on a tool if it's also totally down.

Clicking on Maintenance Tickets will give detailed information on all open tickets, but won't mention any tools that don't have open tickets. (This means that if the category has no tools with open tickets, you'll see a page that just says, "No open tickets in this category.")

Craft area categories

If you click on Location, you're taken to a different category page, with links for

  • Operational Status of Tools and
  • Tool Maintenance Tickets

These are phrased slightly differently than on the species pages, to emphasize that the status and tickets are for the individual tools in that craft area, and not for the craft area itself. As with the species category, clicking on either one of these links will give you a quick status report, or detailed ticket info, for every tool in that craft area. [Note that this information is currently computed live from a fairly slow issue-tracking system, so you may have to wait a few seconds for a craft area that has a lot of tools in it. In the future, depending on demand, caching of this status may be implemented, which will increase performance at the cost of increased code complexity.]

Commenting on tickets

This section is relevant to people who comment on or send mail about RT tickets.

How to update a ticket

You can either send mail, or you can use the web interface. Only people with RT accounts may use the web interface.

Types of updates

If you are adding text to the ticket (as opposed to changing its status), RT understands two types of updates. Both types add the text to the ticket, and also send it to the tracker list, so other people on the tracker get the update. The difference between types of updates concerns whether the requestor (the person who originally opened the ticket) also receives mail.

The two types of updates are:

  • correspondence, which also send mail to the requestor
  • comments, which do not send mail to the requestor

If you don't necessarily want to send mail to the requestor, you should comment, not correspond---but note well that this does not mean you can talk behind the requestor's back! Both correspondence and comments are added to the ticket, and both types of updates shown by fixit when it displays the ticket narrative, as described below.

Email vs web

The easiest way to use the mail interface is to send a message to one of:

  • ticket-queuename: this corresponds on the ticket, meaning what you send is also sent to the requestor
  • ticket-queuename-comment: this comments on the ticket, meaning that the requestor does not see what you sent, but the watchers do

However, you can also manipulate a large number of the ticket's attributes using the CommandByMail interface, such as its priority, its subject line, what queue it's in, its status, and so forth. (Anyone can send mail to a ticket, but only those with an RT account may alter it using CommandbyMail.) For a full explanation of what you can do, see its documentation.

Note that you can include lines like "Owner: Foo" and/or "Priority: 41" in your initial email submission of the ticket. Those lines will appear in the text of the ticket, just like any other text, but they will also take action---this allows you to submit a ticket, and set its owner and priority, in a single message.

If you're using the web interface, note the "Comment" and "Reply" commands in the upper right in the "Update ticket" window. Note also the "Update Type" in the set of dropdowns and headers at the top; you can change between commenting and corresponding via the "Update Type" dropdown.

How the text of a ticket is shown by fixit

When fixit renders a ticket in a report-style page, it also includes the ticket narrative. This is a compressed form of all commentary on the ticket, and is produced by fetching each ticket attachment and processing it. This has some implications if you are opening, commenting on, or replying to tickets and you do or don't want it to show up in fixit's rendering.

Each message to RT (opening, commenting, replying, etc) is viewed by RT as a single transaction, and each such transaction is represented by one or more attachments. fixit's processing includes:

  • Ignoring any attachment without any text (e.g., images)
  • Preferring the text/plain version of any attachment over the text/html version, if the message is multipart/alternative
  • Using text/html if no text/plain version of the message is available
  • Mapping Unicode to ASCII, and tossing unrepresentable glyphs (this is done because the entire web page must agree on its character encoding, regardless of what individual messages want)
  • Throwing away any remaining HTML markup
  • Throwing away any line beginning with ">", possibly preceded by any amount of whitespace (this gets rid of included messages)
  • Translating anything that looks like an email address into one that years of experiments have continued to show is unharvestable by spammers (see here for the general idea)

In particular, note the bit about tossing lines beginning with ">". This means that, if you want to forward someone else's message into an RT ticket and you want their message to show up in fixit's report, you must remove the leading ">" characters, or it will simply disappear. On the other hand, if you'd like something to show up in the long-format ticket, as viewed by someone with an RT account, but you don't want it to show up in fixit's report (perhaps because it's excessively long and would bloat the resulting web page), then manually preceding every such line with ">" will act as invisible ink.

Internals

[This section is relevant to people doing large-scale wiki edits related to tool pages.]

The way this system works imposes a few constraints---these necessitate some care when making large-scale changes to the wiki. Here's a very high-level overview of what's going on.

There are three main components to the fixit system:

  • The wiki, with homegrown templates that define tools and species
  • The RT issue-tracking sytem, with custom priorities and Mailman integration
  • Roughly a thousand lines of homegrown Python that glues them together

The Python code talks directly to the MySQL database underlying the wiki, because the wiki lacks certain necessary APIs, and asking the wiki to render pages and then scraping the results would be slow and fragile. It also talks to RT using all three access modes enabled by RT (the REST interface, the CLI, and email), because each of those methods has bugs and deficiencies that make it unsuitable if used alone. The Python code runs as a WSGI module, invoked by Apache for each request; it does no background processing. [A caching system, to speed up slow queries, would likely have to run independently, presumably as an RT ticket hook, to prebuild the cache and keep it current.] To enable checking for typos in ticket-creator email addresses, the Python code also has limited access to our database of all members.

The functioning of this system is critically dependent upon following certain conventions in the wiki in particular. Most of those conventions are enforced by the templates used to construct tool pages and species pages. Because fixit checks pages to find certain template elements, renaming those templates will break the system (it will conclude that the page is not a tool page, for example), so don't do this. Also, certain changes to the templates themselves can break the system. Ask first!

When a ticket is opened, its subject field is the exact name of the tool in the wiki; searching for this subject field is how fixit finds open tickets for that tool. This means that renaming a tool in the wiki will effectively "lose" any open tickets on that tool, as far as fixit is concerned, because it will then search only for tickets that use the new name. For this reason, it's a bad idea to rename any tools for which open tickets exist---any fixit user will stop seeing old tickets for the tool, and only users with actual RT accounts will be able to find those tickets. If you absolutely need to do that, ask first, and any open tickets' subject fields can potentially be changed to match, but it will involve manual work to do so---which means you'd better have a really good reason to ask someone to spend the time. Furthermore, regardless of whether or not the tool has any open tickets, you're going to have to reprint the QR code for the changed tool name and then remove the old one from the tool and stick the new one on. Because renaming a tool is such an expensive proposition in human time, it should not be done lightly.

RT URLs

Please don't include links to RT URLs (any URL which has "rt." before, or "/rt" after, our domain name) in web pages. RT is slow, and having search engines constantly hitting it isn't ideal. Even though we exclude well-behaved search engines from RT via robots.txt, not all search engines are well-behaved, and the ill-behaved ones are typically only banned after they're found to cause problems. We'd rather not have to enable adaptive throttling on requests, or any other such power tools.

Reporting bugs

Please report any bugs to bug-fixitREbug-fixitMOartisansasylum.comVEME@artisansasylum.com.

Personal tools
Wiki Maintenance