ABBYY VANTAGE 2.5.

VANTAGE INTERMEDIATE
Task 01 Creating a Custom Connector
Task 01 Creating a Custom Connector

In this task, we will show you how to create a custom connector using the Vantage
REST API. As an example, we will create a connector for Gmail that will take a
Purchase Order document attached to an email and send it for processing into
Vantage.
By completing this task, you will learn how to:
• Create a Client ID and Client Secret and choose the Authentication schema
• Create transactions and get a Skill ID using the Swagger tool
• Create a custom connector for Gmail using the Google Apps Script
• Add the connector to Gmail
• Send documents for processing straight from your Inbox folder
• Get the processing results, again using the Swagger tool
To complete this task, you need to either have or create a Gmail account.

Note: Please follow the task instructions when creating and naming folders, Skills, and files.

Please consider environment before printing this task.

If you really need to print it—you may not need to print the two first pages (title list and table of contents).

Vantage Intermediate—Task 01 Creating a Custom Connector

Task 01 Creating a Custom Connector

LOG IN TO VANTAGE, SET UP AN API CLIENT, AND GET A SKILL ID

To process a document, we will use a pre-built Document Skill (Purchase Order US). Let’s find the
Skill ID; we will need it further in this task.

1. Log in to Vantage using your account credentials.

To access Vantage, you need to have your own account that was issued before the training event.
You should have received an e-mail with a link to the Vantage platform, as well as your account
credentials.
2. Click Configuration to open the Tenant Administration window:

3. Click on the Create API Client button.

You will get information about your newly created API client.

Vantage Intermediate—Task 01 Creating a Custom Connector

 Important! Save the Client Id and Client Secret. Click on the Save to File button to save the
“New Client current date.txt” file containing the API client information to your computer. You
will not see this option later, and you will need this information to complete this task.

Then close the window.

4. Enter the new Public API client name in the Client Name field: “Task 06 Creating a Custom
Connector”.
5. At the bottom of the screen, under Allowed Flows, select Allow Resource Owner Password
Credentials Flow. (In this task, we will use the user name and password to authenticate in
Vantage.)

6. Now open the Help page by clicking Help>Documentation in the bottom-left corner of the
screen.
7. Once you are on the Help page, select the
Vantage API card.
8. You have opened the Swagger tool. First of all, you
need to authorize. Click the Authorize button to the
right.
9. Check the two checkboxes at the bottom-left corner to grant Swagger access to all scopes. Click
Authorize. You may need to provide your Vantage credentials.

Vantage Intermediate—Task 01 Creating a Custom Connector

10. Close the Authorization window.
11. Scroll down to the Skills section.
12. Click on the very first line—GET /api/publicapi/v1/skills to get the list of all available Skills.

13. Click the Try it out button to the right, then click the blue Execute button.
14. In the Response body below, you will see a list of all available Skills with listed ID’s, names, and
types.
15. Press Ctrl+F to open up a search pane. Search for the Purchase Order US Skill. Save the
Purchase Order US Skill ID to Notepad. We will need the Skill ID later.

CREATE A CONNECTOR USING THE GOOGLE APPS SCRIPT

To complete this task, you need to have a Google account with a mailbox. You can use a personal
account, or create a new one. To create a Google email account, click here.
16. Log into your Google account and open the Apps Script via this link:
https://script.google.com/home, then click View Dashboard if prompted.
17. Click New project at the top-left corner of the screen.
18. Enable the “appscript.json” manifest file editor. To do so, open
Project Settings by clicking the gear icon in the left-side menu. Then
check the checkbox in front of the Show “appscript.json manifest file in editor” option.

Vantage Intermediate—Task 01 Creating a Custom Connector

19. Go back to the Editor.

20. You will see that appscript.json file has appeared under the Files section. Open it.

21. You need to adjust project settings on this page:

• Request permission to connect to an external service (Vantage)
• Request permission to read e-mails and attachments
• Adjust application settings (name, icon, and location)
• Adjust a contextual trigger to open the application when a Gmail message is opened

Vantage Intermediate—Task 01 Creating a Custom Connector

You will find a “ready-to-go” script in Appendix A. Copy and paste it to the editor, instead of the
default text. Don’t change the sample code.

------ This should be deleted.

We highly recommend that you read through the script and get familiarized with the described
settings.
22. Open the Code.gs file from the left-side menu.
Here you need to write JavaScript code that will do the
following:
• Set up your Vantage credentials
• Specify the API Client ID and Client Secret
• Copy to Notepad your Vantage URL (open Vantage,
then copy the URL where you have an account –
please see below)

Do not copy this example, as you might have an account in a different Vantage environment!

• Go to the Configuration > General, then copy to the Notepad your Tenant ID.

Vantage Intermediate—Task 01 Creating a Custom Connector

 • Set up the Purchase Order US Skill ID that we found earlier
