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.
This Project is no longer in development. If you wish to print tickets in a
less automated way,
check out https://github.com/JRJurman/ticket-printer
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.
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 projectnpm 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.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.
This project uses a combination of watches
, hooks
, and printers
to get
and print tickets at either a time interval, or on triggered events.
To see an actual implementation of this example, look at the following project:
https://github.com/JRJurman/tessel-printer
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 watchtitle
, a string, the title of the ticketproject
, a string, the project that the ticket belongs tonumber
, a string, the id or number of the ticketbody
, a string, the text content of the ticketvar 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 objectvar examplePrinter = {
name: "My First Printer",
printTicket: function(ticket) {
console.log(ticket.name + ": " + ticket.body);
}
};
hooks
TODO: This has yet to be defined
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.
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.
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 isn't assigned is up-for-grabs. If it is unclear on what work needs to be done, feel free to make a comment on the issue asking for help.
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.
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.