Login   Company   1-781-743-2119    

WINGSCAN WHITEPAPER: GETTING STARTED (11.1 version)

GETTING STARTED WITH WEB SCANNING in 11.1

PLEASE NOTE: this is the version of this whitepaper that applies to 11.1 of DotImage. The original was written for 11.0 and there are significant enough changes that the main article was rewritten.

Please see Q10477 - INFO: WingScan Whitepaper - Getting Started with Web Scanning (11.0 version) for the old 11.0 version.

WingScan is a web-based TWAIN scanning SDK that allows developers to add scanning support to existing or new web applications. WingScan can be purchased as a stand-alone SDK. This level of licensing allows developers to add our Web Scanning components to a web site and allows LIMITED use of the WebDocumentViewer (Using only a WingScan license, WebDocumentViewer will allow viewing only of documents scanned in the current session., and does not allow any custom handling. Viewing, annotation, rotation, page reordering (via drag/drop on the thumbnail viewer), and saving are supported via defaults.

Any custom handling or even viewing of documents from previous sessions require a license to DotImage Document Imaging to fully unlock the WebDocumentViewer)

In our getting started section, we're going to start out with a pure scanning with no viewing in order to show you the absolute minimum WingScan setup possible. This is useful for situations where you are just adding scanning to an existing app and already have viewing in place or do not require a viewing component.

We'll then move on to show using WingScan with the WebDocumentViewer and WebDocumentThumbnailer controls under the WingScan only license.

More in-depth discussion of the full WebDocumentViewer and WebDocumentThumbnailer controls are provided in our WebDocumentViewer guide.

The idea here is once you have a sense of using WingScan, you can see how to add it to any application.

 

WINGSCAN HISTORY

Originally, this paper was going to include a history of WingScan web scanning, but for the sake of brevity we'll just link you here:
Q10461 - INFO: A Brief History of Web Based Scanning at Atalasoft

 

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 DotImage 11.0 and up support .NET 3.5 (using our 3.5 dlls) or .NET 4.5.2 or greater (using our 4.5.2 dlls) .. support is not possible for .NET 4.0, 4.5 or 4.5.1 using DotImage 11.0 or up. If you have an existing app you want to add DotImage to that targets an unsupported .NET framework, you will need to update it.

Also note that this document covers a standard ASP.NET web app, not ASP.NET Core. We do have support for ASP.NET core targeting .NET framework (not pure .NET Core), 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.1.0.1 as of January 2019)

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.1.0.1 as of the creation of this document (January 2019) 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

If you have not done so, please create an account with Atalasoft so that you can download and activate our SDK

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\WingScanTestApp\

Then you'd copy your licenses from:
C:\users\YOUR_USERNAME\AppData\Local\Atalasoft\DotImage 11.1\
to
c:\inetpub\wwwroot\WingScanTestApp\bin\

 

EXAMPLE 1

BUILDING A MINIMUM WINGSCAN APP

We're going to be creating the minimum possible WingScan application. It's just going to scan and upload.

While this may seem not too useful, it's the fundamental minimum you need to add scanning. Your use case may not involve using our viewers (we'd love you to, but maybe you have another viewer, or maybe your app is meant to be fairly utilitarian and viewing isn't needed. Either way, this minimalist approach should be easily adaptable to any application where you want to add scanning. Don't worry, we will get fancier in a bit. For now, we're going to start with the basics.

 

MAKING IT BETTER

Ok, so the interface is really minimal and all it does is scans and uploads, but when it encounters errors, it really isn't al that helpful.

That's Ok we can make it better

One of the first things I like to do is to handle the "no plugin/ out of date plugin" errors. This is because in a real app, you would probably rather have your customer be prompted to download/install the viewer directly.

Ok, so let's flesh out the error handling.

We're going to be greatly expanding upon the scanerrorHandler we set up earlier.

// this is a really simplified error handler for now... we can expand on this later
function scanErrorHandler(msg, params) {
	alert(msg);
}

If you note: there are two components, the message (msg) and the parameters (params). When you get an error, there will always be a message, but parameters are only present for specific errors where they are needed.

The WingScan components have a set of predefined messages.. this is handy both for translations to other languages as well as using in a switch/case statement to allow for custom messaging.

First, here's a list of the errors and their meanings:

