POP3

Configure the properties of POP3 (Post Office Protocol) import source and click Save.

The properties of POP3 import source are grouped under the following headings:

General

Field Description
Type Protocol for the import source. Select POP3.
Display name Name for the import source.
Active By default, the import source is active.
Poll cycle in seconds The time interval after which the import connector checks for new documents on the mail server. (Minimum/default value = 5 seconds, Maximum value = 86400 seconds)
Host Name or IP address of the mail server, such as pop.gmail.com. For Microsoft Exchange Online mailboxes (Office 365), enter outlook.office365.com.
SSL Configures Secure Sockets Layer to provide communication security over the internet. Available options are:
  • Always (Default): SSL is always used for email communications.

  • Never: SSL is not used for email communications.

  • Negotiate: SSL is used for email communications if requested.

Port Port number for the mail server. (Default: POP3 - 110, secure POP3 (SSL-POP) - 995)
Credential storage

Select one of the following for authentication with the POP3 host:

  • Local (Default): For OAuth authorization, enter the mailbox name in the User name field. The Password field is disabled for OAuth authorization.

  • External: Enter the secret name for the user name and password stored in the configured external storage in the User name secret and Password secret fields respectively.

Use OAuth server Select this to use OAuth authorization.

  • When you select "Use OAuth server", the "Password" field is not displayed.

  • Make sure that the selected OAuth server uses the "Secret in post body" type of authentication method. See Secret in post body.

OAuth server Select the OAuth server for authorization the list. For information about OAuth servers, see OAuth servers.
Test mailbox Verifies the connection between the import connector and mailbox.
Error Handling
Message Connector service timeout The timeout value for message processing. This value sets the timeout when calling the Message Connector service. (Default: 1200 seconds (20 minutes). This value is suitable for processing most messages.)

To avoid timeout for messages with longer processing time, increase the timeout value. The maximum allowed value is 86400 seconds (24 hours.)

Advanced

Field Description
Normalize images and create pages Normalizes the incoming image files to TIFF and creates pages. (Default: Clear)

  • We recommend using this option in the Document Conversion activity instead of using it in Import Connector.

  • The Document conversion activity runs on the Transformation Server (scalable and optimized for heavy loads) that can manage the tasks of converting documents, splitting images, and creating pages efficiently. You can also address issues such as scaling and orientation in the Document conversion activity and then use any Capture activities in your process map.

Create document from body Creates a document from the email body, classifies, and extracts information from it. (Default: Clear)
Import content Imports the required sections of the email and their occurrence. Select one of the following options:
  • Attachments

  • Attachments first and body

  • Body first and attachments (Default)

  • None

  • Only body

Body with message header Import the body with metadata in its header instead of the plain body. Available options are:

  • Exclude message header (Default)

  • Include message header of email

  • Include message header of email and embedded email(s): Additionally, select the Body option for the Handle body of nested emails as a field in the Document conversion tab of Message Connector Configuration.

For more information about different use cases using this option with File extraction, see Document conversion file extraction use cases.

Include complete message as EML file Imports an EML file the same as the original email including attachments. (Default: Clear)
Include complete message as MSG file Imports an MSG file the same as the original email including attachments.
Skip importing files

Allows you to set conditions to skip specific files for import. For example, to skip the import of .png files that are less than 10 bytes, do the following:

  1. Click .
  2. In the File extension text box, enter the file extension as .png.
  3. Select an Operator as Less than. (Available options are: Less than and Greater than).
  4. Specify the Size in bytes as 10. Use the increment or decrement buttons to specify the file size.
  5. Click Add.

Only the .png files that are less than 10 bytes are skipped. Files greater than or equal to 10 bytes are imported.

To edit the skip import details: Select the record to edit, click , make the required changes, and then click Ok.

To delete the skip import details: Select the record to delete, click , and then click Yes.

Allow importing files

Allows you to set a specific file extension for import. For example, to import .png files, do the following:

  1. Click .
  2. In the File extension text box, enter the file extension as .png.
  3. Click Add.

To edit the allowed import details: Select the record to edit, click , make the required changes, and then click Ok.

To delete the allowed import details: Select the record to delete, click , and then click Yes.

File extraction Allows you to select the file type allowed for extraction.

The available file types are:

File type If selected If not selected

ZIP (.zip, .rar, .7z, .tar, and .gz)

The files inside the ZIP file are extracted and converted. N/A

Portfolio PDF

The files embedded inside the Portfolio PDF are extracted and converted. Only the main PDF is converted. The files embedded inside the PDF are not extracted.

