Kofax Consultant - Custom Text Export Setup Guide Text Export Setup... · 2020. 10. 5. · to the...

David Crewe Ltd Custom Text Export

Registered Office: 21 Enfield Cloisters, Fanshaw Street, London. N1 6LD Registered in England and Wales: No. 06212509

Custom Text Export Setup Guide

Customisable Template Text Export Connector for Kofax Capture

V3.0.2



Contents

1 OVERVIEW ..................................................................................................... 3

1.1 FIXED ISSUES ...................................................................................................... 3 1.2 NEW FEATURES IN V3.0 .......................................................................................... 3

2 INSTALLATION .............................................................................................. 4

3 CONFIGURATION ........................................................................................... 4

3.1 DEFAULT STORAGE ................................................................................................ 4 3.2 INDEX STORAGE ................................................................................................... 5

3.2.1 Template Files ............................................................................................ 6 3.2.2 Custom Template Export – File Per Document ................................................. 7 3.2.3 Custom Template Export – Specific File .......................................................... 7

3.3 ADVANCED .......................................................................................................... 9 3.4 CUSTOM SETTINGS .............................................................................................. 10

3.4.1 General Settings ....................................................................................... 10 3.4.2 Conditional Export Settings ........................................................................ 12 3.4.3 Date Format Settings ................................................................................. 13 3.4.4 XSLT Transformation Settings ..................................................................... 13 3.4.5 SQL Statement Settings ............................................................................. 13 3.4.6 Email Settings .......................................................................................... 14

3.5 TEMPLATE DESIGNER ............................................................................................ 15

4 GENERAL CONSIDERATIONS ........................................................................ 16

4.1 REGISTERING COMPONENTS ................................................................................... 16 4.2 CUSTOM PATH AND FILENAME VALUES ....................................................................... 16 4.3 CUSTOM FILENAME DEFINITION ............................................................................... 16 4.4 SINGLE PAGE FORMATS AND E-DOCUMENTS ................................................................ 16 4.5 SQL STATEMENTS ............................................................................................... 17 4.6 EMAIL ............................................................................................................. 17 4.7 HASH VALUES .................................................................................................... 17

5 CONTACT ..................................................................................................... 17



1 Overview

Custom Text Export (CTE) is a customisable text export connector for Kofax Capture.

CTE has all the functionality of the standard Kofax Text Export Connector, as well as the

following additional features:

- Custom layout and format for index file per document

- Custom layout and format for index file per batch

- Custom naming and versioning for index files

- Header and/or footer per batch in output file

- Multi-line export for multi-value fields

- Run database INSERT, UPDATE, DELETE statements

- Send custom emails per document or per batch

The custom filenames can be defined using a combination of index field values, batch field

values, system values and text, allowing complete flexibility over the configuration.

Output index files are formatted according to templates which gives you complete control over

the layout and content.

This guide is intended to show how to install and configure CTE for Kofax Capture.

CTE is supported for Kofax Capture versions 10, 11

1.1 Fixed Issues

Default values 3.0.1 SQL Statement Settings and Email Settings failed to set a

default option on loading the setup

Template Files 3.0.2 fixes an issue where an extra line is added to a template file

when saved in Template Designer

1.2 New Features in v3.0

Version 3.0 includes all features and bug fixes from all earlier versions, as well as:

Base64 PDF allows you to export a Base64 version of the Kofax PDF. See

3.2.1

SQL Query allows you to define and execute custom database UPDATE,

INSERT, DELETE statements. See 3.4.5

Email allows you to define and send customised emails including PDF

attachment. See 3.4.6

Add Indexes to Output 3.0.2 allows you to add index fields, batch fields, and system

variables to the output data from within Template Designer. See

3.5

Base64 Image 3.0.2 allows you to export a Base64 version of the exported

image. See 3.2.1

File Hash Values 3.0.2 allows you to get a hash value (MD5/SHA) for the document

PDF or exported image. See 3.2.1



2 Installation

NB. As with any custom component, it is strongly advised to take a full back up of

your system configuration before installing new components.

Unzip CustomTextExport.zip and copy CustomTextExport.inf and CustomTextExport.dll

to the Kofax Capture installation Bin folder on any workstation which will run the release

process.

If you are using Kofax Capture v10.1, use the files from the .Net4 folder.

If you are using Kofax Capture v10.2 and above, use the files from the .Net4_1 folder.

In Kofax capture Administration, use Tools > Export Connector Manager to add the

connector.

CTE is now installed and ready to configure for document classes.

NB. It may be necessary to register the CustomTextExport.dll manually using REGASM. See

section 4.1 for details.

NB. Some operating system security settings may block CustomTextExport.dll. If you

experience problems installing or registering Custom Text Export, check whether the .dll file

has been blocked. If it has, unblock it and then retry.

3 Configuration

3.1 Default Storage