• Call the script via a button click in Gmail
• Get an access token scoped to the current message, and use it for the GmailApp
• Get the subject of the email
• Get the attachments
• Get the attachment in base 64 string format
• Login
• Create a transaction
• Wait for the result
• Get the transaction status
• Create a string to display the transaction status
• Request authentication on the Vantage server
• Set up REST call parameters
• Call REST API
• Read the response
• Parse the JSON response
• Read the access token
• Create and run a transaction
• Get the transaction status

Vantage Intermediate—Task 01 Creating a Custom Connector

You will find a “ready-to-go” script in #Appendix_B. Copy and paste it to the editor, instead of the
default text. Change the red text in the Global Constants part of the script, providing your Vantage
details. Do not change any other parts of the sample code.

------ This should be deleted.

Don’t forget to add your Vantage login, password, the valid Skill ID, and the valid Vantage URL,
your Tenant ID, created Client ID and Client Secret to the script template!

Note that the script is quite long. Don’t inadvertently truncate anything while copying and
pasting!
When copying from a PDF, syntax errors may appear. If you see any syntax errors during
compilation, ensure that you haven’t copied a page footer along with the script, and confirm
that the script lines are not broken. The benefit of doing this is you become more familiar with
the code as you resolve any problems.
If, after thorough examination of your pasted script, syntax errors persist, please download
this appendix_B_code.js JavaScript file, then open it with Notepad. After that, you can copy
and paste the code without encountering syntax errors.

23. Save your connector by clicking at the top of the screen.

ADD THE CONNECTOR TO GMAIL

24. Run the script by clicking the Run button at the top of the screen.

25. When asked to authorise, click on the Review permissions button and pick your Google
account.

Vantage Intermediate—Task 01 Creating a Custom Connector

26. You will get a warning that this application wasn’t verified by Google. Continue by clicking
Advanced, then Go to Untitled project (unsafe). When prompted, click Allow.

27. After running the script, you might receive this error in the Execution log:

For the purposes of this task, this error message is not important—so just ignore it.
28. Click Deploy>Test deployments at the top-right corner of the screen.

29. In the Test deployments window, click Install, then Done.

Vantage Intermediate—Task 01 Creating a Custom Connector

30. Open your Gmail mailbox (https://mail.google.com/mail/u/0/#). The Vantage connector icon
should appear on the right panel. If it didn’t appear, try refreshing the page.

SEND A DOCUMENT TO VANTAGE FROM GMAIL

Now that we have created and deployed the connector, we can test it by sending a Purchase Order
for processing.
31. If you haven’t downloaded the Purchase_Order.pdf file yet, go to the Vantage Intermediate:
Creating a connector with REST API lesson and download the sample document from the
Practice: Creating a Connector chapter.
32. Send an e-mail to the same Gmail account you were using to create a connector. You do not
need to add a subject line. Attach the Purchase_Order.pdf file from the Classwork/Task_01
folder.
33. Refresh your Gmail mailbox. Open the e-mail with the attachment. Then click on the Vantage
connector icon.

Vantage Intermediate—Task 01 Creating a Custom Connector

34. After you click on the logo, the connector will be launched
automatically. The application will create and start a
transaction, and you will see the transaction ID on the right
panel. Copy that transaction number—if it is not fully
displayed, triple-click on any part of the transaction number.
That will select the entire string. Then copy that value to an
editor and delete the prefix: Transaction:, leaving you with
just the transaction number.

GET THE TRANSACTION RESULTS USING THE SWAGGER TOOL

35. Open the Swagger tool and authorize.
36. Scroll down to the Transactions section.
37. Get the transaction information. Scroll down to the GET
/api/publicapi/v1/transactions/{transactionId} line, and click on it.
38. Click Try it out, paste your transaction ID (the one you recently recorded from the Gmail
environment), then click Execute.
The transaction info will be returned below. Copy the fileId under “documents / resultFiles” in the
Response body to Notepad.

Vantage Intermediate—Task 01 Creating a Custom Connector

39. Now you can get the result file with the extracted data. Scroll down to the GET
/api/publicapi/v1/transactions/{transactionId}/files/{fileId}/download line, then click on it.
40. Click Try it out, enter the transaction ID, and the File ID that you copied from the transaction
info, then click Execute.
You will get a response with a downloadable JSON file with the Purchase Order processing results.
This file can be used in any of your applicable downstream business processes.

Excellent! You have successfully created a custom connector and tested it!

Vantage Intermediate—Task 01 Creating a Custom Connector

APPENDIX A
{
"timeZone": "Europe/London",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"oauthScopes": [
"https://www.googleapis.com/auth/drive.addons.metadata.readonly",
"https://www.googleapis.com/auth/gmail.addons.current.action.compose",
"https://www.googleapis.com/auth/gmail.addons.current.message.readonly",
"https://www.googleapis.com/auth/gmail.addons.execute",
"https://www.googleapis.com/auth/script.locale",
"https://www.googleapis.com/auth/script.external_request"
],
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "ABBYY Vantage",
"logoUrl": "http://images.netexam.com/images/11356/Vantage_64.png",
"useLocaleFromApp": true
},
"gmail": {
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "onGmailMessage"
}
]
},
"drive": {
"onItemsSelectedTrigger": {
"runFunction": "onDriveItemsSelected"
}
}
}
}