MS Office Document (.docx, .xls, .xlsm, .xlsx, and .pptx)

The main document is converted, and the files embedded inside the document are extracted and converted. Only the main document is converted. The files embedded inside the document are not extracted.

Email (MSG and EML)

Extracts and converts the EML and MSG files attached to the emails.

The extraction results in a separate TotalAgility document for the email body and each attachment.

  • By default, TotalAgility allows the import of the main email and all types of attached emails in EML/MSG format. This is also applicable to the EML and MSG files which are referenced in the XML files.

  • This option is selected by default when upgrading TotalAgility from a lower version.

  • For an XML import, enabling the Extract referenced MSG/EML files option when "Import content" is set to "Only body" is not a valid scenario.

  • The Body with message header option is enabled only when this file type is selected.

Only the email body is converted.

You can configure only one of these options: Allow importing files or Skip importing files. You cannot configure both.

Document normalization

Field Description
Normalize non-PDF eDocuments to PDF/A

Normalizes non-PDF eDocuments (MS Office documents) to PDF/A. (Default: Clear)

Configure the following.

Field Description
Skip converting files

Allows you to set conditions to skip the conversion of specific files. For example, to skip the conversion of .png files that are less than 10 bytes, do the following:

  1. Click .
  2. In the File extension text box, enter the file extension as .png.
  3. Select an Operator as Less than. (Available options are: Less than and Greater than).
  4. Specify the Size in bytes as 10. Use the increment or decrement buttons to specify the file size.
  5. Click Add.

Only the .png files that are less than 10 bytes are skipped for conversion. Files greater than or equal to 10 bytes are converted.

To edit the skip conversion details: Select the record to edit, click , make the required changes, and then click Ok.

To delete the skip conversion details: Select the record to delete, click , and then click Yes.

Concatenate multiple PDF files Concatenates the PDF files selected at the time of importing. (Default: Clear)
Output PDF format Output format for normalized PDF files:
  • PDF

  • PDF/A-1a

  • PDF/A-1b

  • PDF/A-2a

  • PDF/A-2b (Default)

  • PDF/A-2u

  • PDF/A-3a

  • PDF/A-3b

  • PDF/A-3u

  • If the input PDF file format is not compatible to be converted to the required output format, the actual output format may be downgraded. For example, if the input file version is PDF 1.5 and if the "Output PDF format" field is set to PDF/A-1a, PDF/A-2a or PDF/A-3a, the output PDF document is PDF/A-1b,PDF/A-2u or PDF/A-3u respectively.

  • For a complete list of supported input file formats and respective output PDF formats, refer to the Kofax TotalAgility Administrator's Guide.

Embed original source file

Embeds the source files in the normalized PDF file. This option is only available when the output PDF format is set to PDF/A-3a, PDF/A-3b, or PDF/A-3u.

If the input source file is of XML type, it is not embedded in the normalized PDF file.

Normalize incoming PDF documents to PDF/A

Converts the PDF documents to the ISO-standardized PDF/A format, specialized for the digital preservation of electronic documents. (Default: Clear). Configure the following.

Field Description
Output PDF format

The output format for normalized PDF files:

  • PDF

  • PDF/A-1a

  • PDF/A-1b

  • PDF/A-2a

  • PDF/A-2b (Default)

  • PDF/A-2u

  • PDF/A-3a

  • PDF/A-3b

  • PDF/A-3u

  • If the input PDF file format is not compatible to be converted to the required output format, the actual output format may be downgraded. For example, if the input file version is PDF 1.5 and if the "Output PDF format" field is set to PDF/A-1a, PDF/A-2a or PDF/A-3a, the output PDF document is PDF/A-1b,PDF/A-2u, or PDF/A-3u respectively.

  • For a complete list of supported input file formats and respective output PDF formats, refer to the Kofax TotalAgility Administrator's Guide.

Embed original source file

Embeds the source files in the normalized PDF file. This option is only available when Output PDF format is set to PDF/A-3a, PDF/A-3b or PDF/A-3u.

If the input source file is of XML type, it is not embedded in the normalized PDF file.

Flatten XFA forms to PDF documents using Adobe Experience Manager

Allows conversion of XFA forms to PDF documents. (Default: Clear)

Ensure the following:

  • Install the Adobe Experience Manager output service and ensure that the web service interface is available.
  • Configure the Adobe Experience Manager credentials in the Kofax Message Connector configuration.

If support for Adobe LiveCycle is available, you can also use Adobe LiveCycle for conversion of XFA Forms.
Import exception page for failed preparation

