AP Essentials Connect

Kofax AP Essentials Connect is a program you can install on a local computer and use to perform a number of tasks, such as uploading documents to Kofax AP Essentials. It is an alternative to uploading documents using the web interface in Kofax AP Essentials. Using Kofax AP Essentials Connect, you can upload documents automatically, lessening the effort of uploading documents one by one.

AP Essentials Connect runs as a service in the background, so it is not necessary to start a program each time you want to upload documents. Instead, you simply move the files you want to upload to the folders you specify during the installation setup.

AP Essentials Connect can be beneficial if you want to:

  • Upload large numbers of documents.
  • Automate the process of uploading documents.
  • Download output data from AP Essentials Connect.
  • Automatically register supplier documents in external systems.

Note that the user interface for Kofax AP Essentials Connect is currently only available in English.

AP Essentials Connect System requirements

Kofax AP Essentials Connect supports the following operating systems:

  • Windows 10
  • Windows 8.1
  • Windows Server 2019 Standard
  • Windows Server 2019 Datacenter
  • Windows Server 2016
  • Windows Server 2012 and Windows Server 2012 R2

Kofax AP Essentials Connect requires the following:

  • Microsoft .NET Framework 4.8.
  • An HTTPS connection which uses port 443.

The integration for Dynamics AX requires WCF Activation components.

Creating a customer account

To use AP Essentials Connect, you must make sure that your account in Kofax AP Essentials is set up properly.

After you have created a new customer account, check the following:

  • In order to send documents to your target system, make sure your target system is specified in the target system service (Services > Target system) for the account.
  • You can also add buyers if your organizations has more than one buyer.

After you create a customer account with appropriate services and buyers, you are ready to install Kofax AP Essentials Connect.

Installation

If you use a proxy connection to connect to the Internet, make sure you specify the Windows proxy settings before you install Kofax AP Essentials Connect.

To install Kofax AP Essentials Connect:

  1. Download and run the setup file from the URL that corresponds to your location. Note that an HTTPS connection on port 443 is required to download the installation. After the installation, the connection is required to receive program updates.
    Welcome
  2. Specify the installation folder and click Next to continue:
    Destination Folder
  3. Click Install to confirm your settings and install Kofax AP Essentials Connect.
    Install
  4. After the installation, click Finish to launch Kofax AP Essentials Connect and run the setup wizard.
    Finish

Troubleshooting the installation

When running the installation, some computers display a message that states, "Installation directory must be on a local drive." If you receive this message, run this command as an administrator in Windows Command Prompt:

msiexec /i "C:\[path]\Kofax AP Essentials Connect.msi" WIXUI_DONTVALIDATEPATH="1"

AP Essentials Connect Setup

Be sure to specify the target-system settings correctly before you begin.

The first time you run Kofax AP Essentials Connect, a setup wizard appears to help you configure the initial settings. If you see the Kofax AP Essentials Connect dialog instead of the wizard, click Configure to display the wizard.

The steps that appear in the wizard can vary, depending on the services that are enabled in Kofax AP Essentials.

1. Click Next to begin.

Welcome

2. Use the information provided in your account-information email to fill in the Login address, Authorization key, User name and Password.

Login information

Login address
Authorization key (API Key) You can obtain the key from your account-information email or from an administrator, who can find the key in the Target system view in Admin Center.
User name

The user name you use to log in to Kofax AP Essentials.

The user must be a partner admin, partner user, customer admin or customer user. Group users are not supported.

Password The password for User name.

3. Configure optional dialogs that can appear, depending on the services that are enabled in Kofax AP Essentials:

4. After you complete the required procedures from step 3 above, click Save to save the settings and exit the wizard.

Configuration complete

If you add new customer accounts or buyers to the system or change the Target system service settings after you configure AP Essentials Connect, you must run the configuration wizard again and specify the new upload locations.

If you want to change the Output image format from TIF to PDF (Target system configuration settings), you must process all of the documents in the system before you change this setting. Failure to do so will result in output errors.

Windows users that run Kofax AP Essentials Connect must have Read, Write and Modify permissions on all of the folders you specify in the setup.

Configure settings for uploading documents

Admin users must have the Process documents privilege to see this dialog and upload documents using Kofax AP Essentials Connect.

If the Image upload service is enabled, you can use Kofax AP Essentials Connect to upload documents to Kofax AP Essentials. Customers can upload their own documents for processing, and partner administrators can upload images on behalf of all of their customers.

