ABBY Vantage Package
| Latest Version | 1.0.0.0 |
| Latest Release Date | 2021-12-1 |
| Author | Automation Studio Team |
| Supports Automation Studio Versions | From 7.5 |
This topic provides information on how to integrate ABBY Vantage into an automation solution in Automation Studio. For information on how to set up and use ABBY Vantage, see the ABBY Vantage documentation.
Description
Use this package to integrate an automation solution with ABBY Vantage. Specifically, this package allows you to send files to ABBY Vantage for analysis and receive the information generated.
ABBYY Vantage is a comprehensive Content Intelligence platform that provides AI-powered cognitive services and pre-trained and trainable skills that can "understand" business documents and extract actionable data and insights.
Before Using this Package
To use ABBY Vantage, you will need:
-
An ABBY Vantage license and user account
-
A Client ID and Client Secret
Before you can start processing documents using ABBY Vantage, you must:
-
Create ABBY Vantage skills
-
Configure ABBY Vantage skills
For instructions for all of the above, see ABBY Vantage documentation.
Summary of Contents
This package includes four types, each with its own functions and properties. The main type is the ABBY Vantage type.
Summary of Use
The use of ABBY Vantage consist of the steps below:
-
Monitor the transaction (optional)
Connect and Get Skills
Before your solution begins sending files to ABBY Vantage for analysis, it needs to connect and get the skills.
-
Create a variable of type ABBY Vantage.
-
Specify access details (Client Id, Client Secret, User Name, and Password) by populating the relevant properties of the ABBY Vantage variable.
-
Use the Connect method to connect to ABBY Vantage.
-
Get the skills using the Get Skills method. You will need to create a list variable of type Vantage Skills to store the skills received.
For security reasons, avoid using plaintext usernames and passwords. Instead, populate these properties with username and password data stored on the server, using an Application Login Info variable.
Define and Start a Single Transaction
A single transaction involves sending a single file for analysis and receiving the information produced.
Follow the steps below for each transaction:
-
Create a new transaction using the Create Empty Transaction method.
-
Attach a file to the transaction using the Add File to Transaction method.
-
Start processing the transaction using the Start Processing Transaction method.
Alternatively, perform all three steps above using the Create Transaction and Process File method.
Monitor the Transaction
You can monitor the transaction using the Get Transaction Status method. You will need to create a variable of type Transaction Status to store the status information returned.
This method should not be used more often than once per second.
If an error occurs, details will be stored in the Error property of the Transaction Status variable. You can store those details in a variable of type Error Details.
Download the Result
Download the result using the Download Result method.
Sample Project
In this sample scenario, the automation solution sends fuel receipts to ABBYY Vantage. ABBY Vantage uses a pre-defined Fuel Skill to extract information from the receipt and then returns that information to the automation solution.
The three pieces of information that are collected are:
-
Nozzle number
-
Receipt number
-
Product
The solution interacts directly with ABBY Vantage and there is no need for an RT Server.
Download the Project
-
Download the project files here.
-
Unzip the downloaded file.
-
Copy the folder ABBY Vantage AS to any folder, for example, the folder where you store other Automation Studio projects:
%appdata%\Nice_Systems\AutomationStudio\Projects
-
Copy the file sample_gas_receipt.jpg to any location.
Open the Project and Enter Account Details
-
Open the downloaded project in Automation Studio.
-
Set the initial values of the Password, User Name, Client ID, and Client Secret properties of the Abbyintegration variable.
Run the Project (Separated Steps)
The process below includes separate steps for creating an empty transaction, adding files, and starting the transaction.
-
Click Start Project.
The ABBY Vantage Home callout displays.
-
On the callout, click Connect. Doing so runs the Connect method of the Abbyintegration variable.
The Response property is now populated with the access token.
-
On the callout, click Get Skills.
Doing so runs the Get Skills method of the Abbyintegration variable.
The list of skills is displayed in the List Of Skills callout.
-
On the ABBY Vantage Home callout, click Create Transaction & Process.
The ABBY Vantage Transaction callout displays.
-
From the List of Skills callout, copy the ID of the FuelSkill.
-
Paste that ID into the ABBY Vantage Transaction callout and click Empty Transaction. Doing so runs the Create Empty Transaction method of the Abbyintegration variable.
The TransactionId property of the Abbyintegration variable is populated with the transaction ID for the transaction that was just created.
The TransactionId is also returned in the Response property.
Copy that value for future use.
-
In the ABBY Vantage Transaction callout:
-
Paste the full path to the file you want to load, e.g.
C:\temp\sample_gas_receipt.jpg
-
Paste the transaction ID.
-
Click Add Files. Doing so runs the Add File to Transaction method of the Abbyintegration variable.
-
-
In the ABBY Vantage Transaction callout:
-
Paste the transaction ID.
-
Click Start Transaction. Doing so runs the Start Processing Transaction method of the Abbyintegration variable.
The ResponseCode property of the Abbyintegration variable is set to 200, indicating that transaction processing has started.
-
-
In the ABBY Vantage Home callout, paste the transaction ID and click Trans Status. Doing so runs the Get Transaction Status method of the Abbyintegration variable.
The Status property of the TransactionStatus variable is populated.
At first, the status will be set to Processing.
If you click Trans Status again after a short while, the status will be set to Processed, indicating that the transaction completed.
-
Copy the value of the FileIDs property of the TransactionStatus variable.
You can copy this value from the Response value.
-
In the ABBY Vantage Home callout, paste in the transaction ID and File ID and click Download Result. Doing so runs the Download Result method of the Abbyintegration variable.
The response is displayed in the Response callout.
You can view the full response below.
Show
Copy{
"Transaction":{
"Id":"bf4a67e0-afaf-47d1-bf0f-ff44b7afa1c2",
"SkillId":"ceea8eae-0323-476f-ae28-fb6f9e3b6605",
"SkillName":"FuelSkill",
"Documents":[
{
"Id":"5aa00668-690b-4bb5-836e-0ab60aa57af3",
"ExtractedData":{
"DocumentDefinition":{
"RootConcept":{
"Id":"root",
"Name":"Empty",
"Fields":[
{
"Id":"10366775-f6c9-4e04-a715-e7fc36c4b663",
"Name":"Nozzle",
"Type":"String",
"Cardinality":{
"Min":0,
"Max":1
}
},
{
"Id":"3cea23c5-46da-46bf-8596-630e6288861a",
"Name":"Product",
"Type":"String",
"Cardinality":{
"Min":0,
"Max":1
}
},
{
"Id":"5ecf509b-3e8a-4ae8-a133-c29a415f6caa",
"Name":"Reciept",
"Type":"String",
"Cardinality":{
"Min":0,
"Max":1
}
}
]
}
},
"RootObject":{
"Id":"root",
"Concept":"Empty",
"Fields":[
{
"Name":"Nozzle",
"List":[
{
"Id":"3ca68128-4594-4d00-af6e-d1e03db83352",
"Annotations":[
{
"Source":"Image",
"ImageRegions":[
{
"Page":"e99f1cf2-1735-4bb3-ae0c-76f5dbfa1290",
"Rects":[
[
585,
1044,
653,
1094
]
]
}
],
"RawValue":"04",
"Confidence":1.0,
"SuspiciousSymbols":[
]
}
],
"Value":"04"
}
]
},
{
"Name":"Product",
"List":[
{
"Id":"7186caf7-533a-43b9-8433-412b2b57a9be",
"Annotations":[
{
"Source":"Image",
"ImageRegions":[
{
"Page":"e99f1cf2-1735-4bb3-ae0c-76f5dbfa1290",
"Rects":[
[
587,
1107,
798,
1158
]
]
}
],
"RawValue":"Petrol",
"Confidence":1.0,
"SuspiciousSymbols":[
]
}
],
"Value":"Petrol"
}
]
},
{
"Name":"Reciept",
"List":[
{
"Id":"93090c5f-2884-47e4-98f8-3ca177184a53",
"Annotations":[
{
"Source":"Image",
"ImageRegions":[
{
"Page":"e99f1cf2-1735-4bb3-ae0c-76f5dbfa1290",
"Rects":[
[
594,
1376,
778,
1430
]
]
}
],
"RawValue":"00010",
"Confidence":1.0,
"SuspiciousSymbols":[
]
}
],
"Value":"00010"
}
]
}
]
}
},
"Pages":[
{
"Id":"e99f1cf2-1735-4bb3-ae0c-76f5dbfa1290",
"SourceFile":"sample_gas_receipt.jpg",
"SourceImagePageIndex":0
}
]
}
],
"CreationTime":"2021-11-20T17:05:05.8658772+00:00",
"SourceFiles":[
{
"Id":"593965a7-fc46-4459-8d79-d71c9676a395",
"Name":"sample_gas_receipt.jpg"
}
]
},
"Version":"2.1"
}
The uploaded receipt is shown below. Information collected is indicated.
The table below indicates on which line each collected piece of information is returned in the full response.
|
Data |
Response Line NUmber |
Value |
|---|---|---|
| Nozzle Number | 75 | 04 |
| Receipt Number | 135 | 00010 |
| Product | 105 | Petrol |
Run the Project (Merged Steps)
To run the same process as above but with fewer steps:
-
Follow steps 1 to 5.
-
In the ABBY Vantage Transaction callout, paste in the skill ID and the full path to file to upload.
-
Click Create & Process Transaction. Doing so runs the method of the Abbyintegration variable.
-
Continue with the above process at step 9.
ABBY Vantage Type
The ABBY Vantage type is the main type in this package.
Properties
|
Property |
Description |
Type |
||
|---|---|---|---|---|
|
Client ID |
The ABBYY Vantage API application identifier. This should be created by a user with the Tenant Administrator role in ABBYY Vantage. See the ABBYY Vantage Administrators Guide. |
Text |
||
|
Client Secret |
The ABBYY Vantage client secret. This should be created by a user with the Tenant Administrator role in ABBYY Vantage. The client secret value is only available when it is being created. Store it in a secure location. See the ABBYY Vantage Administrators Guide. |
Text |
||
|
Error |
Stores any errors returned by ABBYY Vantage (Detail, Instance, Status, Title, and Type). |
Error Details |
||
|
Exception |
The exception event. |
|
||
|
Grant Type |
Specifies the grant type. For example, 'password'. |
Text |
||
|
Password |
The ABBYY Vantage password. |
Text |
||
|
Response |
The API call response from the following functions: Connect: The ABBYY Vantage access token Get Skills: The list of skills Create Empty Transaction: The transaction ID Monitor Transaction: The transaction ID, the status, the result Files including the fileId (required to download the results), and more. Download Result: The ABBYY Vantage results. |
Text |
||
|
ResponseCode |
The API call response code: l200 for successful. l201 for an error. l404 for no document with ID found. |
Number |
||
|
Scope |
Specifies the permissions scope. For example, 'openid permissions global.wildcard'. |
Text |
||
|
Status |
The API call status. Completed once done. |
Text |
||
|
URL |
The ABBYY Vantage URL: https://vantage-eu.abbyy.com/ |
Text |
||
|
User Name |
The ABBYY Vantage user name. |
Text |
||
Methods
|
Method |
Description |
Return |
|---|---|---|
|
Add File to Transaction |
Adds a file to an ABBYY Vantage transaction. |
None |
|
Connect |
Connects to the ABBYY Vantage API. |
Boolean |
|
Create Empty Transaction |
Creates an empty ABBYY Vantage transaction. |
Text |
|
Create Transaction & Process Ffile |
Creates an ABBYY Vantage transaction and processes the file. |
Text |
|
Download Result |
Downloads the result of the file processing from ABBYY Vantage. |
Boolean |
|
Get Skills |
Gets a list of skills from ABBYY Vantage. |
List of Vantage Skills |
|
Get Transaction Status |
Gets the transaction status. |
Transaction Status |
|
Start Processing Transaction |
Starts processing an ABBY Vantage transaction. |
None |
Response
The response is returned in a JSON array. The contents of the response differ for each of the functions listed above. The main properties in that array are described below.
|
Property |
Description |
|---|---|
|
Id |
The ID of the transaction. |
|
SkillId |
The ID of the applied skill. |
|
SkillName |
The name of the applied skill. |
| Documents |
The list of the Documents objects, together with the processing results.
For more information, refer to the JSON schema on the ABBYY Vantage Developer's Guide. |
| CreationTime | The time of the transaction. |
| SourceFiles |
The list of SourceFile objects, together with information about the source files submitted for processing. ABBYY Vantage currently only supports one file per transaction.
|
Response to Get Transaction Status
The following is a sample response for the Get Transaction Status method. Use the fileId from this response as an input parameter for the Download Result method.
Show
{
"id":"6def39bb-dddd-4241-9623-23e98d67b991",
"status":"Processed",
"documents":[
{
"id":"67d66822-9e3e-4475-a82b-dbe868ae6da8",
"resultFiles":[
{
"fileId":"5c3822ac-4329-43b5-9d30-04e157f5797d",
"fileName":"FuelSkill.json",
"type":"Json"
}
],
"businessRulesErrors":[
]
}
],
"sourceFiles":[
{
"id":"107c2b57-c684-4c28-804c-ca1b8fdbed62",
"name":"New doc 11-03-2021 09.25.53 am.jpg"
}
]
}Response to Download Result Method
The following is a sample response for the Download Result method.
Show
{
"Transaction":{
"Id":"6def39bb-dddd-4241-9623-23e98d67b991",
"SkillId":"ceea8eae-0323-476f-ae28-fb6f9e3b6605",
"SkillName":"FuelSkill",
"Documents":[
{
"Id":"67d66822-9e3e-4475-a82b-dbe868ae6da8",
"ExtractedData":{
"DocumentDefinition":{
"RootConcept":{
"Id":"root",
"Name":"Empty",
"Fields":[
{
"Id":"5ecf509b-3e8a-4ae8-a133-c29a415f6caa",
"Name":"New Field",
"Type":"String",
"Cardinality":{
"Min":0,
"Max":1
}
},
{
"Id":"3cea23c5-46da-46bf-8596-630e6288861a",
"Name":"New Field 2",
"Type":"String",
"Cardinality":{
"Min":0,
"Max":1
}
},
{
"Id":"10366775-f6c9-4e04-a715-e7fc36c4b663",
"Name":"New Field 3",
"Type":"String",
"Cardinality":{
"Min":0,
"Max":1
}
}
]
}
},
"RootObject":{
"Id":"root",
"Concept":"Empty",
"Fields":[
{
"Name":"New Field",
"List":[
{
"Id":"71517cd0-d96b-4a1f-82ed-3aff563b6238",
"Annotations":[
{
"Source":"Image",
"ImageRegions":[
{
"Page":"e3c2ea3e-cd90-46d4-9ed3-2ca4a6d26a29",
"Rects":[
[
606,
600,
794,
652
]
]
}
],
"RawValue":"80209",
"Confidence":1,
"SuspiciousSymbols":[
]
}
],
"Value":"80209"
}
]
},
{
"Name":"New Field 2",
"List":[
{
"Id":"f058e5aa-7212-4b65-9011-6b673d5e0685",
"Annotations":[
{
"Source":"Image",
"ImageRegions":[
{
"Page":"e3c2ea3e-cd90-46d4-9ed3-2ca4a6d26a29",
"Rects":[
[
567,
782,
792,
825
]
]
}
],
"RawValue":"Petrol",
"Confidence":1,
"SuspiciousSymbols":[
2
]
}
],
"Value":"Petrol"
}
]
},
{
"Name":"New Field 3",
"List":[
{
"Id":"cbd571bf-4c52-4332-bada-1109ba87d2d2",
"Annotations":[
{
"Source":"Image",
"ImageRegions":[
{
"Page":"e3c2ea3e-cd90-46d4-9ed3-2ca4a6d26a29",
"Rects":[
[
567,
736,
640,
775
]
]
}
],
"RawValue":"04",
"Confidence":1,
"SuspiciousSymbols":[
]
}
],
"Value":"04"
}
]
}
]
}
},
"Pages":[
{
"Id":"e3c2ea3e-cd90-46d4-9ed3-2ca4a6d26a29",
"SourceFile":"New doc 11-03-2021 09.25.53 am.jpg",
"SourceImagePageIndex":0
}
]
}
],
"CreationTime":"2021-09-25T18:51:39.4425611+00:00",
"SourceFiles":[
{
"Id":"107c2b57-c684-4c28-804c-ca1b8fdbed62",
"Name":"New doc 11-03-2021 09.25.53 am.jpg"
}
]
},
"Version":"2.1"
}