iConnector Getting Started

What are you looking for?

• What is the iConnector?
• iConnector Server Setup - if you want to setup your own iConnector server to upload documents to
• iConnector API - if you want to write your own iConnector API for receiving documents or sending documents to Straatos
• Configure iConnector Server from Admin Panel (continue reading here)

What is the iConnector?

• The iConnector is a set of webservices (and definitions) that facilitate the communication between the CumulusPro Clients (Scan+ProcessLite, Mobile Capture), the Admin Panel and the Backend/Storage System.
• Transmission of all data is secured by HTTPS/SSL.
• The iConnector has two components: Client.Connector and Server.Connector.
• The Client.Connector is integrated within the CumulusPro Clients, but can as well be used by developers to create their own clients and integrate with CumulusPro Admin Panel, Straatos and Backend System.
• The Server.Connector is the integration into the backend/storage repository. For example Document Management Systems, Accounting Systems, Cloud Storage Systems etc. The possibilites are limitless. The Server.Connector receives calls from the Client.Connector and translates them to the Backend System.
• There are two scenarios where the iConnector can be installed/hosted: Customer Hosted Server.Connector and CumulusPro hosted Server.Connector. The scenarios are explained here:

Server.Connector Hosted By Customer

The iConnector is hosted within the customer's system where it integrates directly with the backend. See Diagram below (Scenario 1: Server.Connector Hosted By Customer).

