Atalasoft.Controls.Capture. WebScanning






(static) getVersion() → {Array.<number>}

Gets components of WingScan version as an array of numbers.


WingScan version components.


(static) abortScan() → {undefined}

Aborts the current background operation in progress, if any. If there is no current background operation, it does nothing.

Background Operations:


(static) dispose(successopt, erroropt) → {undefined}

This method should be called to shutdown all Web Capture services gracefully and free all acquired resources (for example, correctly close scanners that web application worked with).

Disposed Web Capture Service could be reinitialized by calling {Atalasoft.Controls.Capture.WebScanning.initialize|initialize}.

Name Type Description
[success] function

Callback to be called in case of successful completion of the operation.

[error] function

Callback to be called in case of any errors during dispose.


(static) setProfile() → {undefined}

This method loads the scanning options (scanningOptions) from a string previously produced by getProfile.


(static) enumerateScanners(callback)

Reloads the internal array of the available scanners and optionally passes it to provided callback.

Name Type Description
callback function

Callback accepting array of available scanners.

(static) getCurrentValues(optionsopt, callback)

Query the scanner for current values of scanning parameters.

Errors during this operation will normally result in an asynchronous call to the onScanError handler. If anything goes wrong, it invokes callback({ }).

Name Type Description
[options] ScanningOptions

Scanning options which will be applied to scanner before getting current values.

callback getCurrentValuesCallback

Completion callback accepting current scanner options.

(static) getProfile() → {string}

This method returns a string, containing the current scanning options stored in scanningOptions. The string is in JSON format, but you should not rely on that.


(static) getScanStationName() → {string}

Gets the NetBIOS name of the local scan station.


NetBIOS name of the local scan station is scan control is initialized; undefined otherwise.


(static) getSessionId() → {string}

Gets WingScan client current session id as an string.


session identifier if scan client initialized, otherwise empty string.


(static) getStoragePath() → {string}

Gets WingScan path to persistent storage.


path to persistent storage without session id. It presents expaned form of the following path:

  • on Windows %LOCALAPPDATA%\Kofax\WebCapture\Persistent.
  • on macOS /Users/<current user>/Library/WebCapture.

(static) getSupportedValues(optionsopt, callback)

Query the scanner for supported values of scanning parameters.

Errors during this operation will normally result in an asynchronous call to the onScanError handler. If anything goes wrong, it invokes callback({ }).

Each property in the object has the name of a Atalasoft WingScan scanning-parameter property e.g. pixelType, dpi, and so on. Each property value is one of the following:

  • A enumeration, represented by an array of valid values, for example [0, 1, 3].
  • A range represented by an object with min, max and step properties, for example { min: 50, max: 2400, step: 1 }.


  • Note A few models of scanner may provide incorrect or misleading information through this query, such as a flatbed scanner that lists the value 1 for feeder, implying that you can scan from its (nonexistent) ADF.

  • Querying the scanner's capabilities requires opening the scanner, which may fail (scanner offline, unplugged, etc.) which may display an error box to the user. For friendly user interface design, make 'choose your scanner' or 'change scanner' into a separate dialog or screen, and call getSupportedValues when the user OK's a new scanner choice.

  • Completing the getSupportedValues operation can take several seconds.

Code sample(see, getSupportedValuesCallback for complete list of available properties):