Import the unprocessed document if there is any exception during the normalization process of a document. (Default: Clear).

A document with error information is generated and the original document is appended to this document.

VRS processing

Field Description
Scan/VRS profile

Name of the Scan/VRS profile.

Extract text from PDF

To extract the text from PDF, select one of the following options:

  • All text (Default): Extracts both visible and invisible text.
  • Automatic: Extracts only visible text. If the results are empty, then extracts by including invisible text in the results.
  • Ignore all text layer: Extracts PDF through OCR. The PDF text layer is ignored.
  • Visible text only: Extracts only visible texts.
Word separation characters

The characters required as word separators. Default characters are: "/", ":", "(", ")", "-" and "#".

When processing the PDF text, strings of text containing these characters are treated as separate words. For example, "1234/56" is treated as three separate words, "1234", "/", and "56".

Apply scan/VRS profile to eDocuments Applies the selected Scan/VRS profile to the documents. (Default: Clear)

Save page PDF data

If selected, saves the metadata which could be used later to render or add back the metadata. (Default: Clear)

XML processing

  • Any document (eDocument, image, or PDF) specified in the XML Page tag are imported along with the XML file. When the page tag is not available or empty, the document fields are not classified or does not have the field values mapped.

  • If the process (Batch Name) is specified in the XML file, you need not specify the process in the Import source settings, as the process name will be derived from the Batch Class name in XML.

Field Description
Kofax XML import mode

Select one of the following options:

  • Do not map XML fields to TotalAgility fields: The XML file fields are not mapped to the TotalAgility fields.

  • Map XML fields to TotalAgility fields and allow fields mismatch:

    TotalAgility imports the XML file and maps the TotalAgility fields to XML file fields. If there is any difference in the fields specified in the XML file, TotalAgility will still import the file and display the errors in the Message Connector.

  • Map XML fields to TotalAgility fields and reject on mismatch:

    TotalAgility imports the XML file and maps the TotalAgility fields to XML file fields. If there is any difference in the fields specified in the XML file, TotalAgility rejects the XML file.

Kofax XML page tag processing level Select one of the following options:
  • Document: Imports a Kofax XML containing reference to a multi-page TIFF file.

  • Page (Default): Imports Kofax XML containing reference to a single page TIFF file.

Create document from XML content

Creates a document from the XML content. (Default: Clear).

Additionally, on the Process list, select the process which contains the Document conversion activity with the required XML rendering configuration. By default, you can only map the XML content to the XML process variable.

You must select this option to use the XML rendering feature in the document conversion activity.

Notification settings

Send notification emails to the configured email addresses when the document import process is successful, partially successful, and rejected/failed.

Field Description
To

The email addresses of the recipients to whom you want to send the notification. You can use an inline value, server variable, and metadata.

CC

The email addresses of the recipients to whom you want to send a copy of the notification. You can use an inline value, server variable, and metadata.

Bcc

The email addresses of the recipients to whom you want to send a blind copy (the email address of the recipient is not shown to other recipients in the list) of the notification. You can use an inline value, server variable, and metadata.

From

The email address of the sender. You can use an inline value, server variable, and metadata.

You can add only one value.
Subject

The subject of the email notification. You can use an inline value, server variable, and metadata.

Format The format in which the notification email is sent. Available options are:
  • Text: Supports only plain text. Any images, font colors, or tables are not displayed or not displayed as expected.
  • HTML: Supports images, tables, and font formats.
Body

The message included in the email notification. You can use an inline value, server variable, and metadata.

Send email to originator

Sends a notification to the originator (sender). The sender receives a copy of the email notification if this option is selected. (Default: Clear)

Include complete email message as attachment

Attaches the original message (in EML format) to the notification mail. (Default: Clear)

Remove email attachments

Removes attachments from the original email. (Default: Clear)

If the original email does not contain a body, an empty email is generated.

For more information on providing values to the To, Cc, Bcc, From, Subject, and Body fields, see Field values.

Field values

You can provide an inline value, server variable, or metadata for the To, Cc, Bcc, From, Subject, and Body fields.

To specify an inline value:

Enter the inline value in the text box provided for the To, Cc, Bcc, Subject, and Body fields. For the To, Cc, and Bcc fields, delimit each email address with a semicolon when an inline value is used. For the From field, use the edit button to enter an inline value.

To use a server variable or metadata:

