Integrate Third-Party Software with a Web Document Import Application

Introduction

You can integrate almost any third-party system with Web Document Import, to enable such systems to prepopulate particular document keys in import applications. The prepopulated data is called "seed" data.

For example, if a third-party ERP system holds data about particular customers, it might provide a facility for its users to upload (to Autoform DM) documents that are related to that customer, such as invoices for their orders. In this scenario, the ERP system could initiate an import application in Autoform DM, and pass the customer's Customer ID to the import application. In the import application, after the user selects documents to import, the Customer ID key for each of those documents would already be filled.

Another way that this feature is used is to provide values for hidden fields. Within the configuration of an import application, key definitions are bound to the import application. However, as part of this configuration, some of those key definitions can be specified as hidden, so that when a user uses the import application, those keys are not present in the Key Input and Table Input panes. Although the user cannot enter values for hidden keys, the integrations described on this page can supply values for them.

Types of Integration

There are two types of integration with Web Document Import:

• URL-parameter-based integration: A relatively simple integration that passes key values to import applications through URL parameters.

• JavaScript integration: A more secure (and more complex) integration that requires Autoform DM to store the key values that you want to prepopulate import applications with. The integration is more secure because the key values are stored and recalled by Autoform DM, rather than included in a URL as plain text.

User Workflow

With both types of integration, an import application automatically opens when the third-party system triggers a document import (for example, if a user clicks a particular button in that third-party system). After the import application loads and the user selects documents to import, particular keys in the Key Input and Table Input panes will be prepopulated with the supplied seed data.

URL-Parameter-Based Integration

Use the following format to construct a URL that passes key values to a specified import application:

<base-URL>/dm/apps/document-import/<import application name>?documentDef=<document definition name>&seed=use-query-params&key-<key name>=<key value>

For example:

https://autoformDMServer/dm/apps/document-import/import-invoices?documentDef=invoice&seed=use-query-params&key-customer-id=13578

Appropriately replace the following elements of the URL:

• <base-URL>: The base URL of the Autoform DM installation.

• <import application name>: The Name of the import application that you want the integration to start.

• <document definition name>: The Name of the document definition that you want the import application to automatically apply to the selected documents.

  • This parameter is optional. If you omit it, the user must select a document definition after they select documents to import.

• <key name>: The Name of the key that you want to supply a value for.

• <key value>: The value that you want to prepopulate that key with (in the import application).

  • You can supply one key name and key value pair, or multiple pairs, or no pairs.

  • To supply multiple pairs, include multiple &key-<key name>=<key value> parameters in the URL.

JavaScript Integration

When integrated, a third-party software application can direct the user to a URL that will launch an import application with document key data populated.

Note

Cross-Origin Resource Sharing (CORS) must be configured on the server using the system property efs.cors.permitted.origins. This only needs to be set when using the produceSecureLaunch function.

In the node.properties file, enter the domain URL that the imported documents originate from.

Substitute * (asterisk) for the domain.

Functions

The method used to construct the URL will vary depending on the function used. Formpipe recommends using the encrypted function produceSecureLaunch, particularly for sensitive data.

A script file containing the functions to launch a document import is available at the following URL: <base-URL>/dm/integrations/doc-import-launcher.js . Substitute <base-URL> for the base URL of the Autoform DM installation, or for http://localhost or https://localhost if appropriate. For example, https://autoformDMServer/dm/integrations/doc-import-launcher.js

This can be used to include the script in your application and to view the code along with comments.

You can call one of two functions: buildDirectLaunch or produceSecureLaunch. For an example of how to use them, see the following Example section of this page.

Function – buildDirectLaunch

This function builds and returns a URL that will start an import application in the Autoform DM web application with fields prepopulated. This function differs from produceSecureLaunch in that the seed data is passed in the URL. However, the consequence of this is that the seed data will be:

• Captured within any system logs or proxy logs that log URLs.

• Visible to anyone able to view the URL.

• Easily editable by a user or any "middleman" agent.

Function – produceSecureLaunch

This function builds and returns a URL that will start an import application in the Autoform DM web application with fields prepopulated. The URL does not contain the key values themselves; instead, the URL contains a unique identifier that Autoform DM uses to securely retrieve seed values stored on the server.

Consequently, the only information that is visible in the URL (and captured by any system or proxy logs that log URLs) is the seed ID, which can used only by an authenticated Autoform DM user. Using produceSecureLaunch prevents any leakage of sensitive information within logs or to observers of network traffic.

Example

In this example, parameters are defined and then passed to either function.

// 1) Define parameters

  const appName = "my-import-name"

  const doc = {

    documentDef: "invoice",

    keys: {

      "string-key-1": "a new dynamic value",

      "number-key-1": 12345,

      "date-key-1": "2021-08-03",

    },

  }

  const config = {

    baseUrl: "http://localhost:8080" // ensure to set the correct server name and port

  }

  // 2a) Direct launch

  const url = DocImportAppLauncher.buildDirectLaunch(appName, doc, config);

  

  // 2b) Secure launch

  const url = DocImportAppLauncher.produceSecureLaunch(appName, doc, config);