Tutorial: Document Capture Server Configuration

Document Capture Server Configuration

 This section covers documents to remote services such as Kofax Import Connector and SharePoint.

Connect to SharePoint

SharepointHandler limitations

  • Sub-sites are not supported.
  • Folder navigation is not currently supported, documents will only be imported into the top.
  • Document libraries are currently the only type of SharePoint list support for document import.
  • Setting additional fields other than the title, and name for specific list ContentTypes is not supported.

Add a SharepointHandler to a project

These are the basic steps to add a SharePoint handler to your application.

General setup

  • Create or open a web application project in your development environment.
  • Add the Atalasoft.dotImage.WebControls reference .
  • Add licensing information to the project.
  • Make the necessary configuration changes to your project.

Add the handler

  • Add a new generic handler to the project.
  • Extend the new handler from the SharepointHandler class found in the Atalasoft.dotImage.WebControls.Capture namespace in the Atalasoft.dotImage.WebControls assembly.
  • Add any additional authentication or handler logic if you need it.

Add the client

  • Add the WebDocViewer client files and handler to your project.
  • Modify the JavaScript API configuration to point to the correct WebDocViewer and SharePoint handler URLs.

Refer to the included WebCaptureDemo for an already configured project. The demo's client .aspx file will need to be modified to point to the SharepointHandler for its capture handler instead of another capture service.

Extend and configure SharepointHandler

The SharepointHandler needs to be extended to handle SharePoint authentication and to configure the services connection. The minimum required configuration that must be specified is the SharepointWsdlLocation for connecting with SharePoint Web services. In addition to the standard WCF elements, endpoints and bindings must be added for each of the CMIS services, and the SharePoint List Service. In the examples below only a basicHttpBinding is shown. Use of a different type of binding is possible.

Add the endpoints to web.config

Endpoints must be specified for the Copy, Lists, and Web SharePoint Web services, which should be placed in the <client> section of<system.serviceModel> in your configuration. If you are extending the SharepointHandler and SharepointConnector, you may need to specify endpoints to additional SharePoint Web services. For a complete list of SharePoint 2010 Web services, see: http://msdn.microsoft.com/enus/library/ee705814.aspx.

<endpoint address="http://your.sp2010server.com/_vti_bin/Lists.asmx"binding="basicHttpBinding" bindingConfiguration="ListsSoap" contract="ListsSoap" name="ListsSoap" />
<endpoint address="http://your.sp2010server.com/_vti_bin/Copy.asmx" binding="basicHttpBinding" bindingConfiguration="CopySoap" contract="CopySoap" name="CopySoap" />
<endpoint address="http://your.sp2010server.com/_vti_bin/Webs.asmx" binding="basicHttpBinding" bindingConfiguration="WebsSoap" contract="WebsSoap" name="WebsSoap" />

Add the bindings to web.config

For each endpoint, specify a corresponding binding. All SharePoint bindings require an MTOM message encoding.

The following block shows the binding to pair with the SharePoint Lists service endpoint bindings

<binding name="ListsSoap" closeTimeout="00:01:00" openTimeout="00:01:00" receivei``meout="00:10:00" sendTimeout="00:01:00" allowCookies="false"
         bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard" maxBufferSize="65536" maxBufferPoolSize="524288" 
         maxReceivedMessageSize="65536" messageEncoding="Mtom" textEncoding="utf-8" transferMode="Buffered" useDefaultWebProxy="true">
<readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384"/>
  <security mode="TransportCredentialOnly">
    <transport clientCredentialType="Windows"/>
  </security>
</binding>

Using this binding as a template, create a binding for each of the following names, which correspond to endpoints.

  1. ListsSoap
  2. CopySoap
  3. WebsSoap

Apart from the name attribute, each of these bindings will have the same configuration unless you have a reason to customize. The maxReceivedMessageSize attribute may need to be adjusted depending on the amount of content that will be returned for a specific repository.

Set the atala-upload folder location

By default, the client javascript api uploads scanned documents to a folder named atala-upload-folder in the root of the website. To change the location where scanned documents are stored, add the following to the <appSettings> section of your configuration.

<add key="atala_uploadpath" value="C:\explicit\path\to\upload\directory"/>

Web applications authentication

If you are configuring a web application, make sure the following settings are in the web.config file, <system.web> section.

<authentication mode="Windows"/>
<identity impersonate="true" />

Authentication

The available authentication options depend upon how SharePoint and the web application containing the SharepointHandler are deployed. Due to restrictions in the Windows security model, communicating with SharePoint using client impersonation is not possible when the SharePoint server and hosted web application reside on different servers. The delegating IIS server in the middle is not able to forward network requests of the originating client on to the remote SharePoint server. In this environment, you are limited to the following options to successfully communicate between the client scanning application and SharePoint

Specify a User Account in web.config

Specify the username and password of an ActiveDirectory user in the <identity> tag in your web.config. IIS will impersonate the specified user when making requests to the remote SharePoint server.

<identity impersonate="true" userName="DOMAIN\username" password="password" />

Override CreateAuthenticationSession in your handler

AuthenticationSession objects are used by the SharepointHandler to perform actions before and after making requests to SharePoint. Overriding CreateAuthenticationSession allows you to specify what AuthenticationSession object should be used at those points. By default the SharepointHandler uses a NullAuthenticationSession, which performs no actions. Another available type is the CredentialAuthenticationSession, which is constructed with the domain, username, and password of a Windows account, and instructs IIS to impersonate the specified user. This is similar to specifying an account in web.config, but the impersonation is only used while making SharePoint requests, rather than being used across the entire website.

