Tungsten AP Essentials Connect
Tungsten 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 AP Essentials. It is an alternative to uploading documents using the web interface in AP Essentials. Using 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.
- Automatically register supplier documents in external systems.
Note that the user interface for Tungsten AP Essentials Connect is currently only available in English.
AP Essentials Connect System requirements
Tungsten AP Essentials Connect supports the following operating systems:
- Windows 11
- Windows 10
- Windows 8.1
- Windows Server 2019 Standard
- Windows Server 2019 Datacenter
- Windows Server 2016
- Windows Server 2012 and Windows Server 2012 R2
Tungsten AP Essentials Connect requires the following:
- Microsoft .NET Framework 4.8.
- An HTTPS connection which uses port 443.
Creating a customer account
To use AP Essentials Connect, you must make sure that your account in 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 () 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 Tungsten 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 Tungsten AP Essentials Connect.
To install Tungsten AP Essentials Connect:
-
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.
- Europe: https://production.readsoftonline.com/install/connect
- Australia: https://au.readsoftonline.com/install/connect
- US: https://us.readsoftonline.com/install/connect
-
Specify the installation folder and click
Next to continue:
-
Click
Install to confirm your settings and install
Tungsten AP Essentials Connect.
-
After the installation, click
Finish to launch
Tungsten AP Essentials Connect
and run the setup wizard.
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:\Program Files (x86)\Tungsten\AP Essentials Connect\Tungsten 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 Tungsten AP Essentials Connect, a setup wizard appears to help you configure the initial settings. If you see the Tungsten 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 AP Essentials.
1. Click
Next to begin.
2. Use the information provided in your account-information email to fill in the
Login address,
Authorization key,
User name and
Password.
| 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 AP Essentials. The user must be a customer admin or customer user. If only one target system is enabled on the partner level, partner admins and partner users are also supported. 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 AP Essentials:
- Configure settings for uploading documents
- Configure settings for uploading master data
- Configure settings for uploading purchase-order data
- Configure settings for downloading output data
4. After you complete the required procedures from step 3 above, click
Save to save the settings and exit the wizard.
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 Tungsten 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
If the Image upload service is enabled, you can use Tungsten AP Essentials Connect to upload documents to AP Essentials. Customers can upload their own documents for processing, and partner administrators can upload images on behalf of all of their customers.
Ideally, you specify the Root folder, and then click
to automatically generate the subfolders. Subfolder are created for each
buyer defined in
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
AP Essentials. Additional subfolders are created
for each document type, if the buyer has more than one document type.
In this example, the Folder containing scanned images is named “Upload."
- Upload documents to AP Essentials – Specifies whether you use Tungsten AP Essentials Connect to upload documents to 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 Tungsten AP Essentials Connect looks for images to upload to 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 Tungsten AP Essentials Connect interface to manually upload images.
- Allow upload of XML files with matching image file - Normally, when you upload XML documents, 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 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. AP Essentials can utilize master data from an external system to provide information when processing documents. For example, AP Essentials can use supplier master data to populate the Supplier list during verification.
If the Master data service is enabled, you can use Tungsten AP Essentials Connect to automatically upload master data to 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 Tungsten AP Essentials Connect settings. Tungsten AP Essentials Connect then checks the folder every minute for new files to import.
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
Tungsten AP Essentials Connect
to upload master data to
AP Essentials.
You must be an administrator to upload buyers.
-
Master data upload location – Specifies the location where Tungsten AP Essentials Connect looks for master data to upload to 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 Tungsten AP Essentials Connect. After Tungsten 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.
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. 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, Tungsten 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, 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
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:
<?xml version="1.0"?>
<Suppliers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Supplier>
<SupplierNumber>00001</SupplierNumber>
<Name>Polychemtex Inc.</Name>
<Description>Supplier of quality goods and services at low prices.</Description>
<TaxRegistrationNumber>GB999999973</TaxRegistrationNumber>
<OrganizationNunmber>5561947986</OrganizationNunmber>
<Street>1 Main Street</Street>
<PostalCode>DH9OTB</PostalCode>
<City>Townsville</City>
<CountryName>UK</CountryName>
<PaymentTerm>30 Days</PaymentTerm>
<PaymentMethod>Direct Deposit</PaymentMethod>
<CurrencyCode>GBP</CurrencyCode>
<Blocked>0</Blocked>
<TelephoneNumber>4960123</TelephoneNumber>
<FaxNumber>4960122</FaxNumber>
<TaxCode>012345</TaxCode>
</Supplier>
</Suppliers>Folder naming conventions for master data
By default, Tungsten 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 Tungsten 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 Tungsten AP Essentials Connect configuration file, ReadSoft.Connect.Host.exe.config (default location: C:\Program Files (x86)\Tungsten\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 Tungsten 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 Tungsten AP Essentials Connect to upload purchase-order data to AP Essentials.
The availability of this dialog varies, depending on your role and setup.
- Enable upload of purchase-order data – Specifies whether you use Tungsten AP Essentials Connect to upload purchase-order data to AP Essentials.
- Purchase order upload location – Specifies the location where Tungsten AP Essentials Connect looks for purchase-order data to upload to 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 Tungsten 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, Tungsten 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
If the Output to target system service is enabled in AP Essentials, and the target system is XML locally, you can use Tungsten AP Essentials Connect to download processed document data and images from AP Essentials to a local server.
The availability of this dialog varies, depending on your role and setup.
- Save output from 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.
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 AP Essentials in these supported file formats using AP Essentials Connect.
Automatic uploading
If you selected Upload documents automatically when configuring Tungsten 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.
Tungsten 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, Tungsten 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 Tungsten AP Essentials Connect, you can upload files manually at your convenience:
-
Start
Tungsten AP Essentials Connect
from the Windows Start menu.
-
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 AP Essentials.
-
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.
Uploading master data using AP Essentials Connect
Master data can be uploaded manually or automatically via a Windows service that runs in the background.
Automatically uploading master data
If you selected Upload automatically when configuring Tungsten 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.
Tungsten 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, Tungsten 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.
Manually uploading master data
If you did not select Upload automatically when configuring Tungsten 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.
Clicking the Synchronize button
- Start Tungsten AP Essentials Connect from the Windows Start menu.
- Move master-data files to an appropriate folder (or subfolder if you are a partner) of the location you specified in the configuration.
-
Click
Synchronize to upload the master-data files.
Clicking the Upload master data button
- Start Tungsten AP Essentials Connect from the Windows Start menu.
- Click Upload master data.
-
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.
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 200 MB in size. -
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 AP Essentials locally in the AP Essentials Connect configuration, processed document data from 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. Tungsten 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).
Using Tungsten AP Essentials Connect with a proxy server
In order to use Tungsten AP Essentials Connect with a proxy server, you must adjust the Local Area Network settings for the computer that runs the Tungsten AP Essentials Connect service. To configure the Windows settings:
- Navigate to the Windows Internet Options.
-
Click the
Connections tab in the dialog that appears, and click
LAN Settings.
- In the dialog that appears, select Automatically detect settings and Use a proxy server for your LAN.
- 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 Tungsten AP Essentials Connect to use the credentials of the current Windows user for authentication.
-
Open the following files in a text editor:
- C:\Program Files (x86)\Tungsten\AP Essentials Connect\ReadSoft.Connect.Host.exe.config
- C:\ProgramData\ReadSoft Software Services AB\ReadSoftOnlineConnect\Bin\App.config
-
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 Tungsten AP Essentials Connect
Generic issues
If you have problems running Tungsten AP Essentials Connect:
- Make sure you have access to the URL that corresponds to your location:
You can click the links above to test if you have access. Click the links using the same computer that runs Tungsten 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 AP Essentials using the same computer that runs Tungsten AP Essentials Connect to make sure you can connect to AP Essentials.
- If you use a proxy connection, make sure the settings are applied to the same user/account that runs Tungsten AP Essentials Connect. By default, this is a local System account. To test this, access AP Essentials using a location above, then change the Tungsten AP Essentials Connect user to the same Windows user you tested with.