Administrator Guide

ABBYY Vantage Integration - Admin Guide

Background and Purpose

The Vantage connector allows for easy OCR and data capturing leveraging both M-Files and ABBYY Vantage. Before you can use the connector, a Vantage Setup must first be created in M-Files Admin. A Vantage Setup contains one or more Skill Setups.

Each Skill Setup maps an M-Files Class to a Skill ID. Each Skill Setup has 1 to many Vantage Mappings and 1 to many sub objects.

Each Vantage Mapping maps the Vantage Skill Property to an M-Files Property.

A Vantage Mapping can optionally be a Sub Object. A Sub Object maps a Vantage Skill Property to an M-Files Object, and itself has 1 to many Vantage Mappings. An example for usage of Sub Object could be Invoice Line Items, or a Vendor object.

To access the configuration, open M-Files admin, access the vault where the Vantage integration is installed, and navigate to Configurations --> Other Applications --> TEAM.Vantage

Logging Configurations

Logging can be enabled to help troubleshoot issues with the vault application. There are two types of logging: MFLogging and MFObject.

MFObject requires a document class to be used to create text files to store logging. To do this, create a new Document class called “App Log”. Once created, select this class for “App Log Class” under Logging Options.

Configurations around the MFLogging logging

• Enabled: enable/disable logging
• Default Target: default logging target
• File Targets: configures logging to file locations
• Event Log Targets: configures logging to the Windows event log
• Database Targets: configures logging to a database
• Mail Targets: allows log messages to be sent via email
• Advanced: advanced logging configurations

Credentials

In order to be able to send documents to Vantage, you must enter in the required credentials.

Vantage has 3 authentication schemes available: Resource Owner Password Credentials, Authorization Code Flow, and Client Credentials.

If using an external Identity Provider (i.e. Azure AD), choose either Authorization Code Flow or Client Credentials.

Prerequisites

Before configuring the credentials, please store the following values in a text file:

• Tenant ID: ABBYY Vantage Tenant ID (GUID)
  • Login to Vantage --> Configuration --> General
  • 
• Client ID: client ID generated in ABBYY Vantage
  • Login to Vantage --> Configuration --> Public API Client
    • New Client --> Add Client
    • 
    • 
    • Copy the Client ID from the popup into the M-Files configuration
• Client Secret: client secret (associated with Client ID) generated in ABBYY Vantage
  • Copy the Client Secret from the popup (previous step) into the M-Files configuration

Authorization Code Flow

To get the authorization code, click on Dashboard, and click on the link highlighted in blue underneath “Get Auth Code”:

This will open a new window to your identity provider. Once you login successfully, there will be a code in the address bar. Copy this code and paste it in “Authorization Code” and hit Save.

Resource Owner Password Credentials

• Username: ABBYY Vantage username
  • Vantage username
• Password: ABBYY Vantage password for the username entered
  • Password for the Vantage username entered above

Client Credentials

• Client ID: client ID generated in ABBYY Vantage
• Client Secret: client secret (associated with Client ID) generated in ABBYY Vantage

Testing Authentication

In order to check if the token authentication process is successful, go to the Dashboard and click on “Check Token”. If successful, a message will be generated like this:

If unsuccessful, an error will appear with the description of the error:

Override Properties

Each document will need to store a transaction ID, file ID, manual review link, and error property. These are defaulted and need not be changed

Workflow Override Properties

Used to override the default workflow. This will be used to determine what state the document should be sent to Vantage, and what states the document should be in afterwards. These need not be changed from the default values

Mail Source Split Attachments Workflow Set-up

Required if using mail source. This will be used to determine if an attachment should be split from the mail message.

Enable Authentication on Manually Reviewing a Document in Vantage

If enabled, users will have to login to Vantage in order to review the document. Defaults to false.

Save Original Document and Save Raw Json Configuration

If “Save original document?” is enabled, then the original document will be stored in M-Files and referenced on the completed document. Defaults to false.

A new Boolean property called “Is Original Document” needs to be created with alias of TI.Vantage.Property.IsOriginalDocument. This is used to determine if a document is an original document or not. Can be overrided with a different property with the same Boolean data type.

A new single-select property called “Original Document” that selects from Documents filtered on “Is Original Document” needs to be created with alias of “TI.Vantage.Property.OriginalDocument”. This is used to store the original document. Can be overrided with a different property with the same single-select filters.

If “Save raw json response?” is enabled, then the raw json file will be stored in M-Files and referenced to the completed document. Defaults to false.

A new Document class will need to be created with the alias of “TI.Vantage.Class.RawJson”. This class will be used to create the raw json document. Can be overrided with a different class.

A new single-select property called “Related Document” that selects from Documents needs to be created with alias of “TI.Vantage.Property.RelatedDocument”. This property lives on the raw json class and is used to reference the completed document. Can be overrided with a different property with the same single-select.

Enable Restart a Transaction when 404 Error is Encountered

If enabled, when a transaction is not found (status returns 404), then a new transaction will be created. This is intended to handle transactions being automatically deleted by the Vantage system after 14 days. Defaults to false.

Generic Skill ID