public class Handler : SharepointHandler
{
    protected override AuthenticationSession CreateAuthenticationSession()
    {
        return new CredentialAuthenticationSession("DOMAIN", "username", "password");
    }
}

It is also possible to write your own types by deriving from AuthenticationSession and implementing the abstract methods Enter and Leave, which setup and undo any changes in authentication.

You may want to write your own AuthenticationSession if you need to impersonate a user that is dynamically fetched from your own user store, rather than specifying a single account to use for all requests.

Certificates

By default, only valid certificates can be used to successfully connect the handler to SharePoint over a secure connection. For more information on setting up certificates and certificate stores, see: http://msdn.microsoft.com/en-us/library/ff648360.aspx.

Connect to KIC

These instruction are for configuring an application to connect to an existing Kofax Import Connector server.

Extend the KicHandler

  1. Open the web application project in you development environment.
  2. Add a generic handler to the project.
  3. Extend the handler that was just created with the KicHandler found in the Atalasoft.dotImage.WebControls.Capture namespace in the Atalasoft.dotImage.WebControls assembly.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;

namespace TheApplicationNamespace
{
    public class MyKicHandler : KicHandler
    {

    }
}

Configure KicHandler

Add the KIC endpoints to web.config

To connect to Kofax Import Connector a WCF endpoint, a binding must be added to the application’s web.config. In the provided example a standard basicHttpBinding will be used, but other appropriate binding types are possible choices to use as the WCF binding.

<system.serviceModel>
  <client>
    <endpoint address="http://servername.domain.com:[port]/soap/tsl"  binding="basicHttpBinding" bindingConfiguration="importBinding" contract="importPortType" name="importPort" />
  </client>
</system.serviceModel>

Add the bindings to web.config

  • HTTP

    <system.serviceModel>
    <bindings>
      <basicHttpBinding>
        <binding name="importBinding" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" 
                 allowCookies="false" bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard" maxBufferSize="1655360"
                 maxBufferPoolSize="15242880" maxReceivedMessageSize="1655360" messageEncoding="Text" textEncoding="utf-8" 
                 transferMode="Buffered" useDefaultWebProxy="true">
          <readerQuotas maxDepth="32" maxStringContentLength="256000" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384" />
          <security mode="None">
            <transport clientCredentialType="None" proxyCredentialType="None" realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
          </security>
        </binding>
      <basicHttpBinding>
    </bindings>
    </system.serviceModel>
  • HTTPS

    <system.serviceModel>
    <bindings>
      <basicHttpBinding>
        <binding name="importBinding" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" 
                 allowCookies="false" bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard" maxBufferSize="1655360" 
                 maxBufferPoolSize="15242880" maxReceivedMessageSize="1655360" messageEncoding="Text" textEncoding="utf-8"
                 transferMode="Buffered" useDefaultWebProxy="true">
          <readerQuotas maxDepth="32" maxStringContentLength="256000" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384" />
          <security mode="Transport">
            <transport clientCredentialType="None" proxyCredentialType="None" realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
          </security>
        </binding>
      <basicHttpBinding>
    </bindings>
    </system.serviceModel>

Configure Kofax Import Connector

This is not intended to be a full set of instructions to install, setting up, and maintain a Kofax Import Connector server. The following information provides the minimum amount of configuration needed for the Web Capture Service to successfully connect, and import into Kofax Import Connector.

Required license

For the KIC web server to accept documents imported from the Web Capture Service the license must be installed on your KIC server.

To verify that the correct minimum license has been installed go to the Message Connector Monitor, which by default is located on the KIC server at https://localhost:25086/file/index.html under the Status -> license section.

Configure the web service

The Web Capture Service connects via KIC’s web service via a server-side handler that extends the KicHandler found in the Atalasoft.dotImage.WebControls assembly.

Once in the message connector, go to the “General” section, and verify that

  1. From the App Programs list, select Kofax > KIC Electronic Documents > Message Connector Configuration. The message connector opens.
  2. In the General section, verify the Own Computer Name is filled in with the current server’s domain qualified name.
  3. Next, go to the Web-Service Input section.
    • If only a HTTP based connection is desired set the HTTPS port to 0. This will be the port which the endpoint in the application's will point to. If HTTPS is desired, then enter the port which will be used.
    • If HTTPS is enabled the HTTP port will not be able to be connected to, and the endpoint in the application's will need to point at the URL using the HTTPS port.
  4. Once all of the desired changes to the KIC Message Connector have been made save, and restart the Message Connector service.

Configure the Electronic Documents plugin

In the Kofax Capture (KC) Administration application, open the 'Electronic Documents -> Configuration' window, and configure the necessary Connections, and Destinations.

When finished, stop and start the service.

Test the configuration

To test that the KIC server has been minimally configured correctly in a browser either on the server, or at a client that might connect to the server enter the following URLs:

  • HTTP enabled webservice

    http://[kic_servername]:[http_port]/soap/tsl/Import?<OwnerReference>myref</OwnerReference><Address>importaddr</Address><Part><ContentType>text/plain</ContentType>    <Content><Text>hello</Text></Content></Part>
  • HTTPS enabled webservice

    https://[kic_servername]:[https_port]/soap/tsl/Import?<OwnerReference>myref</OwnerReference><Address>importaddr</Address><Part><ContentType>text/plain</ContentType>    <Content><Text>hello</Text></Content></Part>