Job Settings

The Job Settings tab displays the settings for the selected job.

At the top there are sub-tabs that allow you to view and edit the settings for the job.

The sub-tabs and their options are covered in detail below.

At the bottom of the Job Settings tab there is a toolbar with the following options.

Job Definition

Job Definition contains the common job properties that need to be set for the job to be executed.

The options displayed depends upon the Operation selected.

The following are common to all operations:

Rename PDF File

Rename based on Text Match

The “Copy To Output and Rename” requires an additional filename template which can use a number of variables.

Click on the question mark for details of the available variables.

Rename based on Barcode

Rename based on Text Match and Barcode

Split PDF Files

Split File based on Barcode

Split File based on Text Match

Split File based on Text Change

Split File based on Page Ranges

Split by Page Ranges has the one additional field.

Split by Repeating Page Ranges has two additional fields.

Extract Pages from PDF Files

Extract Pages from file based on Barcode

Extract Pages from file based on Text Match

Export PDF Content

PDF to Text

PDF to CSV/XLSX

Advanced Export to CSV/XLSX

Location Settings

Kingfisher allows users to process files in SharePoint Online (Office 365), SharePoint On-Premises and on the Windows file system. This section will show you the details of the “Location Settings” tab.

Location Types

Kingfisher gives you an option of 3 different location types, this section explains the different ways there are added or edited in a job.

File System

This is straight forward, choose between processing a “Single File”, “Folder” or “Tree”. After chose the file system type, you can use the browse button to select the location.

The Browse button allows you to browse to the location of the file or folder.

Local, Mapped and UNC paths

Local paths are those that are on drives local to the machine running Kingfisher. These are (subject to suitable permissions for the Kingfisher service user) usable as paths for locations for use by Kingfisher.

Mapped drives (where a device has a network path mapped to a drive letter) must not be used in paths in Kingfisher. This is due to how drive mapping is applied to service users. If you have a network path, please use the Uniform Naming Convention (UNC) path. If you select a path using the file or folder browser, it will convert it to the UNC path.

SharePoint (On-Premises)

Adding a SharePoint location is a bit different, after select the “SharePoint” option, you will see the button below.

Click on the “Add SharePoint Location” button to open the SharePoint location dialog box shown below.

The SharePoint locations can be accessed using either Username and Password, or by Active Directory Federation Services (ADFS).

After you enter your SharePoint details, click the “Save Location” button and the locations will be validated as shown below.

After saving the location, you can always edit by clicking the “Edit SharePoint Location” shown below.

The key thing to be aware of is that Kingfisher will traverse everything under the URL, so if the output location is in the same location, the files will be picked up on subsequent runs.

To specify what folders will and will not be processed, use the Input Filters:

• Filter Locations by Regular Expression

• Excluded Locations

