WINGSCAN WHITEPAPER: APPENDING
APPENDING ADDITIONAL SCANS
This Whitepaper is going to be "laser focused" on implementing one specific
use case with WingScan: To allow one append the results of a second and
subsequent scan to an existing document / previous scan present in the
WebDocumentViewer / WebDocumentThumbnailer.
The "out of the box" experience with WingScan is that when you open or scan a
document, you are replacing any existing document that is present. So if you
have say 2 pages loaded and you begin a scan with page.. you will end up with
just the new 1 page scan open and the former document is lost/closed. This then
is about "what if I want to add more pages to the existing open document".
This is not a "getting started with WingScan" tutorial. For that, please see
INFO: WingScan Whitepaper - Getting Started with Web Scanning.
For other White Papers please see the Whitepaper category on our
knowledgebase.
TECHNICAL OVERVIEW
In some ways, the append versus open operation is a WebDocumentViewer /
WebDocumentThumbnailer operation. We could easily write a KB on "appending a
document in WDV" ... in fact, we may do that at a future date. We will be taking
advantage of the WDV/WDT viewer.document.insertPages() feature. The difficulty
is that in order to insert multiple pages, one must know how many pages one will
be inserting. There is no "just insert all the pages in this document".. (An
enhancement request for this is officially on file but has not yet been
implemented).
An additional complication is that you don't necessarily know in advance
before oyu scan how many pages will be part of the scan. If you are using blank
page detection/removal (VRS License required) then the number of pages may not
match the number of pages you have inserted.
In order to solve this problem, what we will be doing is implementing a
simple count incrementor during the imageAcquired event so that we track in real
time how many pages have been uploaded. This way, we know the moment the scan
has finished how many pages need to be inserted. This saves us the ugly step of
having to go back to the server side and implement some form of "count number of
pages in this file" (perhaps fodder for a WDV whitepaper in the future).
We will be starting with the final result project from INFO: WingScan Whitepaper - Getting Started with Web Scanning. You can download
the sources for the starter project here: WingScan_withViewer.zip (11.3.0.3).
We will then modify it to add handlers for image acquired, we will add a new
function to decide if we are appending or adding and add buttons to trigger that
functionality, and finally adjusting the uploadCompleted handler to perform the
append (or open as directed).
DOCUMENT STANDARDS AND ASSUMPTIONS
The technical portions of this document assume that you are a developer with
access to MS Visual Studio 2013 or later. We will be providing examples in C#.
Our SDK works with VB.NET as well, but for the sake of simplicity any .NET code
will be provided in C# You can use a converter tool such as Telerik Code converter to
convert examples to VB.NET
This document and our SDK assume that you're a developer familiar with basic
use of Visual Studio, IIS Express or IIS, and general web application
development practices. The samples will be using an HTML 5 approach in a non-MVC
application targeting .NET framework 4.5.2 in a 64 bit application.
Please note that due to changes in Google Chrome and the Chromium engine, WingScan will not work if you're not on at least 11.4.0.5. Also note you must target at least .NET Framework 4.5.2 with DotImage 11.2 or greater - but since MS has end of lifed < 4.6.1 we suggest at least that.
Also note that this document covers a standard ASP.NET web app, not ASP.NET
Core. We do have support for WingScan with .NET 6 and above but that is beyond the scope of this document. The fundamental
concepts of this document apply whether you are going to use ASP.NET or ASP.NET
Core the client-side code is the same - the difference is in the handler (used
for ASP.NET) versus the startup middleware (used by ASP.NET Core).
A brief set of instructions for downloading our SDK and activating a license
will be given, but the rest of the document assumes you've installed the latest
DotImage SDK (currently 11.4.0.14 as of March 2024)
Examples herein will use IIS Express (built in web server for Visual Studio)
set to run in x64 mode
We do provide NuGet packages for our components, but this example will assume
you've installed and activated our SDK locally.
If you're a licensed developer, or are actively evaluating our SDK and run
into problems/questions, you are welcome to contact support. You can make a
support case in writing in our
support portal
You may also call in to support during our normal business hours
Support
Hours: M - F from 8AM - 5PM EDT (New York Time)
Call us: 1-781-743-2119
STANDARD TROUBLESHOOTING
Web applications with WingScan have a lot of "moving parts" and
troubleshooting can seem a daunting task.
There are two tools (one ours, one a free third party tool) that can greatly
enhance troubleshooting and assist you in reporting issues to support
If you are having issues with WingScan
Please download and run the diagnostic logging
tool
Use it to collect a log while you reproduce the issue.
These diagnostic logs will often show the root cause of an issue. Although
they may be a bit daunting to look at at first, rest-assured, they're a valuable
diagnostic tool. So, if you're contacting support about a WingScan issue, please
take a moment to collect this log then save it to a text file, then zip up the
log file and attach it to your support case
In addition to the WingScan log, problems related to the client-side web
components are best diagnosed by looking at a log of the network traffic. Most
commonly a faulting application will clearly show a 500 internal server error
being thrown and the full response body of that error will offer a great deal of
insight into the root cause (licensing issues, and errors in the
WebCaptureHandler and WebDocumentRequestHandler will most often show up in the
500 error response body)
We recommend Fiddler if you need to collect a log and report it to support.
Please download, install, and run Fiddler web
logging
Use it to collect a log while you reproduce the issue, then save the log as a
native .saz file and and attach it to your support case as a file attachment/
(please do not save as CSV or text log. The native SAZ file gives us much better
access to the tools we need to help diagnose your issue)
PLEASE NOTE: you need to capture a session while NOT using SSL/HTTPS.
Fiddler logs cannot see into HTTPS without enabling a special certificate which
we do not recommend.. if your capture is of an HTTPS session we will not get
useful diagnostic information from the log
INSTALLATION AND LICENSING
If you have not done so already, please download the latest version
of Atalasoft DotImage SDK
NOTE: The current version is 11.4.0.14 as of the creation of this
document (March 2024) updates of the SDK happen with regularity. We work hard
not to make breaking changes so this guide should be compatible with future
releases. We will update the specific technical details as needed as changes
arise
Some of the images here may be of older versions - but you need to be on at least 11.4.0.5 in order to work with WingScan and modern Chromium based browsers.
If you have not done so, please create an account with Atalasoft so that you
can download and activate our SDK
- Download and install the Atalasoft DotImage SDK
- Run the activation wizard
- If you have SDK serials for DotImage and/or WingScan use the "Activate an
SDK serial for use on this machine or a server license" option and activate your
serials for version 11.4
- If you do not yet have licenses, you can select the "request 30 day
evaluation"
- If you run into issues activating or require assistance, please contact
support
NOTE for IIS users: The licensing above should be sufficient if you're
using the built in web server in Visual Studio (IIS Express) but if you are
using a local copy of IIS, then the IIS process does not run as your user name
so it will not pick up your licenses. You'll need to take the extra step of
copying your licenses into the application bin directory.
Assuming you have an app named WingScanTestApp hosted in IIS
under:
c:\inetpub\wwwroot\WingScan_withViewer\
Then you'd copy your licenses
from:
C:\users\YOUR_USERNAME\AppData\Local\Atalasoft\DotImage 11.4\
to
c:\inetpub\wwwroot\WingScan_withViewer\bin\
MODIFYING THE SAMPLE APP
As mentioned above, we will be basing this project on the completed getting
started with WingScan project from another whitepaper.
- Download WingScan_withViewer.zip (11.4.0.14)
- Unzip it to a known location
- Open the solution with Visual Studio 2013 (or later)
- Add vars for keeping track of state
- open Default.aspx and edit the script section where we initialize viewers...
look for where it has
<script type="text/javascript">
var _viewer = null;
var _thumbs = null;
// Initialize Web Scanning and Web Viewing... this will run at startup
$(function () {
...
- just after the var _thumbs line, add this:
// _append and _scanCount are needed for scan new vs scan add...
var _append = false;
var _scanCount = 0;
- Create utility function makeSrcArray
This is needed due to an oddity
in how the insertPages works - we need to build the array of page indices it
expects when given just a page count.
- Within the JavaScript block, just after you initialize the viewer and web
scanning, add this makeSrcArray function
// This is needed because the insertPages call needs an array of indices
// so we pass in a number of pages to generate the needed src indicies array
function makeSrcArray(count) {
var returnArray = new Array();
for (var i = 0; i < count; i++) {
returnArray.push(i);
}
return returnArray;
}
- Modify scanWithSelectedScanner function
The WingScan_withViewer
sample app has a scanWithSelectedScanner method. We need to modify it to handle
control of append versus open
- In the default.aspx page, find the original scanWithSelectedScanner()
function:
// this is needed because if you do not use this code, then only the system default scanner will ever be used
function scanWithSelectedScanner() {
Atalasoft.Controls.Capture.WebScanning.scanningOptions.scanner = $('.atala-scanner-list').val();
Atalasoft.Controls.Capture.WebScanning.scan();
}
- Replace it with this:
// this is needed because if you do not use this code, then only the system default scanner will ever be used
// We will be adding the append value to set here
function scanWithSelectedScanner(append) {
// setting the _append var to true/false to determine if we will scan new (false) or append to existing scan (true)
if(append) {
_append = true;
} else {
_append = false;
}
// this is the standard scan with selected scanner code
Atalasoft.Controls.Capture.WebScanning.scanningOptions.scanner = $('.atala-scanner-list').val();
Atalasoft.Controls.Capture.WebScanning.scan();
}
What we have done here is modified it to take an
argument for append.. if there's anything not-null passed in, then we set append
to true, otherwise, we set to false. Then we just do the same thing we did in
the original code.. scan wit the selected scanner.
- Add event handlers for onScanStared and onImageAquired in support of append
feature
Now, we need to modify the web capture initialization. We will be
adding handlers for two events that we did not handle at all in the
WingScan_withViewer sample.
- Between handlerUrl and onUploadCompleted, add onScanStarted
handler
Original code looks like this:
try {
Atalasoft.Controls.Capture.WebScanning.initialize({
handlerUrl: 'WebCaptureHandler.ashx',
onUploadCompleted: function (eventName, eventObj) {
...
- We will add just after the handlerUrl: 'WebCaptureHandler.ashx',
onScanStarted: function () {
// When we start a new scan, we want to make this count zeroed out so that we get an accurate count
_scanCount = 0;
},
- After the new onScanStarted, add the onImageAquired handler
onImageAcquired: function (index, image) {
// this just increments the count each time an image is acquired..
// this is how we will know how many pages were scanned so we can properly
// insert later
// NOTE THIS EVENT DOES NOT FIRE IF discardBlankPages was true and the page scanned was discarded
// this allows us to have a correct count for number of pages scanned
_scanCount++;
},
- Modify the onUploadCompleted to do the actual append versus open
Now,
we need to modify the original onUploadCompleted event. We need to decide if we
are appending or opening and then take the appropriate action
- The original onUploadCompleted() will look like this:
onUploadCompleted: function (eventName, eventObj) {
if (eventObj.success) {
_thumbs.OpenUrl("atala-capture-upload/" + eventObj.documentFilename);
Atalasoft.Controls.Capture.CaptureService.documentFilename = eventObj.documentFilename;
}
},
- We need to replace it with this:
onUploadCompleted: function (eventName, eventObj) {
// we only do this if the upload completed successfully
if (eventObj.success) {
// You will need to adjust this to point to the actual location where
// the files are being uploaded/scanned into
// atala-capture-upload is simply the component's default location
var folderWhereFilesUploadTo = "/atala-capture-upload/";
// we need to know the page count so that we can avoid trying to append (add) when
// there are no pages.. attempting the _thumbs.document.insertPages
var pageCount = _thumbs.getDocumentInfo().count;
// we can not insert if there are no pages existing so we will check
// and switch to "new scan" if there aren't pages
if (_append && pageCount > 0) {
var destIndex = pageCount
var srcIndices = makeSrcArray(_scanCount);
//alert("Inserting " + _scanCount + " pages at index " + destIndex);
_thumbs.document.insertPages(folderWhereFilesUploadTo + eventObj.documentFilename,
srcIndices,
destIndex);
} else {
_thumbs.OpenUrl(folderWhereFilesUploadTo + eventObj.documentFilename);
}
}
},
- Finally modify/replace the original scan button with 2 buttons - one to scan
and open and one to scan with append
- in the Default.aspx page, find the original HTML for the scan button. It
will look like this
<p>Select Scanner:
<select class="atala-scanner-list" disabled="disabled" name="scannerList" style="width:22em">
<option selected="selected">(no scanners available)</option>
</select>
<!-- DO NOT USE <input type="button" class="atala-scan-button" value="Scan" /> -->
<input type="button" id="scanNOW" value="Scan" onclick="scanWithSelectedScanner(); return false;" />
</p>
- Replace it with this:
<p>Select Scanner:
<select class="atala-scanner-list" disabled="disabled" name="scannerList" style="width:22em">
<option selected="selected">(no scanners available)</option>
</select>
<!-- DO NOT USE <input type="button" class="atala-scan-button" value="Scan" /> -->
<input type="button" id="scan_new" value="Scan New Document" onclick="scanWithSelectedScanner(false); return false;" />
<input type="button" id="scan_append" value="Scan and Append" onclick="scanWithSelectedScanner(true); return false;" />
</p>
- That's it - you're done.. go ahead and run the solution. It should look like
this:
- If you start with a blank viewer, then both buttons will simply scan and
open what was scanned. However, if you then go to scan another document.. using
the Scan New Document will REPLACE the existing one where Scan and Append will
append to the existing document.
SAMPLE APP DOWNLOADS
It is our hope that you've been following along with the tutorial and have
successfully built your solution. However, if you've run into issues or if you
want a working reference app, we've implemented BasicWebCapture_withViewer (staring app) and WingScan_withViewer_append (final result) for you to download and run if needed. They also make great
test harnesses for any experimental WingScan code you want to try out... letting
you start from a known-working application.
CONCLUSION
It is possible to seriously customize the viewer and the saving, and it is
possible to perform many other useful tasks with WingScan and with WDV/WDT. This
paper focused specifically on how to enable appending to the existing current
document in the WebDocumentViewer / WebDocumentThumbnailer while scanning.
Please see our growing list of whitepapers for more use cases / examples / tutorials.
v004 - 2024/03/08- TD
Original Article:
Q10470 - INFO: WingScan Whitepaper - Appending Additional Scans