Vantage Intermediate—Task 01 Creating a Custom Connector

APPENDIX B

//CHANGE THIS PART

// define global constants
const VANTAGE_LOGIN = '[email protected]'; // set up your login
const VANTAGE_PASSWORD = 'Password'; // set up your password
const VANTAGE_SKILL_ID = 'Skill ID'; // put here the Skill ID
const VANTAGE_URL = "https://vantage-eu.abbyy.com"; // put here the Vantage URL
const VANTAGE_CLIENT_ID = 'Client ID'; // put here the Client ID
const VANTAGE_CLIENT_SECRET ='Client Secret'; // put here the Client Secret
const VANTAGE_TENANT_ID = 'Tenant ID'; // put here your Tenant ID

//DO NOT CHANGE THE FOLLOWING PART OF THE CODE

// standard function - call script on a button press in Gmail

function onGmailMessage(e) {

// Get the ID of the message the user has open.

var messageId = e.gmail.messageId;

// Get an access token scoped to the current message and use it for GmailApp calls.
var accessToken = e.gmail.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);

// Get the subject of the email.

var message = GmailApp.getMessageById(messageId);
var subject = message.getThread().getFirstMessageSubject();
// get attachments
var attachments = message.getAttachments();
var attachmentInBase64='';
var attachmentName ='test.pdf'
var displaytext='';

for (var k = 0; k < attachments.length; k++) {

// get the attachment in base 64 string.

// attachmentBytes=attachments[k].getBytes();
attachmentInBase64 = Utilities.base64Encode (attachments[k].getBytes());
attachmentName=attachments[k].getName();

// login
var token=VantageAuthenticate(VANTAGE_LOGIN,VANTAGE_PASSWORD);

// create a transaction
var transactionID=RunTransaction(token,VANTAGE_SKILL_ID,attachmentInBase64,attachment
Name)

Vantage Intermediate—Task 01 Creating a Custom Connector

// wait for a result
// there is a sleep method for example. You can check the status = processed in a loop
Utilities.sleep(10000);

// get a transaction status

var transactionStatus=GetTransactionStatus(token,transactionID)

// create a string to display

displaytext=displaytext+'Name:'+attachmentName+'\n\nTransaction:'+transactionID+'
\n\nStat us:'+transactionStatus+'\n-----------------\n\n'; }

// this is a UI creation section

var exampleCard = CardService.newCardBuilder()
.setHeader(CardService.newCardHeader()
.setTitle('Processing attachments'))
.addSection(CardService.newCardSection()
.addWidget(CardService.newTextParagraph()
.setText(displaytext)))
.build();
return [exampleCard];

// authentication on the Vantage server

function VantageAuthenticate(login,password) {

// define headers
var headers = { 'Content-Type' : 'application/x-www-form-urlencoded' }

// define a request body

var payload ={
'grant_type' : 'password',
'scope':'openid permissions global.wildcard',
'username':login,
'password':password,
'client_id':VANTAGE_CLIENT_ID,
'client_secret':VANTAGE_CLIENT_SECRET }

// set up the REST call parameters

var options = {
'headers': headers, // headers
'method' : 'post', // call type
'payload' : payload // call body
};

// call the REST API

var response=UrlFetchApp.fetch(VANTAGE_URL+'/auth2/'+ VANTAGE_TENANT_ID +
'/connect/token', options);

// read the response

var json = response.getContentText();

Vantage Intermediate—Task 01 Creating a Custom Connector

// parse the json response to objects
var data = JSON.parse(json);

// read access token

var token=data.access_token;

return token;

// create and run a transaction

// A 'transaction/run' method is used for demo purposes.
// It is recommended to create a transaction and add files instead.

function RunTransaction(accesstoken,skillid, file, fileName) {

var payload = {
'skillId' : skillid,
'file' : {
'content': file,
'fileName': fileName }
}
var headers = { 'Authorization' : 'Bearer '+ accesstoken }

var options = {
'headers': headers,
'method' : 'post',
'contentType': 'application/json',
'payload' : JSON.stringify(payload)
};
var response=UrlFetchApp.fetch(VANTAGE_URL+'/api/publicapi/v1/transactions/run', option
s);

var json = response.getContentText();

var data = JSON.parse(json);

var transactionID=data.transactionId;

return transactionID;

// get a transaction status

function GetTransactionStatus(accesstoken, transactionID) {
var headers = {
'Authorization' : 'Bearer '+ accesstoken
}

var options = {
'headers': headers,
'method' : 'get',
};

var response=UrlFetchApp.fetch(VANTAGE_URL+'/api/publicapi/v1/transactions/'+transact
ionID, options);

Vantage Intermediate—Task 01 Creating a Custom Connector

 var json = response.getContentText();

var data = JSON.parse(json);

var status=data.status;

return status;
}
}

Vantage Intermediate—Task 01 Creating a Custom Connector