The advantage of this deployment is that the documents and data travel from the client directly to the customers server (without going through a 3rd party or CumulusPro's system) and from there directly into the backend system. Hence optimised for speed and privacy.

Server.Connector Hosted by CumulusPro

CumulusPro is hosting the Server.Connector (See diagram below "Scenario 2. In this case, the documents are sent from the CumulusPro clients to the Server.Connector in the CumulusPro Cloud Infrastructure and from there to the Customer's Backend System. This scenario makes sense if the backend system is for example a Cloud based repository (SaaS), such as Google Drive. Documents then travel through the CumulusPro Infrastructure. The advantage is that the customer does not need to host the Server.Connector.

Configure iConnector Server in Admin Panel

There are two scenarios where iConnector Server can be configured.

1. Capture (e.g. Web Scan or Mobile Capture) and upload to your backend system
2. Capture and upload to Straatos and at the end of the Straatos process, upload to an iConnector Server.

Capture and Upload to your backend

In this scenario, documents are captured with the ScanApp, the Mobile Capture or any other App that supports the upload to an iConnector.

Documents and Metadata are uploaded from the clients directly to the iConnector server and do not pass through CumulusPro environment, except if the iConnector Server is installed in the CumulusPro Environment.

The settings to configure the iConnector Server can be found in the Admin Panel in the 'Organisation' tile:

The red boxes are the two settings that are relevant for the iConnector setup.

First, select the Server Connector URL from the Dropdown list:

Note: If you access the Asia or US Admin Panel, the connector have in brackets (Asia) or (US). The connectors have the same functionality, just indicating the region they are running.

The options available are:

1. Straatos
2. Google Drive
3. CSV
4. XML
5. SFTP
6. Custom

Straatos

For Straatos, please see the next section on this page 'Capture and Upload to Straatos'.

Google Drive

Before using the Google Drive connector, you will need to create have at least 1 user account with 'Google Drive Federation' enabled (can be found in 'Authentication' tile under Accounts. Each user that uses the Scan or Mobile Capture client and wants to upload to Google Drive, needs to have this setup. Otherwise an upload to Google Drive will fail.

The Google Drive Export can be used with the 'Anonymous (Default) Account' option. The user selected in the 'Anonymous (Default) Account' option needs to setup with the 'Google Drive Federation'.

Setup Account (User) with Google Drive

To setup the Google Drive Federation:

1. In Admin Panel, goto Authentication - Accounts and select an account that should have the Google Drive Authentication enabled.
2. Click on the checkbox to enable Google Drive.
3. You will be asked to select the Google Drive account to use.
4. Google then requests your permission, click on 'Allow'.
5. Once the Admin Panel is shown, the 'Google Drive' is now enabled and a button 'Select Folder' is shown.
6. Click on Select Folder.
7. Select the Folder where the documents should be stored in.

Custom Configuration

The Google Drive connector supports the following Custom Configuration on Organisation level:

(copy & paste the code into the Custom Configuration section).

<Configuration>
 <ExportXML>true</ExportXML>
 <UseDocumentNameForXML>true</UseDocumentNameForXML>
 <CreateFolderForDocument>true</CreateFolderForDocument>
</Configuration> 

ExportXML can either be 'true' or 'false'. If set to 'true', the metadata will be exported as an XML file for each document. If set to 'false', only the documents are exported.

UseDocumentNameForXML can either be 'true' or 'false'. If set to 'true', the same name for the XML is used as for the document (just with different file extension). If set to 'false', a Unique ID (GUID) is used for the Filename. If the setting ExportXML is set to 'false', this setting will be ignored.

CreateFolderForDocument can either be 'true' or 'false'. If set to 'true', each document will be saved into it's own folder. If set to 'false', all documents are saved to the same (root) folder. To set this to 'true' makes sense for uploading JPG (color) images as each page will be one file. Hence if the document has it's own folder, each JPG file for a specific document will be in this folder.

Save Name Template

The Save Name Template allows the definition of the Document and XML file name with a combintion of fixed values and variables that are replaced during runtime with document specific values. The Google Drive connector supports the 'Save Name Template' option at the Document Type level.

To configure Save Name Template:

1. In Admin Panel, goto 'Document Types' and select a document type.
2. In the 'Save Name Template' option enter the name of the file.
3. The Google Driver connector supports the following variables:

• <DOC_UNIQUE_ID> - Document unique ID
• <GUID> - creates the files with a GUID
• 'string' - Any string without <> will be written as text (e.g. BPM-)
• <YYYY> - Current year (e.g. 2014)
• <MM> - Current month (e.g. 12)
• <DD> - Current Day (e.g. 31)
• <hh> - current Hour (e.g. 24)
• <mm> - current minute (e.g. 59)
• <ss> - current second (eg. 59)
• <0000> - running number with placeholders (example 0001, 0002 etc). Note: the running number will be reset when restarting the IIS.

CSV

The CSV iConnector works in a similar way to the XML iConnector. The difference is that the Metadata (index fields) are exported in a CSV file instead of an XML file and there are more configuration options.

Custom Configuration

On Organisation Level, enter the following Custom Configuration:

{
  "TargetPath": "D:\home\site\wwwroot\demo\test",
  "CreateSubFolder": true
}

TargetPath - This is the local path on the iConnector server. You can choose any that is locally accessible to where the iConnector Server is installed. The above sample code puts the files into the Webserver directory and hence the files are available publicly over the Internet.

CreateSubFolder - If set to 'true', each document is added as a subfolder to the TargetPath. We recommend this settings so the files are easily found and distinguished.

If you are interested in the CSV iConnector Server to be installed on your own servers, you can download it here. For instructions on how to install the CSV iConnector Server, follow the section 'iConnector Server Setup'.

Document Type Custom Configuration

Enter the following code into the Custom Configuration at Document Type level and then modify to suit your needs.

{
  "SortOrder": [
    {
      "Position": 1,
      "Item": "Field1"
    },
    {
      "Position": 2,
      "Item": "Field2"
    },
    {
      "Position": 3,
      "Item": "FilePath"
    }
  ],
  "TIFFOutputFormat": "multipage",
  "CSVFileName": "TestCSV.csv",
  "IncludeHeader": "true",
  "Delimiter": ";",
  "SubfolderNameTemplate": "<YYYY>-<MM>-<DD>-<hh>-<mm>-<ss>",
  "CreateCSVFilePerDocument": true,
  "NoImageExport": false,
  "NoCSVExport": false
}

SortOrder - Enter here the index field in the order they should be exported. 'Position' is the position of the field within the CSV file. 'Item' is the index field Name. 'FilePath' is the path of the document that is exported.

TIFFOutputFormat - can be multipage or singlepage. If multipage is defined, then one file is exported containing all TIFF files. For other file types (like JPG or PDF) this setting is ignored.

CSVFileName - The name of the CSVFileName, in this case 'TestCSV.csv'.

Delimiter - The character used for separation between fields. In this case a semi-colon ';'.

SubFolderNameTemplate - If specified, each document will be entered into a subfolder with the specified name template.

CreateCSVFilePerDocument - Can be either 'true' or 'false'. If set to 'false', only one CSV file is created and each document record is appended in the CSV file. If the CSV does not exist (e.g. first upload of documents, or if it has been removed from the server), then the file is created automatically. If set to 'true', a CSV file is created for each document.

NoImageExport - Can be either 'true' or 'false'. If set to 'true', no images/documents are exported. If set to 'false', then images/documents are exported.

NoCSVExport - Can be either 'true' or 'false'. If set to 'true' no CSV is exported. If set to 'false', a CSV file is exported. 

XML

The XML export is based on the sample code of the iConnector API. There is no configuration required. The 'Save Name Template' option is not supported.

If you are interested in the XML iConnector Server to be installed on your own servers, you can download it here. For instructions on how to install the XML iConnector Server, follow the section 'iConnector Server Setup'.

To see documents that are uploaded in Europe (with XML (Europe)) goto:

https://iconnector-xml.cumuluspro.net/uploads

To see documents that are uploaded in Asia (with XML (Asia)) goto:

https://iconnector-xml-asia.cumuluspro.net/uploads

SFTP/FTP

The SFTP iConnector exports documents to a SFTP or FTP Server. This SFTP iConnector Server is deployed in the CumulusPro Infrastructure and you can export to any SFTP or FTP server exposed to the internet.

Custom Configuration

On Organisation Level, enter the following Custom Configuration:

{
  "sFTPServer": "ftpservername.com",
  "sFTPPort": 22,
  "sFTPUserID": "username",
  "sFTPPassword": "password",
  "Path": "",
  "MaxRetry": 3,
  "RetryInterval": 5,
  "ZIP": true,
  "TextExportField":"FieldExport",
  "TextFileExtension":"XML" / "CSV" / “TXT”,
  "TextFilename":"<FieldValue>",
  "NoImageExport": true
}

The above JSON Custom Configuration with 'TextExportField' to FieldExport and TextFileExtension to XML results the content of the ‘FieldExport’ metadata export to text file with file extension to XML. Both TextExportField and TextFileExtension parameter are optional parameter.

sFTPServer - The URL of the SFTP server, exluding the path and port. If exporting to FTP, the server name must be specified with the prefix "ftp://" for example "ftp://servername"

sFTPPort - The Port of the SFTP

sFTPUserID - The username of the SFTP user.

Path - Optional, the path of the FTP server teh documetns should be stored

MaxRetry - The maximum retries the iConnector Server takes before reporting an error. The MaxRetry resets after a successful transfer.

RetryInterval - The number of minutes the iConnector waits until retrying to upload the document.

ZIP - Can be either true or false. If set to 'true', the documetns will be delivered in a zip file. If no entry is made for ZIP, ZIP is set to false.

TexExportField - The name of the Text file. The textfile contains the metadata (index fields) of the document.

TextFileExtension - The text file extension to be added. Supported extensions: "XML", "CSV", "TXT".

TextFilename - The filename of the TextFile. Default is blank/optional. If completed, the text file created will be the name specified.

NoImageExport - Can be either true or false. If set to false, documents (images) are exported. If set to true, documents are not exported, only the textfile is exported.

Custom

User 'Custom' if you have created your own iConnector Server. You will need to enter your iConnector URL of your server here. For more information on Installation, visit the iConnector Server Setup section or for creating your own iConnector, visit the API section of this documentation.

Capture and Upload to Straatos

Straatos is CumulusPro's workflow solution. If Straatos is enabled, then the Server URL Option should be selected as 'Straatos'. This means the files are uploaded directly into Straatos workflow.

Once the Server Connector URL is set to Straatos, ensure that the document types are linked to a workflow step. More details on this can be found in the Straatos Tutorial - Getting Started.

The export from Straatos into an iConnector Server is done via a Service Task.

In case you want to export to an iConnector Hosted in your environment, select the Action 'Export to iConnector) from the Action list.

Then select the 'iConnector Export' from the Action List.