Uploading documents

Ideally, you specify the Root folder, and then click   to automatically generate the subfolders. Subfolder are created for each buyer defined in Kofax AP Essentials. If no buyers are defined, the subfolder has the same name as the organization (customer account). These subfolders determine which buyer the documents are connected to when they are uploaded to Kofax AP Essentials. Additional subfolders are created for each document type, if the buyer has more than one document type.

Folder examples

In this example, the Folder containing scanned images is named “Upload."

Upload documents toKofax AP Essentials
  • Upload documents to Kofax AP Essentials – Specifies whether you use Kofax AP Essentials Connect to upload documents to Kofax AP Essentials.
  • – Auto-generates the folder structure inside the Root folder.
  • – Displays a dialog which you can use to add a folder location manually. When you specify the folder location, you can optionally associate a buyer/seller and document type with the folder. Partner administrators can also specify a customer account.
  •   – Displays a dialog which you can use to edit the selected folder location.
  •   – Removes the selected folder from the Upload locations list. Note that the folder is not deleted from the hard drive.
  • – Removes all of the folders from the Upload locations list. Note that the folders are not deleted from the hard drive.
  • Upload locations – Displays a list of locations where Kofax AP Essentials Connect looks for images to upload to Kofax AP Essentials.
  • Processed documents folder – Specifies the folder where you want to move the images after they have been uploaded.
  • Document sorting - Determines how many documents each file can contain. See Help for more information about page separation.
  • Upload documents automatically - When this setting is selected, files located in subfolders of the Folder list are automatically uploaded as soon as they are detected. If this setting is not selected, you must click the Upload documents button in the Kofax AP Essentials Connect interface to manually upload images.
  • Allow upload of XML files with matching image file - Normally, when you upload XML documents, Kofax AP Essentials automatically creates a document image from the XML data, so users can visualize the data during verification. If your solution uses XML documents and a document image file, select this setting, so you can upload both of these files, and Kofax AP Essentials will display the original document image during verification, instead of creating one from the XML data. This is helpful because it offers the superior data capture of XML, while displaying the original document image, which might contain additional information that is not available in the XML. Make sure that the corresponding file pairs have the same file name.

Configure settings for uploading master data

Master data is business information—such as supplier address information or other identifying information—that is used by multiple systems and applications. Kofax AP Essentials can utilize master data from an external system to provide information when processing documents. For example, Kofax AP Essentials can use supplier master data to populate the Supplier list during verification.

If the Master data service is enabled, you can use Kofax AP Essentials Connect to automatically upload master data to Kofax AP Essentials.

Ideally, you set up your financial system to export master data (in the XML format outlined below) to a folder that you specify in the Kofax AP Essentials Connect settings. Kofax AP Essentials Connect then checks the folder every minute for new files to import.

Each time you import supplier data, all existing suppliers are removed, then the new data is imported. This ensures that your supplier master data only includes current suppliers.
Uploading master data

The settings and master data types that appear in this dialog can vary, depending on other settings.

  • Enable upload of master data – Specifies whether you use Kofax AP Essentials Connect to upload master data to Kofax AP Essentials.
    You must be an administrator to upload buyers.
  • Master data upload location – Specifies the location where Kofax AP Essentials Connect looks for master data to upload to Kofax AP Essentials.

    If you are a partner, subfolders are automatically created for each customer account. If a customer account has buyers defined, subfolders are created for each buyer too. Master-data files that are put in the correct corresponding folders are automatically uploaded by Kofax AP Essentials Connect. After Kofax AP Essentials Connect uploads the master data, files that are successfully imported are moved to the Imported folder. Files that cannot be imported are copied to the Error folder.

    Upload locations

    In this example, the Folder containing master data to upload is named “Master data.”

  • Master data type – Specifies the type of master data you want to import. This is also the internal name that you reference, for example, when adding custom fields to a document type. Kofax AP Essentials supports these master data types by default:

    • Suppliers

    • Supplier banks

    • Currencies

    • Cost centers

    • Supplier cost centers

    • Projects

    • Accounts (General-ledger accounts) - Only available when the Workflow service is enabled.

    • Field values

    • Customers, add or update - Only available when using accounts receivable document processes. Incremental upload is always applied to customer master data that is automatically uploaded via Windows services.

    • Customers, delete - Only available when using accounts receivable document processes. This master data type is unique because it deletes the specified items (customers) rather than uploading them.

  • File name – Specifies the name of the XML file that contains the master data that you want to import.
  • Delete local file after upload – If selected, the XML file is deleted after it is imported successfully instead of being moved to the Imported folder.
  • Upload automatically – If selected, Kofax AP Essentials Connect checks for new files to import every minute. If you do not select this setting, you can import XML files manually.
  • Incremental upload – When selected, AP Essentials Connect compares the latest XML file with the previous XML file that was uploaded, and uploads only the new changes. This saves time and decreases network traffic significantly.

    Example

    If you upload an XML file that contains 100 suppliers, and then you upload a new file with two new suppliers (102 in total), AP Essentials Connect compares the files and uploads only the two new suppliers. Conversely, if the second upload contains only 50 suppliers, Kofax AP Essentials deletes the missing suppliers from the master data, keeping only the 50 suppliers that are specified in the new XML file.

    AP Essentials Connect uses incremental upload for files that exceed 30 MB in size, even if you do not select this setting.
    If you process documents using accounts receivable processes, incremental upload is always applied to customer master data that is automatically uploaded.