Required if genericizing document ingestion (using a classifier skill within a process skill). Leave empty if not using this. This is what will determine what skill in Vantage is to be used when a document object that doesn't have a skill config is created (i.e. Document class)

Skill Configuration

Configure the Vantage skill to M-Files class/properties

Expand the Skill Configuration dropdown:

Click on “Add SkillConfig” and expand it:

Enter in the name. If the Generic Skill ID is set, this is what will be used to retrieve the skill configuration. Is also used to see what Skill Setup you are configuring.

By default, the Vantage integration will replace the file with a OCR Text searchable pdf version from Vantage. If you wish to disable this, enable “Disable File Replacement”.

Vantage cannot process protected pdf files. If you wish to send protected pdf files to Vantage, enable “Enable Protections Check”. This will attempt to remove protections such as passwords, signatures, etc. from the version of the PDF file sent to Vantage for capture. Defaults to false. Do note that this may result in a malformed file when returned from Vantage. Generally, this only affects the logo. It is recommended to pair this flag with the “Disable File Replacement” flag, and to set the “Convert to Searchable” action in the final state of the workflow.

Enter in the appropriate Vantage skill ID (The skill GUID obtained from the Vantage Skill edit page URL).

Note that when configuring a skill in Vantage, please ensure that on the Output Exported Data settings, “Save fields data to” is enabled, and that “Values, metadata, and field structure for each document” is selected.

Select the M-Files Class in which you want to use the skill with.

Select the M-Files property that you wish to store the name defined above. Optionally enter in the Vantage Name. Used to overwrite the name of the original file after it is processed by Vantage. For example, if you want to overwrite the name of an invoice with the Invoice Number value from Vantage, enter "Invoice Number" as the Vantage Name.

Optionally enter in the Split Object Name Suffix. Only should be entered if using Split Document skill. If the object has been split, this is the unique identifier. For example, if you want to append to the existing name of the object with the Invoice Number value from Vantage, enter "Invoice Number" as the Vantage Name.

Expand Vantage Mappings, click “Add VantageMapping” and expand it

The Vantage Property can be viewed on the document in Vantage. For example, if we wanted to store the Invoice Number inside an Invoice property, it would look like this

Continue to add as many Vantage Mappings as needed following the steps above.

If a sub object is needed, set “Add Sub Object?” to Yes, and expand the Sub Object Mappings

The Vantage Property is the sub object you would like to reference on the document. For example, if it were Line Items, you would enter in “Line Items”.

The M-Files Object and Class is what will be used to create the sub object. The Name Property is what will be used to store the object’s name defined in “Vantage Name” and to reference the sub object. Since we entered in Line Items, it would make sense to use the Line Item object and class in M-Files.

As with Skill Setups, the sub object also uses Vantage Mappings to store Vantage values inside M-Files properties.

“Use object ID to detect existing object” will have the integration first check to see if an object in M-Files exists using the ID of the object in Vantage. If it finds an object, it will add the object lookup to the specified M-Files Property. If enabled, you have the option to specify what the ID property on the JSON should be. This defaults to “ID”.

“Use specified Vantage property to detect existing object?” will have the integration check to see if an object in M-Files exists used the specified Vantage property of the object in Vantage. If it finds an object, it will add the object lookup to the specified M-Files property. If “Use object ID to detect existing object” was enabled, then it will check to see if an object has been found already. If it has been found, then it will skip the aforementioned check. If enabled, you must define what the Vantage Match Property and M-Files Match Property is. The specified M-Files Match Property is what is used to match against the value of the Vantage property. You can optionally adjust the Search to either Equals based or Contains based. Contains based only applies to text properties whereas Equals based applies to text, integer, and floats.

If “Create Sub Object” is enabled, it will create a new object in M-Files if an existing object was not found in either of the checks above (“Use object ID to detect existing object” and “Use specified Vantage property to detect existing object?”). If none of the checks above were enabled, then it will automatically create the object if enabled.

Create duplicates sets the action on what to happen if the sub-object already exists in M-Files

• If Yes, create duplicates
  • Add the new object regardless
• Else, if No
  • If an object already exists in M-Files matching all the captured properties
    • Associate the new parent object (ex: invoice) to the existing M-Files object
  • Else
    • Create a new object and associate to the parent object

If using split documents, properties can be inherited from the original document by specifying properties in the Inherited Properties configurations.

Skill Parameters

Skill Parameters can be used to pass in data for use within Vantage. An example would be passing in a Business Unit ID that determines which Vendor to search in the data catalog. This helps narrow down the vendors to match with the invoice. Skill Parameters are limited to only 10 per Vantage.

If the skill parameter is to reference a property on the document object that is an object (i.e. a Vendor), then set Is ObjType to Yes, and select the property to reference on that object itself.

If the property is not an object, then leave Is ObjType? Set to No and select the property on the document object that you wish to reference.

Poll Transactions Button Configuration

The Poll Transactions Button Configuration allows admins to specify a list of user groups or individual users who can see and click the Poll Transactions button in the Desktop and Web clients. These configurations are optional, however, if no user groups or users are selected, all M-Files users will be able to see and click the Poll Transactions button. If a user is both a member of a user group in the User Group(s) list and in the User(s) list, they will still be able to see and click the Poll Transactions button.