TWAIN Acquisition in DocuVieware

Although part of the daily work in many document workflows, TWAIN acquisition in web applications is not as straightforward in a traditional Windows application for several technical reasons.
The first is that a web application is not able to access certain resources of the system for obvious security reasons, instead, the web applications work in a kind of sandbox with limited rights and access.
The other difficulty is the fact that the web application comes in two separate parts, client and server, which must communicate. But the server part has no access to the client system in this context.

It would be tempting to use the many TWAIN methods and options already present in GdPicture.NET™ for this but, for the reasons mentioned above, only devices connected to the server would be visible.

To overcome these technical difficulties, DocuVieware™ offers a simple and transparent tool that allows the connection and communication between the web application and the TWAIN acquisition devices.

This tool is a lightweight, self-contained, secured software component that installs locally on the client machine (this is a one-time operation).
This component is available as an MSI package that is embedded and served by DocuVieware™ directly. This way you are assured that you users always have the right version.

The TWAIN acquisition capabilities of DocuVieware™ are very easy to use since they are built-in and enabled by default through the EnableTwainAcquisitionButton property.
It comes with standard support for any TWAIN compliant acquisition device and a dedicated acquisition dialog that lets you choose the source and the destination of the acquired pages (either append to the currently loaded document or into a new one).

While this might be enough for many cases, sometimes you may need a finer control over the process and the acquisition options in your business process.
In this case, you can use the JavaScript client API to take control of the TWAIN acquisition and customize its behavior as needed as described in the next part.

Whether you use the default built-in feature or implement your own acquisition process with the API, the acquisition result is the same: all acquired pages will automatically go directly into the corresponding DocuVieware™ instance to be handled just like any other document.
This makes the process consistent and natural regardless of the source, whether it is a document open from a local, remote source or an acquired document.

Here is the workflow that must be followed to proceed with the TWAIN acquisition using the API. For this example let's assume your DocuVieware™ instance is called DocuVieware1.

1. Check for local service status

   This is done by simply calling the TwainGetLocalServiceStatus method, as documented, it returns a value that will let you know if the local service is either ready, not responding or if the wrong version is running.

   In case the service is not running (or if the wrong version is running) you can start the download process of the latest version by calling the TwainDownloadServiceSetup method.

   This software will require administrative rights to be installed on the client machine.
   It is also recommended to close all the browsers before installing the package.
   The software will start automatically with Windows after installation.
   • JavaScript

   Checking the local service status.	Copy Code
   var status = DocuViewareAPI.TwainGetLocalServiceStatus("DocuVieware1"); if (status !== 0) { console.log("Local service cannot be accessed. Please install it now."); DocuViewareAPI.TwainDownloadServiceSetup("DocuVieware1"); }

2. Retrieve the available devices

   Now that you know the service is up and running, you can retrieve the list of the TWAIN devices installed on the system.

   This is done using the TwainGetSources method that will not only return the source name but also a few details information about it in case you need it.

   • JavaScript

   Retrieving the available devices.	Copy Code
   var sourceList = DocuViewareAPI.TwainGetSources("DocuVieware1"); if (sourceList != null) { var source = sourceList.defaultSource; console.log("Default source is " + source); } else { console.log("No available source have been found."); }

3. Define the acquisition parameters

   This step can be done anytime in the process, it can set the parameters for the subsequent acquisitions or simply set the parameters for the next one so if you call it between two batches you can set different options.

   The method to call to do that is TwainSetConfig and it allows you to easily set the most common acquisition parameters such as the bit depth, resolution, duplex, if you want the device driver UI to be shown for advanced configuration or if you want it hidden.
   It also allows you to set advanced options if the scanning device supports it.

   For a 24-bit, 200 DPI acquisition from document feeder without showing the device driver UI and with red color dropout enabled, it would be:

   • JavaScript

   Defining the parameters.	Copy Code
   DocuViewareAPI.TwainSetConfig("DocuVieware1", true, true, 200, 24, false, true, [{ capability: DocuViewareAPI.TwainCapabilities.ICAP_FILTER, value: "0" }]);

4. Acquire from the source

   Everything is ready, you can proceed with the acquisition itself. The only thing left to choose now is where the acquired pages should go.

   Two options are available, you can acquire to a new document so it will only contain the pages from the batch, or, you can choose to append the pages to the existing document (currently loaded document).

   For acquisition to a new document, the method to call is TwainAcquireToNewDocument and you just need to provide the source name you want to acquire from.

   If you want to go with option two, you can also choose where you want to append the new pages. It can be at the end of the document, before the current page or after the current page. In any case, the method to do that is TwainAcquireToCurrentDocument.
   It is basically the same but with an extra parameter to set the position.

   Let's assume we want to acquire pages at the end of the currently loaded document from a device called "TWAIN2 FreeImage Software Scanner" (virtual scanning device from the TWAIN Group) that would be:

   • JavaScript

   Acquiring from the source.	Copy Code
   DocuViewareAPI.TwainAcquireToCurrentDocument("DocuVieware1", "TWAIN2 FreeImage Software Scanner", 1);

Now that you have acquired content in your DocuVieware™ instance, you can save the document. As always in DocuVieware™, the current document only exists server side so to proceed with the file saving operation there are a few different options.

To save the document locally (on client machine) the built-in Save feature is available, it can also be done using the Print feature (and choose PDF over printer for output).

However, if you need to save the document server side (to push it into a database or to export it to a filesystem of some sort for instance) then, you will need to implement a Custom Action so please refer to the corresponding tutorial to learn more.

Technically speaking, the document acquired in DocuVieware™ takes the form of a multipage image document.
You are free to keep it as is (and save it in TIFF, the document format of choice for this case) or to convert it to another format more adapted to your needs like the PDF for example. In both cases, you can achieve it by simply calling either the SaveAsTIFF or SaveAsPDF method.

Reference

Actions

Web Forms

MVC Razor

Other