Master data formats

Kofax AP Essentials can consume several types of master data. Use the file names specified below when creating the master-data files that you save in the Folder containing master data to upload. You can click the file names to see the XML schema that is used to validate the master data.

Type File name (schema)
Suppliers suppliers.xml
Cost centers costcenters.xml
Supplier cost centers suppliercostcenters.xml
Supplier banks supplierbankaccounts.xml
Currencies currencies.xml
Projects projects.xml
Accounts glaccounts.xml
Field values * fieldvalues.xml

* Although field values are not  technically master data, you can upload them using AP Essentials Connect. Field-value data lets you specify valid field values for interpreted fields. If a field does not validate according to the specification in fieldvalues.xml, it receives a validation error in AP Essentials Office.

Sample

The XML data that you submit for one supplier can look like this for example:

</Suppliers>

Folder naming conventions for master data

By default, Kofax AP Essentials Connect does not allow special characters, such as dots and slashes, in folder names that you use for uploading and downloading master data. When Kofax AP Essentials Connect encounters a special character, it is automatically replaced with an underscore when creating folders. However, you can override the default behavior by adjusting the Kofax AP Essentials Connect configuration file, ReadSoft.Connect.Host.exe.config (default location: C:\Program Files (x86)\Kofax\AP Essentials Connect\). This is helpful, for example, if you have an organization that contains special characters in its name, and you require folder names other than the default naming convention.

To override the default behavior, you use XML to specify the incoming name (object name) and the outgoing name (folder name). For example, assume you have a customer account named “example.com”. When Kofax AP Essentials Connect makes folders for example.com, it changes the name to “example_com”. By inserting the following XML in ReadSoft.Connect.Host.exe.config, you can preserve the original name:

<FolderNameSubstitutions>
	<FolderNameSubstitution>
		<ObjectName>example.com</ObjectName>
		<FolderName>example.com</FolderName>
	</FolderNameSubstitution>
</FolderNameSubstitutions>

In the next example, the dot is changed to a dash instead of the default (underscrore).

<FolderNameSubstitutions>
	<FolderNameSubstitution>
		<ObjectName>example.com</ObjectName>
		<FolderName>example-com</FolderName>
	</FolderNameSubstitution>
</FolderNameSubstitutions>

Configure settings for uploading purchase-order data

If the Purchase order service is enabled in AP Essentials Connect, you can use Kofax AP Essentials Connect to upload purchase-order data to Kofax AP Essentials.

For the Dynamics AX 2012 integration, purchase-order data is synchronized automatically, so you do not need AP Essentials Connect to upload purchase-order data.

The availability of this dialog varies, depending on your role and setup.

Uploading purchase-order data
  • Enable upload of purchase-order data – Specifies whether you use Kofax AP Essentials Connect to upload purchase-order data to Kofax AP Essentials.
  • Purchase order upload location – Specifies the location where Kofax AP Essentials Connect looks for purchase-order data to upload to Kofax AP Essentials.

