ticket-printer v0.2.0

Ticket Printer

This project is an automated solution to print tickets and items as they get assigned. It is a library that exposes object standards and a server for making new ticket sources (github, jira, trello, etc...) and printers (console, receipt printer, web browser, etc...) easy to connect to each other.

Installation

This is a Node.js project, and requires npm and node to build the project. First clone or download the repository from github, and then run npm install in the root directory to install all the dependencies.

Building, Testing, and other Scripts

This project contains several npm scripts to help build and test the project.

• npm run build:lib: builds the project into lib/ticket-printer.js, happens after npm install by default.
• npm run build: does the above build, and prepares the library for testing, this should be the command when developing on the project.
• npm test: runs mocha tests on the project
• npm run test:ci: runs mocha tests and returns a report to be read by circleci, happens after making a PR or new branch on github.
• npm run test:debug: runs mocha tests with a debugger that can be inspected on port 5858. You can use a node-debugger (such as atom's Node Debugger) to attach and inspect the process.

Running

This project has no executable, but it has example scripts in the example_scripts directory, which show basic use cases and demonstrate how to use the bundled objects.

System Design

This project uses a combination of watches, hooks, and printers to get and print tickets at either a time interval, or on triggered events.

ActivityWatcher

The ActivityWatcher is the server that collects watches, hooks, and printers and acts as a mediator. watches and hooks do not need to know how their tickets will be printed, and printers do not need to know how to get new tickets, or who to get them from.

#constructor([environment])

Builds the ActivityWatcher object, and can take in an environment variable for specific settings when running.

var ActivityWatcher = require('ticket-printer').ActivityWatcher;
var aw = new ActivityWatcher({printLogs:true});

#start(printInterval)

Kicks off all the watches, and creates a loop that checks the print queue for new tickets at the printInterval. printInterval should be in milliseconds, and should be faster than any of the watches, unless you want tickets to build up before printing them. If there is more than one ticket in the queue, they will all be printed (for more information, look at printQueue below).

var ActivityWatcher = require('ticket-printer').ActivityWatcher;

var aw = new ActivityWatcher({printLogs:true});
aw.start(1000);

#addPrinter(printer)

Adds a printer object for watches and hooks to print to. You can use a bundled printer or you can write your own printer (look at printers section).

var ActivityWatcher = require('ticket-printer').ActivityWatcher;
var consolePrinter = require('ticket-printer').consolePrinter;

var aw = new ActivityWatcher();
aw.addPrinter(consolePrinter);

#addWatch(watch, interval)

Adds a watch object for printing tickets at an intervals. This is useful if you can not add your own hooks to a project or organization. The interval is an integer in milliseconds to check for new tickets from the watch. This is attached to the watch as ._interval, so that the watch can be kicked off in #start (read above). You can use a bundled watch or you can write your own watch (look at watches section).

var ActivityWatcher = require('ticket-printer').ActivityWatcher;
var timeWatch = require('ticket-printer').timeWatch;

var aw = new ActivityWatcher();
aw.addWatch(timeWatch, 1000);

#addHook(hook)

Adds a hook object for printing tickets when an event occurs.
TODO: This has yet to be defined

#reset()

Stops watches from running and removes all watches, hooks, and printers. It also stops the print check that happens after #start, and clears the print queue, if there were any tickets leftover.

var ActivityWatcher = require('ticket-printer').ActivityWatcher;
var timeWatch = require('ticket-printer').timeWatch;

var aw = new ActivityWatcher();
aw.addWatch(timeWatch, 1000);
aw.watches; // -> [ timeWatch ]

aw.reset();
aw.watches; // -> []

tickets

Tickets are objects which are generated by watches and hooks, and are passed on to (possibly multiple) printers by the ActivityWatcher. They have the following properties:

• watch, a string, the name of the watch
• title, a string, the title of the ticket
• project, a string, the project that the ticket belongs to
• number, a string, the id or number of the ticket
• body, a string, the text content of the ticket

var exampleTicket = {
  watch: "Example Watch",
  title: "Messages are lost in queue",
  project: "Chats-R-Us",
  number: "#27a",
  body: "When sending messages using ..."
};

printQueue

The printQueue is a queue that lives in ActivityWatcher. It is passed to the getTicketObjects function, which then can enqueue tickets to be printed whenever the ActivityWatcher loops around to check it (see #start above). It will always be a list of tickets to print, and pops off those tickets as it sends them to all the printers. If there are no printers, tickets are still popped off the queue.

watches

Watches are javascript objects which are queried for tickets at a given time interval. This is valuable when hooks are not available (due to permissions or availability) and manually checking via an API call would be easier. Watches need to be added to an ActivityWatcher, and print to all the printers added to the ActivityWatcher.

Watches are expected to have the following properties:

• name, which maps to a string.
• getTicketObjects, which maps to a function that takes in a printQueue to mutate, and returns nothing. To print tickets in order, the unshift function should be used to push tickets onto the queue. Look at printQueue above for more details.

var exampleWatch = {
  name: "My First Watch",
  getTicketObjects: function( printQueue ) {
    printQueue.unshift({
      watch: "Example Watch",
      title: "Messages are lost in queue",
      project: "Chats-R-Us",
      number: "#27a",
      body: "When sending messages using ..."
    });
  }
};

printers

Printers are javascript objects which can print a ticket object. They are automatically triggered by the ActivityWatcher when new tickets are found. Except for testing, it is rare that you call the functions directly.

Printers are expected to have the following properties:

• name, which maps to a string.
• printTicket, which maps to a function that takes a ticket object

var examplePrinter = {
  name: "My First Printer",
  printTicket: function(ticket) {
    console.log(ticket.name + ": " + ticket.body);
  }
};

hooks

TODO: This has yet to be defined

Bundled Objects

With this project, there are several bundled examples to make understanding and working with this project easier.

timeWatch

This is a bundled watch that always returns a single ticket with the current time.

consolePrinter

This is a bundled printer that prints the ticket to the console.

Contributing

If you would like to contribute to this project, feel free to fork this repository and make a Pull-Request. PRs should include new tests and documentation updates. Commits should be semi-formal. While the PR's description will be reviewed first-and-foremost, commits should have a present-tense single line that details what will be added. For a clear example of what PRs should look like, look at one of the closed PRs.

Issues

If you want to help contribute, but don't know what needs to be worked on, check the issues tab on github. Anything on there that is not assigned is up-for-grabs . Issues with the help wanted label are for comments and are encouraged to be picked up by other developers. Issues with the discussion label are for comments or feedback, usually on potential features or work items that aren't completely defined yet, or need some fleshing out.

Pull Requests

There are also Pull Requests with the needs review label. One way that anyone can contribute is by reviewing PRs with this label. These PRs may include large code changes, or small README updates. If a PR looks confusing, or is unclear, call it out! This project should be easy to approach and make changes to. If a new PR does not include enough documentation (in the form of comments, or in the README), then the PR should be updated.

Watches, Printers, Hooks, Oh My!

If you want to contribute by making new watches, printers, or hooks, that's 100% encouraged! The dream is that this project becomes a great plug-and-play system, where people can hook up whatever ticket system they use into whatever display they use. A web page that shows incoming JIRA cards, maybe a receipt printer that prints github issues, or a text console that shows all the new Trello bugs for the day. The possibilities are endless!

New Watches, Printers, and Hooks should only introduce the minimum required dependencies, and these should be included as optional dependencies. I realize in the future, including several Node APIs may get out of hand. When that happens, this project may go the way of babel (separate packages) however, that's something we'll tackle once we hit that bridge.