The server variable contains information such as server name, server ID, and server password. For more information, see Server variables. The metadata includes the data from the original message, such as Bcc, CC, and To. To select a server variable or metadata, do the following.

  1. Right-click inside the text box.

    A pop-up window is displayed. By default, the Server variable tab is selected on the left pane.

    For the From field, use the down button to open the pop-up window.

  2. Do the following:
    • To select a server variable, select a category and type to view the list of server variables, and then select a variable.

    • To select metadata, select Metadata on the left pane to view the list of metadata, and then select metadata.

    You can use the Filter search box to search for a server variable or metadata.

The Test connection validation fails if metadata is used in the To field. However, this does not affect sending the email notification, the metadata is resolved while sending the email.

Document archiving

Configure one or more file formats for saving the successfully imported, partially imported, rejected, or failed documents.

Field Description
Successfully imported

Archive folder

Path of a local folder (such as C:\Archive) or a network folder to store the successfully imported documents.

Format

Supported formats for successfully imported documents are:

  • File: Archives the message body in a text file and all attachments in separate files.

  • EML: Archives the message body and the attachments as a single EML file.

  • XML: Archive the message metadata in an XML file (custom Kofax format).

Test archive folder Tests whether the archive folder is configured correctly.
Subfolder and file prefix

The name of the subfolder and prefix for the archived files. You can also add predefined Fields (metadata) as subfolder names and filename prefixes. The value of these metadata is populated at the time of saving the archived files. If you do not add the "\" character in the field, all the fields are appended to the archived file names. For example, if you add {OK}\{Process-ID}, the files are stored in the OK folder with the process ID appended to the filename.

The following fields are available:

Message field Description
OK Name of the subfolder created inside the Archive folder for import.
Hostname Host name of the system where KTA web application is running.
Process-ID The process ID of the MC instance.
Import-Date-Short(YYYY-MM-DD) The date in short format when the mail was imported. For example: 2023-09-20
Import-Date-Long(YYYY-MM-DDThh-mm-ss) The date in long format including the time when the mail was imported. For example: 2023-09-20 03-45-50
Processmapname The name of Processmap configured in Associated actions.
Processinstance-ID The ID of Processmap configured in Associated actions.
Timestamp(YYYYMMDDhhmmss) The date and time when the mail was imported.
Message-ID A unique ID provided for a message by Message Connector once the message is imported.
MCHostname Host name of the system where Message Connector application is running.

Partially imported
Archive folder

Path of a local folder (such as C:\Archive) or a network folder to store the partially imported documents.

Format

Supported formats for partially imported documents are:
  • File: Archives the message body in a text file and all attachments in separate files.

  • EML: Archives the message body and the attachments as a single EML file.

  • XML: Archives the message metadata in an XML file (custom Kofax format).

Test archive folder Tests whether the archive folder is configured correctly.
Subfolder and file prefix

The name of the subfolder and prefix for the archived files. You can also add predefined Fields (metadata) as subfolder names and filename prefixes. The value of these metadata is populated at the time of saving the archived files. If you do not add the "\" character in the field, all the fields are appended to the archived file names. For example, if you add {PARTIAL}\{Process-ID}, the files are stored in the PARTIAL folder with process ID appended to the filename.

The following fields are available:

Message field Description
OK Name of the subfolder created inside the Archive folder for import.
Hostname Host name of the system where KTA web application is running.
Process-ID The process ID of the MC instance.
Import-Date-Short(YYYY-MM-DD) The date in short format when the mail was imported. For example: 2023-09-20
Import-Date-Long(YYYY-MM-DDThh-mm-ss) The date in long format including the time when the mail was imported. For example: 2023-09-20 03-45-50
Processmapname The name of Processmap configured in Associated actions.
Processinstance-ID The ID of Processmap configured in Associated actions.
Timestamp(YYYYMMDDhhmmss) The date and time when the mail was imported.
Message-ID A unique ID provided for a message by Message Connector once the message is imported.
MCHostname Host name of the system where Message Connector application is running.

Rejected/Failed

Archive folder

Path of a local folder (such as C:\Archive) or a network folder to store the failed/rejected documents.

Format Supported formats for rejected or failed documents are:
  • File: Archives the message body in a text file and all attachments in separate files.

  • EML: Archives the message body and the attachments as a single EML file.

  • XML: Archive the message metadata in an XML file (custom Kofax format).

Test archive folder Tests whether the archive folder is configured correctly.
Subfolder and file prefix

The name of the subfolder and prefix for the archived files. You can also add predefined Fields (metadata) as subfolder names and filename prefixes. The value of these metadata is populated at the time of saving the archived files. If you do not add the "\" character in the field, all the fields are appended to the archived file names. For example, if you add {REJECTED}\{Process-ID}, the files are stored in the REJECTED folder with process ID appended to the filename.

