Integrating web scanning, web viewing, and adding documents with your application

It is possible to integrate web scanning (WebCap), web viewing and the add document wizard with external applications in a way that is fairly seamless to end users. In all cases, direct access URLs are available to the external application. In order to give a seamless integrated appearance to users it is possible to enable a minimal user interface that is isolated to only web scanning, web viewing, or adding documents. In addition, information can be passed to FileHold to open a specific document or preset metadata before scanning.

WebCap is a deprecated technology. It is maintained here for the convenience of legacy implementations.

Direct access to web scanning or adding documents

Use the following URL to directly access the scanner inbox. The user must be logged in and have a license for using web scanning.

<protocol>://<server>/FH/FileHold/WebClient/InboxForm.aspx<optional_parameter>

The <protocol> will be either HTTP or HTTPS depending on your configuration. <server> is the name or IP address of your web client or application server. The <optional_parameter> is ?ui=lock to indicate that the full FileHold interface should be suppressed. If this parameter is left out, the normal FileHold user interface will be used.

For the add document wizard, replace InboxForm with AddDocumentWizardForm. The user must have a document publisher role or higher.

Post scanning or add document actions

If the full user interface is used, web scanning will return to the screen where it started from when the user presses the return button. When the document is submitted, the user will be taken to the library location where the document is stored and the metadata panel will be displayed.

There are two options when the full FileHold interface is suppressed. A return button can be enabled or not. The button will be enabled if the calling application or configuration supplies an URL to return to. The user will be taken to the same URL when the document is successfully submitted. If a return URL is not supplied, there will be no return button and when the document is successfully submitted the user will receive a success message and remain on the same page.

Direct access to web viewing

Details for directly accessing the web view are available at Hidden Document URL Links. The user must be logged in and have a license for using the web viewer. If they do not have a license assigned or if the file type is not supported by the web viewer, the document will be downloaded to the browser. Depending on the file type and the viewers available for the browser, the document may be displayed on the local workstation.

Using a pre-existing session

It may be desirable for the calling application to create and maintain a session on the user's behalf. This will allow the user to avoid a prompt to login into FileHold when the page is opened. This is done by calling the login form and passing the session id and final destination URL as a parameter.

<protocol>://<server>/FH/FileHold/WebClient/LoginForm.aspx?sessionId=<ID>&originalUrl=<originalUrl>

Here is an example assuming the protocol is https, the server address is filehold.example.com, the session GUID is 696420e2-bb93-4f39-a6f2-38f09b016428, and the destination is the locked web scanning form.

https://filehold.example.com/FH/FileHold/WebClient/LoginForm.aspx?sessionId=696420e2-bb93-4f39-a6f2-38f09b016428&originalUrl=%2FFH%2FFileHold%2FWebClient%2FInboxForm.aspx%26ui%3Dlock

Configuring the return page

The return page is where the client goes when the user presses the back or close button. The return page can be defined at run time using the ScanningManagerService of the API or it can be statically configured in managed options. The placeholder values should be replaced with relative or absolute URLs. Relative URLs will execute in the context of the web client. If the return page is defined both in managed options and using the ScanningManagerService the latter will take precedence.

AddDocumentWizard.ReturnPage
ScannerInbox.ReturnPage
Viewer.ReturnPage

Setting parameters at runtime

In addition to the return page, a variety of parameters are available for the scanning and add document forms to set where the document will be filed, the schema and metadata that should be used, and scanning specific parameters. See the API documentation for more details on the ScanningManagerService.SetSettings() method.

Example of preparing web scanning metadata

Prior to calling web scanning it is possible to pre-populate metadata for the document. This allows the calling application to pre-fill any known information and save the user from doing this manually. The follow is an example of pre-populating metadata using the ScanningManagerService. It pre-fills two metadata fields and the return page for web scanning.

// set the document schema ID
// - schema ids can be retrieved with DocumentSchemaManager.GetElectronicSchemaList()
      int documentSchemaId = 123;

// create and fill an array of metadata fields
// - metadata field ids can be retrieved with DocumentSchemaManager.GetDocumentSchemaFields()
      ScanningManagerService.FieldWithValue[] fields = new ScanningManagerService.FieldWithValue[ 2 ];
      fields[ 0 ] = new ScanningManagerService.FieldWithValue() { FieldId = 1234, FieldValue = "Value1" };
      fields[ 1 ] = new ScanningManagerService.FieldWithValue() { FieldId = 1235, FieldValue = "Value2" };

// serialize the array of metadata fields to an XML string
      System.Xml.Serialization.XmlSerializer serializer =
            new System.Xml.Serialization.XmlSerializer( typeof( ScanningManagerService.FieldWithValue[] ) );
      System.IO.MemoryStream stream = new System.IO.MemoryStream();
      serializer.Serialize( stream, fields );
      byte[] bytes = stream.ToArray();
      string serializedMetadata = System.Text.Encoding.UTF8.GetString( bytes );

// set the return page URL
      string returnPage = "http://www.example.com/";

// create and authenticate a reference to the ScanningManager service
      ScanningManagerService.ScanningManager manager =
            new ScanningManagerService.ScanningManager();
      FileHold.Common.Authentication.AuthenticateService( manager );

// create and fill an array of settings
      ScanningManagerService.ScanningSetting[] settings =
            new ScanningManagerService.ScanningSetting[ 3 ];
      settings[ 0 ] = new ScanningManagerService.ScanningSetting
            { Key = "DocumentSchemaId", Value = documentSchemaId.ToString() };
      settings[ 1 ] = new ScanningManagerService.ScanningSetting
            { Key = "MetadataValues", Value = serializedMetadata };
      settings[ 2 ] = new ScanningManagerService.ScanningSetting
            { Key = "Inbox_ReturnPage", Value = returnPage };

// pass settings to the Scanning Manager service
      manager.SetSettings( settings );