Engineering, Design and Analytics

Pushing Paper

Here at Counsyl, we process a lot of blood and saliva samples every day, and as we grow, this number is only going to increase. Most of our laboratory processing is mechanized and automated, but the first stage of sample intake and unpackaging, known as accessioning, is by nature a manual process.

Most of the samples we receive already have information stored in our system, because they’ve been ordered electronically by a patient or clinic. But even today, over 30% of requisitions are made using paper forms — some clinics prefer or require a paper workflow. Right now, our Accessioning team hands over the forms they receive to the Data Entry team, who type the data into our system manually. As Counsyl grows, we’ll need to handle this all as efficiently as possible.

To that end, we’re beginning to move towards a digitized setup. The first part of this project, newly introduced, is a workflow for scanning these paper requisition forms.

How It’s Used

Brother ADS-2000 scanner

The Accessioning team has now been equipped with a fleet of four document scanners. When they go through their standard workflow for a sample with a paper requsition, a new “Scan” button greets them with the option to scan paper requisitions and other documents, uploading them to our server, right from the webpage. These images are stored on our servers, and are linked to the sample in the database, so the Data Entry team can access them.

Scanning Workflow Screenshot

And when the Data Entry team uses their interface to digitize a form, rather than looking at a paper copy, they can now view the scanned images right on the page. The image viewer supports zooming and rotation, and remains visible while they scroll through the form.



How it Works

Every once in a while in software development, you’ll find a challenge for which the existing tools are insufficient, and you have to get a bit creative. In the case of this project, we had a new feature (scanning) which had to be built flexibly on top of an established workflow (web-based data entry).

In order to integrate fully and seamlessly with the web-based interface, JavaScript was a necessary part of the new system. But how could we get JavaScript to talk to a physical scanner device? One possibility: make use of HTML5’s new media capture APIs. (Luckily, because this project was an internal one, such a new API might be a feasible solution, because we have control over the computers and web browsers our teams use.) These APIs currently provide video and still camera support, but unfortunately there’s no support for scanning or generic USB devices. So we know our web browser can’t talk directly to the scanner. What’s the next best thing? We’ll have to make an in-between layer ourselves!

Fortunately, there is a good way to interface with scanners from software: Mac OS X’s IKDeviceBrowserView and ICScannerDevice classes. (For more info on ICScannerDevice, you’ll have to see /System/Library/Frameworks/ImageCaptureCore.framework/Headers/ICScannerDevice.h, since it’s mysteriously absent from But don’t worry, it’s not a private API!) Combining these APIs, we were able to make a simple Mac app, dubbed ScanStream, that mediates between the USB scanners and the web browser.

the ScanStream app

When ScanStream receives an AJAX request from JavaScript code running in the browser, it asks the scanner to work its magic — and when the documents are finished scanning, it sends the image data back to the webpage. Then, we can make use of JavaScript’s super-cool FormData class (another fairly new web technology) to upload the files to Counsyl servers.

Here’s a slightly more detailed diagram of the architecture, showing more specifics about the functionality we included to make it easy to integrate with our existing workflow:



Our accessioning web interface determines ScanStream’s status by sending a request to localhost:8080/ping, and requests a scan with localhost:8080/scan. Since we need to scan multiple files at once, the initial HTTP response from /scan includes a list of temporary codes that can be used to load the actual file data individually from localhost:8080/download/....

Each file is served in a JSON dictionary, so that extra metadata can be included if need be. For our purposes, the JavaScript on the webpage uploads the files to our server immediately (using FormData), and records their IDs in a hidden field on the form, so they can follow along during form validation, without actually being “attached” until the form is successfully saved.


With just a little creative hackery, we’ve been able to implement a fully functional and extensible document scanning workflow. For Counsyl, this means we can finally store all documentation electronically — a huge win for us in terms of both efficiency and patient information tracking. We can now process documents more quickly, and the door has been opened to further automation as we continue to scale.

By the way, ScanStream is open-source — check it out on GitHub!

Jacob Bandes-StorchJacob Bandes-Storch is a software engineering intern at Counsyl and a rising senior at Harvey Mudd College, majoring in Computer Science and Mathematics. Lately he doesn’t have any free time, but in it he grades & tutors computer science classes, hacks on apps and a few open-source projects, and plays the piano.

Leave a Reply