Additionally if the output location is supposed to be a sub folder, ensure that the URl has EXACTLY the same format (Shared%20Documents and Shared Documents are treated as different locations and generates a nested folder structure.

Office365 (SharePoint OnLine)

Adding a new Office 365 location is similar to adding a new SharePoint location.

There are two options for authentication:

• Username and Password

• Modern Authentication/OAuth2

Username and Password

The key thing to be aware of is that Kingfisher will traverse everything under the URL, so if the output location is in the same location, the files will be picked up on subsequent runs.

To specify what folders will and will not be processed, use the Input Filters:

• Filter Locations by Regular Expression

• Excluded Locations

Additionally if the output location is supposed to be a sub folder, ensure that the URl has EXACTLY the same format (Shared%20Documents and Shared Documents are treated as different locations and generates a nested folder structure.

Modern Authentication

For details on how to set up modern (OAuth2) authentication for SharePoint (and email) see the OAuth2 Configuration document.

Follow the same process as the previous section if you want to save or edit the location.

Apply Input Filters

Kingfisher give you the ability to filter or exclude source files/paths based on difference criteria.

Filter Locations by Regular Expression

If you provide any values for this, Kingfisher will only process files that match the regular expression provided. To add values, click the “Filter Locations by Regular Expression” link, this will show the dialog below. Then click the “Add new Location” button.

Example:
This example job will process files only in the RegexTest folder:

Open the Filter Locations by Regular Expressions dialogue and add the folder name RegexTest.

Be aware the regular expression only needs to match something in the path.

If the job is in Debug mode, the log will contain a record of those files that match and those that do not. This will help you with tailoring the regular expression to your environment.

Exclude Locations

Any path you provide here will be skipped by Kingfisher, to add values to this property, click the “Exclude Location” link. The Dialog below will be shown.

Click on the “Add Item” button to add a new value, after you are done click the Ok button.

If the job is in Debug mode, the log will contain a list of the exclusion locations and will show locations that are included and those that are excluded.

This will help you with tailoring the regular expression to your environment.

Select Variables

One of the most attractive features of Kingfisher is the ability to select text or barcode at a position in a PDF page, the selected text or barcode can be used to:

• Decide whether to split the document at the page where the text of barcode was found.

• Decide whether to extract the page where the text of barcode was found.

• Use these extracted text or barcode values to rename the file.

Template file

The Select Variables tab uses a template file to allow the interactive definition of the various zones. By default, it picks up either the source file selected in the Location Settings tab or one of the files located in the folder file selected in the Location Settings tab.

It is possible that during the use of Kingfisher, this file will be removed. If the job condition is opened again in the UI, a warning message will be displayed indicating that the template file is missing. It does not affect the operation of Kingfisher.

It is a good idea to define a Template File folder and copy your chosen template file into it. Use the browse file option to select this as the new template file.

Variables

The “Select Variable” tab is used to select four variables named:

• %VALUE1%: This is used to decide the split or extract page, it is also used to generate the output file name, note this must be selected for some jobs to run.

• %VALUE2%: This is used to generate the output file name.

• %VALUE3%: This is used to generate the output file name.

• %VALUE4%: This is used to generate the output file name.

Zones

To assign a zone to a variable, you should first choose the zone on the PDF page with your mouse, click the camera icon associated to the variable you want to assign the zone to. If you do not assign a zone to the variable, Kingfisher will assume you want to use the whole page as a zone. You will notice the “Selected Zone” Text Box change from “all” to the coordinates you selected.

Text Match Option

When extracting text, Kingfisher gives you the ability to select text that is relative to a word/pattern. The table below shows the options available and what they mean.

Barcode

When extracting Barcode, you can select specific barcode formats or select All of the supported barcodes (default).

Text Pattern Option

Kingfisher allows the user to define the text pattern of the text to be extracted from the PDF document. This helps the user make sure only text that match a certain pattern will be extracted. For example, a user might want a phone number, but a postcode gets extracted just because it was present in the same location as the postcode on a different page. Kingfisher provide pattern matching so that a user can make sure the text that is extracted is properly validated before it is accepted.

Patterns are used to match parts of the document. Some useful examples are below. For a complete reference on patterns including advanced examples see the link below.

https://docs.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference

Refine Extracted Text

Kingfisher has an advanced method to refine the extracted text.

This allows the removing/replacing of certain pieces of text based on patterns or values.

Scheduler

This tab allows the user to schedule when jobs are executed.

Please note that Kingfisher’s default behavior is that a Scheduled job that generates an error will not run again until either the error is cleared (right click on the job entry on the Dashboard and select clear error), or the job is successfully run manually.

This behavior can be changed by changing two entries in the Kingfisher.Config file.

For jobs scheduled to run once per day, change the value of the setting ScheduleOncePerDayContinueAfterError to true.

For jobs scheduled to run continuously, change the value of the setting ScheduleContinuousContinueAfterError to true.

Alerts

Use this tab to set email alerts for jobs. Email settings (SMTP or OAuth2) are set in the Options/Email tabs (see the email options section).

File Naming

Kingfisher offers various variables to customize the final output name. These variables include:

• Text/Barcode values extracted from the PDF document (including by OCR)

• Index value for split or extract operations (with zero padded options).

• Page numbers (original, first original page of block, last original page of block)

• Bookmarks (for split by bookmark)

• Time and Date values (including the date and time that a job started)

Note that the index value is very useful where the values extracted on different pages during the split/extract are the same.

Name Template

You can enter a string in the name template text box, any occurrence of variables in the table below will be replaced by the appropriate value at runtime.

For non-Tree file sources, there is an option to include folders in the file naming by using a double backslash (escaping a single backslash).

%DATE%\\%VALUE1%

Be aware it is possible to use this file name template with Tree file sources, but the folder structure will include the source folder structure before the file naming one.

File naming example

Two areas are selected:

%VALUE1% has text refinement added:

The File Naming tab has the value %VALUE2\\%VALUE1. The double backslash (\\) is an escaped backslash that indicates the file should be written to a folder with the value of %VALUE2%.

The output file from the example above is created in a sub-folder called “Patent Application Publication”.

Advanced Settings

Security

Source Document Security

Target Document Security

Target Document Permissions

Properties

The default display properties of a PDF can be set here.

Display Modes

Settings

Bookmark Settings

PDF Metadata

OCR Settings

Barcode Settings

Other Settings

Custom Script File

Trigger File

Output PDF

Text Match Settings

Running Job

The Task Log displays the progress of the current or most recent run of the selected job.

The toolbar at the bottom has an additional Explore Destination button

This opens the destination folder if it exists.