For partner accounts, AP Essentials Connect automatically creates subfolders for each customer account. If a customer account has buyers, AP Essentials Connect creates subfolders for each buyer. After Kofax AP Essentials Connect uploads the XML files, files that are successfully imported are moved to the Imported folder. Files that cannot be imported are copied to the Error folder.

  • Purchase-order file name – Specifies the name of the XML file that contains the purchase-order data that you want to import.
  • Delete local file after upload – If selected, the XML file is deleted after it is imported successfully instead of being moved to the Imported folder.
  • Upload automatically – If selected, Kofax AP Essentials Connect checks for new files to import every minute. If you do not select this setting, you can import XML files manually.
  • Incremental upload – When selected, AP Essentials Connect compares the latest XML file with the previous XML file that was uploaded, and uploads only the new changes. For example, if you upload a PO file that contains 100,000 purchase orders, and then you upload a new file with two additional purchase orders (100,002 in total), AP Essentials Connect compares the files and uploads only the two new purchase orders. This saves time and decreases network traffic significantly.
    AP Essentials Connect uses incremental upload for files that exceed 30 MB in size, even if you do not select this setting.

Configure settings for downloading output data

Admin users must have the Process documents privilege to see this dialog and download output data using Kofax AP Essentials Connect.

If the Output to target system service is enabled in Kofax AP Essentials, and the target system is XML locally, you can use Kofax AP Essentials Connect to download processed document data and images from Kofax AP Essentials to a local server.

The availability of this dialog varies, depending on your role and setup.

Downloading output data
  • Save output from Kofax AP Essentials locally – Specifies whether you use Downloading output data to download processed document data to a local folder.
  • Directory to store XML output in – Specifies the folder where you want the output files to be saved. If you are a partner admin or partner user, subfolders are automatically created for each customer account.
Folder examples

In this example, the Directory for storing XML output is named Download.

Using AP Essentials Connect

After following the procedures above to setup AP Essentials Connect, you are ready to use it in production.

Uploading documents using AP Essentials Connect

You can upload documents to Kofax AP Essentials in these supported file formats using AP Essentials Connect:

  • JPEG, JPG
  • PDF version 1.3 to 1.7
  • PNG
  • TIFF, TIF
  • XML

Admin users must have the Process documents privilege to upload documents using Kofax AP Essentials Connect.

Automatic uploading

If you selected Upload documents automatically when configuring Kofax AP Essentials Connect for uploading documents, no interaction is required. When files are moved to the subfolder(s) of the location you specified in the configuration, they are automatically uploaded.

Kofax AP Essentials Connect runs continuously in the background as a Windows service and periodically checks (every 15 minutes by default) for new files to upload. When new files are found, they are uploaded automatically. Even if you restart the computer, Kofax AP Essentials Connect runs automatically in the background with no need for interaction. If a problem occurs during the upload, the upload operation will timeout after 10 minutes.

Most users use automatic uploading, and set up their scanners to save files directly in the appropriate subfolders that are created during the configuration.

If you have more than one document type, but you place files in the parent folder of the document type folders, the files are uploaded and processed using the Default document type specified in the Extraction service settings.

Manually uploading documents

If you did not select Upload documents automatically when configuring Kofax AP Essentials Connect, you can upload files manually at your convenience:

  1. Start Kofax AP Essentials Connect from the Windows Start menu.
    Kofax AP EssentialsConnect
  2. Move or scan document image files to an appropriate subfolder of the location you specified in the configuration, and click Refresh so you can see the files in the list. You can also click the Event log tab to check for errors.
    If you do not see files in the list, make sure you place the files in a subfolder that corresponds to an organization or buyer in Kofax AP Essentials.
    Kofax AP EssentialsConnect Upload
  3. Click Upload documents. You can click Refresh to see that the images have uploaded or use the Event log to monitor the progress of your uploads.
    Kofax AP EssentialsConnect Event Log

Uploading master data using AP Essentials Connect

Master data can be uploaded manually or automatically via a Windows service that runs in the background.

Each time you import supplier data, all existing suppliers are removed, then the new data is imported. This ensures that your supplier master data only includes current suppliers.

Automatically uploading master data

If you selected Upload automatically when configuring Kofax AP Essentials Connect for master data, no interaction is required to upload master data. When master-data files are moved to the folder of the location you specified in the configuration, they are automatically uploaded.

Kofax AP Essentials Connect runs continuously in the background as a Windows service and checks every 12 hours for new master-data files. When new master-data files are found, they are uploaded automatically. Even if you restart the computer, Kofax AP Essentials Connect runs automatically in the background with no need for interaction. Depending on the amount of master data uploaded, it can take a moment before the data is available for use.

If you process documents using accounts receivable processes, incremental upload is always applied to customer master data that is automatically uploaded.

Manually uploading master data

