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 );
You may need to set the SameSite attributed of the FileHold session cookie if you will embed these pages in the iframe of another application.