Atalasoft.Controls.Capture.WebScanning.getSupportedValues(null, function(values){
  // if successful might call gotValues with an object like this:
  // {
  //     pixelType: [0, 1, 2],
  //     dpi: {min: 50, max: 1200, step: 1},
  //     duplex: [0, 1],
  //     feeder: [0, 1],
  //     paperSize: [0, 1, 2, 4, 7, 9],
  //     orientation: [0, 1]
  // }
Name Type Description
[options] ScanningOptions

Scanning options which will be applied to scanner before getting supported values.

In scanners API (TWAIN on Windows or Image Capture on macOS) not all capabilities dependencies are documented, so supported values response could differ depending on scanner state. Setting scanning options before querying scanner allows to start from some predictable default configuration or properly handle changes in configuration by setting parameters that should have exact values.

callback getSupportedValuesCallback

Completion callback accepting available scanner options.

(static) setBarcodeLicense() → {undefined}

Set's the barcode license.

If license is not set default barcode engine is used. It's possible to enable Honeywell Omniplanar/SwiftDecoder engine, but license key should be purchased separately. Applicable for Web Capture Service for Windows only.


(static) importFiles(options) → {undefined}

Begin a background process to import files with the specified options. The options object has the same valid properties as the scanningOptions parameter to the scan method above, however, this method ignores options that control the scanner. If options is omitted, null or undefined, importFiles uses the scanning options stored in scanningOptions.

The user is prompted to select one or more files on the local machine, with a standard multi-select File Open dialog. The supported file formats are those listed in File Formats and File Options above, plus PDF. If the user cancels the File-Open dialog, this is treated as an import of zero (0) files.

The title of the dialog is a localizable string named importFilesPrompt.

The selected files are read image-by-image and processed as if they were being scanned - post-processing options are applied to each image - except for PDF files, which are passed through 'verbatim'.

Files are processed in an order determined by Windows, and not necessarily in the order they appear in the File Open dialog nor the order of selection. If order of processing is important, the user must do separate Import operations.

importFiles calls the onScanStarted handler before doing anything else, then calls the onImageAcquired handler with each successfully imported image or PDF file, and finally calls the onScanCompleted handler when finished, whether successful or not.

The eventObj parameter to onScanCompleted has a property success that tells you if the import completed successfully. See the onImageAcquired event for details of how PDF files are imported.

If the user attempts to import any files of unsupported type (such as .doc or .psd) the error unsupportedFileFormat is fired to the onScanError handler and the import proceeds, completely ignoring all those files.

If a file of supported type cannot be imported (e.g. corrupted data, access error), an appropriate error is fired to the onScanError handler and the import process is aborted i.e. completes unsuccessfully.

The images and files imported by importFiles are not retained by the control or uploaded automatically to the server.

This method is called (with no parameters) when the user clicks the designated import button, if any.

Name Type Description
options ScanningOptions

Scanning options.


(static) initialize(params) → {undefined}

This method must be called to initialize the WebScanning component. The init object must contain a handlerUrl property, all other properties - listed below - are optional. Initialization is asynchronous! When this method returns, WebCapture is not yet initialized, and may never be. When initialization is complete (licensing has been verified, a scanner list has been constructed and it is possible to initiate scan or import operations) WebScanning calls the onScanClientReady call-back from the init object.

Asynchronously, initialize attempts to install or start the WebCapture plugin or service, verify licensing, and then to initialize scanning on the client, and to collect a list of available scanners. If it is successful, it will populate a scanner-list control and enable a scan button and/or import button, if they exist with the appropriate classes:

  • If there is a listbox (select element) with class atala-scanner-list, it is loaded with the list of available scanners and the default scanner is selected.
  • Any controls with class atala-scan-button are given a click-handler that calls scan
  • Any controls with class atala-local-file-import-button are given a click-handler that calls importFiles

Remember, the initialization process is asynchronous and may not have finished when the initialize function returns. In fact it may never complete, for example if the browser has ActiveX controls disabled, or if the user declines to install and activate the ActiveX or plugin.

Name Type Description
params Object

WebScanning initialization parameters.

Name Type Description
handlerUrl string

The URL of the web request handler. This is normally a relative URL, for example: 'TestCaptureHandler.ashx'.

Default value: no default.

onImageAcquired onImageAcquiredCallback

See onImageAcquired event.

[onImageDiscarded] function

This handler is called when Web Capture Service discards image.

[onScanClientReady] function

This handler is called when scanning initialization is complete, no matter whether it was successful or not. Note that the scanner list could still be empty if no scanners were detected.

Important: This handler may never be called! Some possible causes:

  • The user declines to install/approve the WebCapture plugin
  • Plugin installation fails.
  • The browser or OS is unsupported.
[onShutdown] function

This optional handler is called when the web page is unloaded or reloaded, prior to any internal WingScan cleanup or shutdown.

Note: any scan or import that is in progress is aborted before this handler is called. If initialize did not succeed, it is possible this handler will not be called. And if you are somehow using WingScan in the Opera browser, this handler will never be called because Opera famously does not support the page-unload event.

[onScanError] onScanErrorCallback

This handler is called to report any errors detected by WingScan/WebCapture. Note that it can be called during a call to any WingScan method, or asynchronously by background operations such as importFiles.

[onScanStarted] function

This handler is called when a scan or importFiles is started.

[onScanCompleted] onScanCompletedCallback

This handler is called when a scan or importFiles ends - successfully or not.

[onUploadStarted] onUploadStartedCallback

This handler is called when a document upload is starting.

[onUploadCompleted] onUploadCompletedCallback

This handler is called when a document upload has completed.

[onUploadError] onUploadErrorCallback

This handler is called when an error occurs during uploading.

[serverTimeout] number

This is the number of seconds to wait for the server response after starting an upload. After this number of seconds, the upload is considered to have failed, it is canceled, and an error is signaled by calling the onUploadError handler.

Default value: 50 (seconds)

[scanningOptions] ScanningOptions

This property must be an object containing scanner settings to be used for scanning.

[uploadOptions] UploadOptions

This property must be an object, which contains (additional) upload settings.

[localization] Errors

This object provides a translation table for all potentially user-visible strings used by Atalasoft DotImage. See Atalasoft.Controls.Capture.Errors for all possible strings.

Default value: {} - which selects the default American English localization.


(static) isInitialized() → {boolean}

Checks if Web Scanning control is initialized or not.


True if Web Scanning control is initialized; false otherwise.


(static) scan(options) → {undefined}

Initiates a scan, as a background process, with the specified scanning options (see Scanning Options#scanningOptions). If you pass in nothing, null or undefined, it uses the scanning options stored in Atalasoft.Controls.Capture.WebScanning.scanningOptions.

This method is called (with no parameters) when the user clicks the designated scan button.

Use abortScan to abort a running scan.

When a scan is started it calls the onScanStarted handler, and when it ends, normally or not, it always calls the onScanCompleted handler.

Name Type Description
options ScanningOptions

Scanning options.


(static) showSettingsDialog(options, callback) → {undefined}

Starts a background operation to display the settings-only dialog (custom user interface) of the scanner, if the scanner supports this feature.

Note: no scanner driver provides settings dialog under macOS

This shows a version of the scanner's UI that is only for choosing settings, without a Scan button.

When the operation completes, successfully or not, callback(status) is called, where status is an object. status.complete is true if the dialog was successfully displayed and closed by the user, false if the dialog could not be displayed or the operation was aborted.

If anything goes wrong, the onScanError handler will be called, asynchronously, with details.

The scanner used is:

  • options.scanner if that exists and is a string.
  • Otherwise scanningOptions.scanner if it exists and is a string.
  • Otherwise the scanner most recently selected in the UI.
  • Otherwise the default scanner, as reported by scanner device manager (TWAIN on Windows or ImageCapture on macOS).
Name Type Description
options ScanningOptions

Scanning options.

callback notificationCallback

Completion callback.


(static) saveBase64ToEncryptedLocalFile()


(static) listLocalFiles()


(static) deleteLocalFile()


(static) encryptedLocalFileAsBase64String()


(static) setSymmetricEncryptionKey()



onImageAcquired :onImageAcquiredCallback

The onImageAcquired handler is called during scanning, once for each image received from the scanner, with a single parameter which is an image object - that is, an object that represents the received image held by WingScan. The image object provides a rich set of properties and a small set of methods for exporting the image data in various ways.

The onImageAcquired handler is also called by the importFiles method, once for each imported image, and once for each imported PDF file.

Imported PDF files are handled somewhat specially: they are represented by an image object with the distinguishing property filename - which is the full path of the imported file. When the filename property is present, the usual image properties are absent. The image object that represents an imported PDF still supports the methods asBase64String, clear, saveEncryptedLocal, and thumbnail.

onImageDiscarded :notificationCallback

Called when Web Capture Services discards image. This can happen, when flag discardBlankPages is set.

onScanClientReady :notificationCallback

This handler is called when scanning initialization is complete. Normally in case of failure the onScanError handler will have been called.

onScanCompleted :onScanCompletedCallback

Called when scan or import completed. See Handling Errors for details.

onScanError :onScanErrorCallback

Called when scan or file import completed with error.

onScanStarted :notificationCallback

Called when scanning starts.

onUploadCompleted :onUploadCompletedCallback

Fired when scanned document upload completed.

onUploadError :onUploadErrorCallback

Fired when scanned document upload completed with error.

onUploadStarted :onUploadStartedCallback

Fired when scanned document upload started.