If you did not select Upload automatically when configuring Kofax AP Essentials Connect for master data, you can upload master-data files manually at your convenience. There are two methods for manually uploading master data:

  • Clicking the Synchronize button synchronizes the master data according to the master data settings you specified in the configuration wizard. This option initializes the action that occurs when master data is uploaded automatically.
  • Clicking the Upload master data button displays a dialog that you can use to upload a single file containing master data. This is useful for one-time uploads, such as currency master data.

When master data is uploaded or synchronized, it is noted in the Audit trail view along with a description of whether or not the operation succeeded.

The customer master data upload can be up to 200 MB. Other master-data files cannot exceed 100 MB in size.
Clicking the Synchronize button
  1. Start Kofax AP Essentials Connect from the Windows Start menu.
  2. Move master-data files to an appropriate folder (or subfolder if you are a partner) of the location you specified in the configuration.
  3. Click Synchronize to upload the master-data files.
    Manual uploading
Clicking the Upload master data button
  1. Start Kofax AP Essentials Connect from the Windows Start menu.
  2. Click Upload master data.
  3. In the dialog that appears, specify the Master data type, and use the browse button to select the file that contains the master data you want to upload.
    Manual uploading

    When uploading customer master data via the Upload master data button, all existing customer master data is deleted before importing the new customer master data.

    The customer master data upload can be up to 200 MB. Other master-data files cannot exceed 100 MB in size.
  4. Click Upload.

    The progress is displayed in the Event log tab, and an additional dialog is displayed after the master data uploads successfully.

Downloading output data using AP Essentials Connect

If you selected Save output from Kofax AP Essentials locally in the AP Essentials Connect configuration, processed document data from Kofax AP Essentials is automatically downloaded to the folder you specified in the configuration. If you are a partner, a subfolder is created for each customer account. Subfolders are also created for each buyer, if any exist, and for each document type.

Downloading begins immediately after you complete the setup. Kofax AP Essentials Connect checks for new data continuously every two minutes and downloads up to 5,000 documents at a time. After AP Essentials Connect downloads the documents, it continues checking every two minutes for more documents. Each downloaded document consists of one XML file (UTF-8) containing the processed data and one multi-TIFF image or PDF of the document. The files are named using a unique ID (GUID).

Admin users must have the Process documents privilege to download output data using Kofax AP Essentials Connect.

Using Kofax AP Essentials Connect with a proxy server

In order to use Kofax AP Essentials Connect with a proxy server, you must adjust the Local Area Network settings for the computer that runs the Kofax AP Essentials Connect service. To configure the Windows settings:

  1. Navigate to the Windows Internet Options.
  2. Click the Connections tab in the dialog that appears, and click LAN Settings.
    LAN Settings
  3. In the dialog that appears, select Automatically detect settings and Use a proxy server for your LAN.
  4. Use the Proxy server settings to specify the details of you proxy server.

Proxy server authentication

If your proxy server requires authentication, you can edit two files to instruct Kofax AP Essentials Connect to use the credentials of the current Windows user for authentication.

  1. Open the following files in a text editor:

    • C:\Program Files (x86)\Kofax\AP Essentials Connect\ReadSoft.Connect.Host.exe.config
    • C:\ProgramData\ReadSoft Software Services AB\ReadSoftOnlineConnect\Bin\App.config

  2. In each file, locate the <system.net> element and add the following line:

    <defaultProxy useDefaultCredentials="true" />

    If there is no <system.net> element, add the following to the <configuration> element.

    <system.net>
       <defaultProxy useDefaultCredentials="true" />
    </system.net>

Troubleshooting

Check these issues if you have problems running Kofax AP Essentials Connect

Generic issues

If you have problems running Kofax AP Essentials Connect:

You can click the links above to test if you have access. Click the links using the same computer that runs Kofax AP Essentials Connect. If you receive a 404 error, you do not have access.

  • Make sure you can download the files that are listed in the page that is displayed when you click one of the links above. To do this, replace "Deployment.manifest" in the URL with one of the file names in the list.
  • Log in to Kofax AP Essentials using the same computer that runs Kofax AP Essentials Connect to make sure you can connect to Kofax AP Essentials.
  • If you use a proxy connection, make sure the settings are applied to the same user/account that runs Kofax AP Essentials Connect. By default, this is a local System account. To test this, access Kofax AP Essentials using a location above, then change the Kofax AP Essentials Connect user to the same Windows user you tested with.