Error Code Default Message
ajax Could not create an XMLHttpRequest object needed for uploading.
badBrowser Scanning requires Chrome, FireFox, or Internet Explorer (at least version 8 and with Compatibility View Mode disabled) running on Windows.
badVrsLicense VRS license is missing or invalid.
batchFieldsError The server could not retrieve the batch fields for the selected batch class.
batchFieldValidationError Batch field validation failed.
brokenConnection Connection to the scanning service is broken. You may need to refresh the page to restore it.
contentDescError The server could not retrieve the content description.
contentTypesError The server could not retrieve content types.
docClassIndexFieldError The server could not retrieve the index fields for the document class.
doorOpen Scanner reports cover open.
doubleFeed Scanner reports a double-feed.
driverCrash Fatal exception in scanner driver.
dsmFail Failure in TWAIN Manager.
dsOpen Failed to open scanner.
fieldValidationError Batch, or index field validation failed.
fileFail File not found or cannot be written or cannot be read.
fileLocked File locked by other application.
helperDll Failed to load scanning service helper DLL.
importError The server could not import the document.
indexFieldValidationError IndexField validation failed.
internalError Unexpected internal error.
licensingError The server did not return valid licensing information.
lowIntegrityAccessDenied Access to the Web Capture Service is denied because the current user has insufficient rights. This can have happened if you have visited site with the untrusted certificate or connect to the Web Capture Service from internet. Contact your administrator for assistance.
noPlugin The scanning service needs to be installed. If it is installed it may need to be enabled. In the browser look for Add-ons, Plugins, Kofax scanning.
noTwain The TWAIN Manager needs to be installed.
oldPlugin The scanning service needs to be updated to a newer version.
oldWindowsService The scanning service needs to be updated to a newer version. Contact your administrator for assistance.
outOfMemory Insufficient memory to complete an operation. Restarting the Scanning Service may help.
paperJam Scanner reports a paper jam.
scanFail Unable to start scan.
serverNotResponding The server is not responding.
tooManyImages Too many images for Scanning service to handle.
unsupportedFormatWarning Warning: Only the following image file types are supported for import: BMP, GIF, JPG/JPEG, PDF, TIFF. All other file types will be ignored and will not be imported.
uploadError The server reported an error while uploading.
userCancel
vrsBadCommand eVRS command string is invalid.
vrsBadDpiWarning Warning: One or more images were skipped - Image Enhancement requires image DPI > 25
webServiceMissed Web Capture local service is not running.
xferFail Image transfer from scanner failed.

We could custom handle any/all of these.. but realistically, our default displaying of the message will do.. so we can just concentrate on ones where we want some special handling.

The ones needing our attention are:

noPlugin and oldPlugin are errors that happen when a local user account has either not installed the web capture service, or has an out of date version of it respectively. The fix for both situations is to provide them with a link and install instructions.

webServiceMissed and oldWindowsService are similar, but are related to running in a Terminal Server / Citrix environment where the administrator must install the WCS as a system service

noTwain is important because the default message isn't instructive enough.

These examples will show you the pattern of how to handle such errors so you can add your own custom error handling for any/all events.

// This is an updated handler with more sophisticated handling of certain errors
function scanErrorHandler(msg, params) {
	switch (msg) {
		case Atalasoft.Controls.Capture.Errors.noTwain:
		    alert("This web capture application requires that you have at least one " +
		    "valid TWAIN device installed and configured. Please ensure you install " +
		    " the TWAIN driver for your scanner device(s) then re-visit this site.");
			break;
		case Atalasoft.Controls.Capture.Errors.oldWindowsService:
		    alert("The version of Kofax WebCapture Service running on the multiuser " +
		    "system you're using is out of date. Please contact your system administrator.");
			break;
		case Atalasoft.Controls.Capture.Errors.webServiceMissed:
		    alert("The Kofax WebCapture Service on the multiuser system you're using  " +
		    "is not running. Please contact your system administrator.");
			break;
		case Atalasoft.Controls.Capture.Errors.noPlugin:
        	var installerUrl = window.location.protocol + "//" + window.location.host + "/WebCapture/" + params.filename;
        	window.open(installerUrl, '_downloadService');
            alert(
            	"The WingScan Web Scanning service is not available. \n\n" +
            	"If the download doesn't start automatically, please download from " + installerUrl + "\n\n" +
            	"If you are not prompted to install, the service may be installed but not running. \n\n" +
            	"enable it by running from START->All Programs->Kofax Web Capture Service->Kofax Web Capture Service  \n\n" +
            	"Refresh your browser when completed.");
            break;
		case Atalasoft.Controls.Capture.Errors.oldPlugin:
			var installerUrl = window.location.protocol + "//" + window.location.host + "/WebCapture/" + params.filename;
			window.open(installerUrl, '_downloadService');
        	alert(
            	"The WingScan Web Scanning service is out of date.<br />" +
            	"If the download does not begin automatically, please go to " +
            	params.filename);
            break;
		default:
			alert(msg);
			break;
	}
}

 

EXAMPLE 2

WING SCAN WITH VIEWER

Up to this point, the whole setup has been bare minimum, but now let's say you want to have users view the document they scanned.

WingScan licensing on its own (without DotImage Document Imaging) gives you limited use of the WebDocumentViewer and WebDocumentThumbnailer controls. They are not able to be used to open or modify images from other sources, but they can be used to view images just captured in the current session.

This paper will explain the basics of hooking up the WDV and WDT to the WebCapture scanning. For more advanced approaches to our web viewing controls unlocked with a full DotImage Document Imaging license see WebDocumentViewer Whitepaper.

The getting started steps are going to be nearly identical to the Wingscan_noviewer sample app, but there are several significant differences, so you probably will run into issues if you just try and modify the noViewer sample.

 

MAKING IT BETTER

Ok, so you can scan and view. The viewing components do not allow a lot of customization without a license for DotImage Document Imaging. However, one thing that you may want to to (and can do with this level of licensing) is enable saving. So, now, let's modify the app to enable the save button so you can annotate and rotate and re-order your thumbs and then save.

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 both the WingScan_noViewer and WingScan_withViewer 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, but you would need a license for DotImage Document Imaging and a bit more information to do that. The upcoming WebDocumentViewer Whitepaper will go into more details about the WebDocumentViewer. For now, we've shown you how to use the base WebCapture and WebDocumentViewer with WebDocumentThumbnailer controls using only a WingScan license.

v011a - 2019/05/23 - TD