The following fields are available:

Message field Description
OK Name of the subfolder created inside the Archive folder for import.
Hostname Host name of the system where KTA web application is running.
Process-ID The process ID of the MC instance.
Import-Date-Short(YYYY-MM-DD) The date in short format when the mail was imported. For example: 2023-09-20
Import-Date-Long(YYYY-MM-DDThh-mm-ss) The date in long format including the time when the mail was imported. For example: 2023-09-20 03-45-50
Processmapname The name of Processmap configured in Associated actions.
Processinstance-ID The ID of Processmap configured in Associated actions.
Timestamp(YYYYMMDDhhmmss) The date and time when the mail was imported.
Message-ID A unique ID provided for a message by Message Connector once the message is imported.
MCHostname Host name of the system where Message Connector application is running.

Scenarios when a message may be partially imported

  • "Normalize non-PDF e-documents to PDF/A" is enabled and the incoming message contains a file that cannot be normalized, such as a DAT file.

  • A fax is partially received (fax with a reception error.)

  • Documents for which the PDF/A normalization failed.

  • "Normalize non-PDF e-documents to PDF/A" and "Normalize incoming PDF documents to PDF/A" are enabled, and an email with an attached password-protected file is ingested through Message Connector.

  • “Unpack archives” is selected in the Message Connector configuration, and an email with an attached password-protected file is ingested through Message Connector.

  • The message attachment has document conversion errors.

    A document with conversion errors is imported as original file and is available in the workflow. Conversion of any non-supported document (.dat,.xyz,.psz) fails with document conversion error.

Scenarios when a message import may fail

  • "Normalize non-PDF e-documents to PDF/A" and “Concatenate multiple PDF files” are enabled, and the incoming message contains a BIN/DAT file as an attachment.

  • "Normalize non-PDF e-documents to PDF/A", "Normalize incoming PDF documents to PDF/A", and “Concatenate multiple PDF files” are enabled, and an email with an attached password-protected file is ingested through Message Connector.

  • When the XML fields are mapped to the TotalAgility fields, “Map XML fields to TotalAgility fields and reject on mismatch” is enabled and there is some difference in the fields specified in the XML file.

  • "Normalize non-PDF e-documents to PDF/A", "Normalize incoming PDF documents to PDF/A", and “Concatenate multiple PDF files” are enabled, and an email with an attached password-protected file is ingested through Message Connector.

  • “Unpack archives” is selected in Message Connector configuration, "Normalize non-PDF e-documents to PDF/A", and “Concatenate multiple PDF files” are enabled in TotalAgility Designer, and an email with an attached password-protected file is ingested through Message Connector.

  • Any of the message attachment content is null.

  • The process map is not available for an import source.

Associated actions

On the Job type list, select one of the following job types to associate an action with the import source so that a job can be created at runtime for the successfully imported, partially imported, or rejected/failed documents.

Successfully imported / Partially imported / Rejected/Failed

Create new job (default)

  1. On the Process list, select a process or case.

    If the selected process or case map has any initialization variables, the parameters appear under Initialization variables.

    For rejected/failed or partially imported documents, only the metadata of the documents is passed to the relevant processes. When configuring such process maps, you can then map the metadata. Additionally, in case of rejected/failed documents, the original content of an EML is added as a document to the Job.

  2. To map the parameters to the initialization variables, on the Mapping list of the initialization variable, select a dynamic value or click and enter a static value.

Create new case

  1. On the Case list, select a case map.

    If the selected case map has any initialization variables, the parameters appear under Initialization variables.

  2. Select an Expression type:

    • Regular: Enter an expression to extract the case reference from a subject in the Case ref field.

    • XSL: Enter an XML expression to extract the case reference from the XML data in the Case reference field.

    • None (default): Automatically uses the job ID as the case reference.

  3. Map the parameters to the initialization variables, using a dynamic or static value.

Create job in case

  1. On the Process list, select a process, case, or case fragment.

    If the selected process, case, or case fragment has any initialization variables, the parameters appear under Initialization variables.

  2. Select an Expression type:

    • Regular (default): Enter an expression to extract the case reference from a subject in the Case reference field.

    • XSL: Enter an XML expression to extract the case reference from the XML data in the Case reference field.

  3. Map the parameters to the initialization variables, using a dynamic or static value.

For more information about mapping parameters to variables, see Metadata for all import sources.