Select or define the folder to be used as the default storage area for images and index file

export.

Define custom file naming for the output Image, PDF, and OCR files if required.

Select whether to Error, Rename (version), or Replace files with duplicate names.



3.2 Index Storage

Configure settings for custom text file output in the Index Storage Tab.



3.2.1 Template Files

Custom Text Export works by using template files. A template file is a file in the format you

want to produce during the export process. In the file, you put markers which will be replaced

with actual values at export time.

Note: The output file at export time will have the format specified in the Body Template. So to

export as XML for example, the Body Template should be a .XML file.

The markers which can be used are:

{@IndexFieldName} for any index field

{$BatchFieldName} for any batch field

{##SystemVariableName} for any Kofax system variable

{@@TAB} inserts a TAB

{@@CRLF} inserts a new line

{@@DocumentNumber} the document position in batch

{@@ImagePath} the full exported image path

{@@ImageFile} the exported image filename

{@@PDFPath} the full exported PDF path

{@@PDFFile} the exported PDF filename

{@@OCRPath the full exported OCR path

{@@OCRFile} the exported OCR filename

{@@BatchClassName} the batch class name

{@@BatchName} the batch name

{@@BatchDescription} the batch description

{@@DocClassName} the document class name

{@@UniqueDocumentID} the unique document ID

{@@Date0} a dynamically formatted date – see 3.4.3

{@@DocPageCount} the page count for the document

{@@Base64PDF} Base64 text rendition of the document PDF

{@@Base64Image} Base64 text rendition of the exported image*

{@@HashPDF_MD5} MD5 hash of the document PDF

{@@HashPDF_SHA-1} SHA-1 hash of the document PDF




{@@HashImage_MD5} MD5 hash of the exported image*

{@@HashImage_SHA-1} SHA-1 hash of the exported image*




To use any marker as plain text in the output file use markers as shown below. These will be

converted to plain text at export time.

{_@IndexFieldName_} {_$BatchFieldName_} {_@@Date0_} {_##SystemVariableName}

An example of a template file is shown below:

{@@DocumentNumber} Name=OrderReference Value={@OrderReference} {@@PDFPath}



The template above could produce an output file as below:

0

Name=OrderReference Value=673421895 C:\Data\Kofax\Capture\Export\Files\PDF\673421895_Bill Slater.pdf

* If you are using a single image format export, you must use Single Page Export in order to get the Base64 or Hash value of the exported image file. Also see sections 4.4 and 4.7.

3.2.2 Custom Template Export – File Per Document

Check the box to write one index file per document, to the default storage area defined in

Default Storage.

To use the custom text template output settings, select a template file. You can use the ?

button to go to the Tempate Designer to edit the selected template – see section 3.5.

If required, enter a custom output filename definition. This can be defined using the markers

listed in 3.2.1 See also 4.3.

If no filename is entered, the name defined in Default Storage will be used.

Select whether to Error, Rename, Replace, or Append when a duplicate name is encountered.

NB. This Error, Rename, Replace, Append refers to the output index file and not the Image,

PDF, OCR files – set options for those in Default Storage Tab.

NB. If no Template File or Filename is entered, the index release will be as per the standard

Kofax Text Export

3.2.3 Custom Template Export – Specific File

Check the box to write to a specific index file.

Select or define a Storage Folder to write the index file to.

Specify a filename. This can be defined using the markers listed in 3.2.1. See also 4.3.



Select whether to Error, Rename, Replace, or Append when a duplicate name is encountered.

NB. This Error, Rename, Replace, Append refers to the output index file and not the Image,

PDF, OCR files – set options for those in Default Storage Tab.

NB. If no Body File Template is selected, the output text file will be as per the standard

Kofax Text Export.

Specify a Header File Template if required. This will be used to generate a header at the

beginning of each batch. This is optional.

Specify a Body File Template. This will be used to generate an entry in the index file for each

document. This file is mandatory to use custom text export.

Specify a Footer File Template if required. This will be used to generate a footer at the end of

each batch. This is optional.

You can use the ? button to go to the Tempate Designer to edit the selected template – see

section 3.5.

When writing to a specific file, Custom Text Export will always append to the file. In order to

generate a file per batch, specify a filename or custom path that will be unique for each batch,

or select Rename to create a version – ie FileName_V1.txt

If you use a path or filename that creates a new file for each batch, then the following

template files:

Header

{@@BatchName}

{$BatchCreationDate}

Body

{@@DocumentNumber}

Name=OrderReference Value={@OrderReference} Name=CustomerName Value={@CustomerName} {@@PDFPath}

Footer

Could produce the following output index file:



CustomTextExport 76 23/04/2013

1 Name=OrderReference Value=673421895 Name=CustomerName Value=Bill Slater C:\Data\Kofax\Capture\Export\Files\PDF\673421895_Bill Slater.pdf

2 Name=OrderReference Value=478231793 Name=CustomerName Value=Janet Harvey

C:\Data\Kofax\Capture\Export\Files\PDF\478231793_Janet Harvey.pdf

3.3 Advanced

For each output type – Image, PDF, OCR – select whether this type should be exported.

Select where each type will be exported. Choose from the Default Storage (defined in Default

Storage Tab) or select/define a custom path.

Select suppress image output if PDF is detected, if you do not want to export the image files

when PDF’s have been exported.

Select Skip first page of each document if you want to remove a header sheet etc.

Select the export image format.



3.4 Custom Settings

3.4.1 General Settings

3.4.1.1 Enable XML Entity Translations

Select this option in order to translate specific XML entities. The following characters are

special characters in XML, and need to be translated in order to produce valid XML:

Character Translates To

> >

< <

‘ '

“ "

& &



When this option is selected, any instances of these characters in the output file will be

converted as above.

3.4.1.2 Single Page Export

Select this option if you want to run the export for each page of a multipage document. This

feature will only work if a single page image format is selected for the image output.

3.4.1.3 Convert Illegal Filename

When this option is selected, any illegal characters in a filename or path will be replaced with

‘_’ (underscore character).

3.4.1.4 Encoding

Select the Encoding for writing output index files. It is also possible to specify a particular

CodePage. Leave as Default to use the system default CodePage.

NB. Specific CodePage settings are only applied if you are using template files for text export.

If not the text file produced will be as per the standard Kofax Export.

3.4.1.5 Table Export

If you want to produce a multi-line output based on a TABLE, select Table Export and enter the

name of the TABLE field to use.

During export, the template file will be written once for each row in the table, with the relevant

row value being used each time.

For example, where there is a table defined at the Document Class level with fields

Description, Value, and Units, and also a standard field CustomerName, and the data at

validation is:

Description Value Units

Overcoat 14.99 3

Hat 3.99 4

Then the following basic template body file:

CustomerName: {@CustomerName} Description: {@Description}

Value: {@Value} Units: {@Units}

Could produce an output such as:



CustomerName: John Smith Description: Overcoat Value: 14.99 Units: 3 CustomerName: John Smith Description: Hat

Value: 3.99 Units: 4

NB. TABLE export settings are only applied if you are using template files for text export. If

not the text file produced will be as per the standard Kofax Export.

3.4.2 Conditional Export Settings

Enter a conditional test to determine if this export will run for each document. In the example

above an Index Field called ‘ExportThisDocument’ is checked at export time. The export will

only run if the value in the field is ‘YES’

It is possible to choose from a number of conditional tests to be evaluated at runtime. You can

select the ? to test the results which will be produced at export time to ensure that you select

the correct test.

If you select any of the following tests: =, , >, =,



3.4.3 Date Format Settings

It is possible to specify a list of possible date formats to be used at export time. This gives the

ability to set date and/time values during the actual export process rather than take values

from an index or batch field which may not represent the actual export date/time.

In the example below three formats are specified with a delimiter of &&

dd-MM-yy {@@Date0}

dd-MMM-yy {@@Date1}

ddMMyy {@@Date2}

To use any of these date formats during export, use the flags {@@Date0}, {@@Date1},

{@@Date2} etc in any template file.

Up to 10 date formats are allowed. {@@Date0} – {@@Date9}

3.4.4 XSLT Transformation Settings

If the output generated by your export configuration is XML, you can define a stylesheet

transformation to be carried out on the generated XML.

Specify the stylesheet to use in the XSLT box.

Specify a new location to write the transformed XML to. If this box is left blank, the original

XML is simply replaced with the transformed file.

Select whether to delete the original XML if the transformed XML is written to a new location.

3.4.5 SQL Statement Settings

A SQL statement can be executed per document or per batch, and the database connection

and statement are held in template files and interpreted at runtime so that Index or Batch field

values and other custom variables can be used.

These templates can be viewed and edited in the Template Designer by clicking the ? button to

open the currently referenced template file in the designer.



Template using a Batch field to detemine the DSN connection to be used at runtime.

Template using Index fields to define an INSERT statement.

See section 4.5 for details of supported statements.

3.4.6 Email Settings

It is possible to send emails per document or per batch. The subject and body of the emails

are defined in template files which are translated at runtime to give total control over the

layout and content of the emails.

It is also possible to attach a copy of the Kofax PDF for a document, and rename it using any

of the available flags listed in section 3.2.1.

Template for email body content using Index field values.

Click Server Setup to define outgoing mail server settings. Settings can also reference any of

the flags in section 3.2.1 which will be translated at runtime. In the example below the email

will be sent to an address in an Index field called ‘MailRecipient’.



Click Send Test Email to check your outgoing server settings are correct. Note that you will

need to enter credentials in full to send a test email in the setup stage, but can reference

Index fields etc to be used at runtime.

See section 4.6 for more details on email capability.

3.5 Template Designer

The Template Designer allows you to import or create template files within the export setup.

Using this feature you can load a sample of what the desired output file should look like and

insert markers for export data values.

Once you have the desired format, you can save the template file ready to be used at export

time.

You can use the Template Designer by clicking the ? button from within Index Storage tab, or

use it independently to create/edit template files.

In the example below, a sample of the required XML output is loaded. The values are replaced

with data markers to create a generic template. This template can then be saved and used at

export time.

You can type any required data into the template designer, or highlight the area where data is

required, and select Index Field, Batch Field, Kofax Variable, or Other Value from the drop

down lists.

Click Add to insert the marker into the template.

Click Literal to insert a text literal of the marker into the template.

Click + to add the Index Field, Batch Field or Kofax Variable to the output values (Index

Storage TAB).

Sample of desired output loaded. Edited to create generic template.

Note: Template files are saved in the file system and are not stored in the Custom Text Export

settings, so they may also be edited manually outside of the export configuration.



4 General Considerations

4.1 Registering Components

It may be necessary to manually register the CustomTextExport.dll file.

To do this, open a command window using Start > Command

Run the following command:

\Microsoft.NET\Framework\\regasm.exe

“\Bin\CustomTextExport.dll”

Where is the root install path for Windows – usually C:\Windows

Where is the Kofax installation path – for example C:\Program

Files\Kofax\Capture

Example:

C:\Windows\Microsoft.NET\Framework\v2.0.50727\regasm.exe “C:\Program

Files\Kofax\Capture\Bin\CustomTextExport.dll”

.Net4 version:

C:\Windows\Microsoft.NET\Framework\v4.0.30319\regasm.exe “C:\Program

Files\Kofax\Capture\Bin\CustomTextExport.dll”

4.2 Custom Path and Filename Values

When defining custom path and filename values, it is not possible at configuration time to

ensure that the values passed at export time will be valid path and/or filename values.

Where invalid path or filenames are generated, batches will be routed to Quality Control.

It is advised that full testing of the Custom Text Export be carried out to ensure that values

used in custom paths or filenames will not cause export errors.

4.3 Custom Filename Definition

For custom filename definition it is possible to use text, index field values, batch field values,

system values, or a combination of all.

For example a custom filename definition:

Ref_{@CustomerName}_Order_{@OrderReference}_{@@BatchName}

Could produce a file such as:

Ref_Joe Bloggs_Order_12345_AccountsBatch21.xml

4.4 Single Page Formats and E-Documents

Where a document contains non-image files, or uses a single page export format (single page

Tiff, or JPEG for example), Kofax creates a folder per document, and this folder contains the

pages for the document.



For example:

…\ExportPath\00000001\1.tif



If you define a custom filename in this case, the custom filename (and versioning if selected)

will be applied to the document level folder, as below:

…\ExportPath\Joe Bloggs\1.tif



If you are using a Single Page format for Image output, then the markers {@@ImagePath}

and {@@ImageFile} will contain the name of the directory containing the images. If you

select Single Page Export, then the markers will contain the image names of the single pages

within the directory.

4.5 SQL Statements

Custom Text Export uses .Net System.Data.OdbcCommand.ExecuteNonQuery method to

run sql statements. These are typically INSERT, UPDATE, and DELETE statements.

More information is available here: https://docs.microsoft.com/en-

us/dotnet/api/system.data.odbc.odbccommand.executenonquery

4.6 Email

Custom Text Export uses .Net System.Net.Mail.SmtpClient.Send method and

SmtpDeliveryMethod.Network to send emails.


us/dotnet/api/system.net.mail.smtpclient

4.7 Hash Values

Custom Text Export uses .Net System.Security.Cryptography and the following:

MD5CryptoServiceProvider

SHA1CryptoServiceProvider





us/dotnet/api/system.security.cryptography

5 Contact

For support and assistance please contact [email protected]
https://docs.microsoft.com/en-us/dotnet/api/system.data.odbc.odbccommand.executenonqueryhttps://docs.microsoft.com/en-us/dotnet/api/system.data.odbc.odbccommand.executenonqueryhttps://docs.microsoft.com/en-us/dotnet/api/system.net.mail.smtpclienthttps://docs.microsoft.com/en-us/dotnet/api/system.net.mail.smtpclienthttps://docs.microsoft.com/en-us/dotnet/api/system.security.cryptographyhttps://docs.microsoft.com/en-us/dotnet/api/system.security.cryptographymailto:[email protected]

Kofax Consultant - Custom Text Export Setup Guide Text Export Setup... · 2020. 10. 5. · to the...

Documents

Transcript of Kofax Consultant - Custom Text Export Setup Guide Text Export Setup... · 2020. 10. 5. · to the...