|
Scan2x Web Access Server – Developer Integration (Scan2x API)
High Level Overview
The Developer integration module allows for documents to be uploaded into a Scan2x Web Access Server environment from an external application. This module is only available for environments (and thus licenses) pertaining to Scan2x Web Access Server. A dedicated POST request is made available for unauthenticated access. However, the license needs to be provisioned to allow for Developer Integration module.
.jpg)
Figure 1 - A document file exists within an external application. It is uploaded into Scan2x Web Access Server via the dedicated Dev Integration endpoint. Job and settings are retrieved from the Scan2x database according to parameters specified. The request is validated; in case of any issues, an informative error is returned immediately to the external application. If valid, a scan job is created and queued for processing/saving.
.jpg)
Figure 2 - The Scan2x Web Access Server processing engine picks up the queued scan job from the Scan2x Web Access server queue. It retrieves the relevant job configuration from the Scan2x database. The document is processed according to the initial payload parameters and the job configuration. At the end of processing, the processing engine automatically initiates saving (if autosave is enabled) which uploads the document back into the External app based on the Job’s output configuration.
End-to-end process
The typical usage of Scan2x as a system requires the document to be input via a document scanner or via file upload. However, in some cases, the document would already exist in another system, externally to Scan2x (such as a windows/web application). The process of collecting these documents and uploading them one by one into Scan2x would be manual, tedious and time consuming. The Developer integration module aims to solve this problem by automating the uploading of documents into Scan2x as an integral part of the external application’s workflow.
Scan2x “Jobs” are the basis of document processing and saving in Scan2x. Scan2x boasts an extended set of features, all of which are compatible with the Developer integration module (assuming that the intended feature is an available module within the base license purchased).
Some of these features include:
1.Colour, DPI, and other image settings
2.QR Code / Bar Code / ID Card / Passport validation
3.Post Processing (adding image layers on the document)
4.Metadata
5.OCR (Optical Character Recognition) / OMR (Optical Mark Recognition)
6.ADR (Automatic Document Recognition)
7.Document Splitting
8.Workflows
When using the Developer integration module, a request that uploads the document is linked to a specific Scan2x Job by its “Job_SysRef” (internal ID). A “Username” needs to be specified; and any uploaded documents would appear under this user. It is advisable that a dedicated user is made available for the Developer Integration module for differentiation purposes.
The Initial request can include external metadata; and as such, the Job’s metadata would need to be configured to accept the corresponding field names. The external metadata is usually used to link the output document to the initial request when it is uploaded into the external application*.
The Initial request also includes a parameter “ConvertAndSaveOnly”. This allows the administrator to decide whether Scan2x Web Access Server should take route 1 or route 2.
Route 1 (Default, ConvertAndSaveOnly = false)
Scan2x Web Access Server will download the document, convert it to PDF and pass it through the usual processing flow as configured within the Scan2x Job. In this route, Scan2x will consider all the features^ mentioned above. The job can be configured to “Auto Save” (which is required to enable an automatic flow). The document will be saved according to the Output configuration in the Scan2x job.
Route 2 (ConvertAndSaveOnly = “true”)
Scan2x Web Access server will download the document, convert it to PDF and send it straight to saving (regardless of the “Auto Save” setting in the Scan2x Job configuration). The document will be saved according to the Output configuration in the Scan2x job.
* In typical scenarios, tenants configure the Scan2x Job to upload the document back to the external system via Web Service. The below steps would need to be adhered to:
1.The tenant configures the “Initial” Developer Integration request to include “processID” as one of the metadata fields in the “ExternalMetadata” property of the payload.
2.The tenant configures the “Output” endpoint (which receives the document back) to include “processID” as part of the payload.
3.The Scan2x job is configured to accept “processID” as one of the metadata fields (enabling mapping from point 1).
4.The Scan2x job is configured to send the “processID” as part of the “Webservice” payload parameters (enabling mapping to point 2).
Note:
•Any other metadata generated by the process (such as via OCR) and intended to be sent back to the external web service endpoint would need to be included as part of the payload (for mapping purposes), in the same way as the “processID” described above.
•All other Output configurations available in Scan2x can be considered instead of the Scan to Web Service output configuration. The above is just a single example.
In the initial payload, the file name is included in the “FileName” and a base-64 string representation of the file is included in the “FileBase64”. In cases in which a document is large, it may be split into smaller parts; the base-64 string will be concatenated and created as a file when the “EndOfDocument” boolean is specified as “true”. The “ConnectionId” which would have been returned as part of the first response, would need to be included for any subsequent parts.
There are 3 scenarios whereby documents may be stuck in the queue: if there are any processing/saving errors, if there are any metadata fields marked as mandatory which would not have been filled by saving time, and if the Job is not configured to Auto Save (this can be rectified via Job configuration). To mitigate these cases and ensure that the external app is notified about such problems, the Developer Integration module accepts 2 parameters which are only applicable when the output configuration is set as “Webservice”. SaveToWebServiceOnError and
SaveToWebServiceOnInvalidMetadata will make sure that Scan2x Web Access server still sends the “Output” request at the end of the process, in cases of errors and invalid metadata validation, respectively. In these cases, the payload of the “Output” endpoint needs to accept “ErrorMessage”; a metadata field with the same name needs to also be configured in the Scan2x Job’s Metadata and be included in the Scan2x Webservice output configuration.
Additionally, setting “DiscardScanOnError” as “true” ensures that Scan2x Web Access Server discards the document if an error is encountered during processing or saving. Similarly,
“DiscardScanOnInvalidMetadata” ensures that Scan2x Web Access Server discards the document if it ends up with Invalid metadata or Invalid metadata rules validation. If additionally, the
“SaveToWebServiceOnError” and/or “SaveToWebServiceOnInvalidMetadata” are specified as “true”, the relevant message would be sent to the webservice, before initiating the discard step.
For more detailed information about configuration, kindly refer to the technical documentation section.
Licensing
Tenants desiring to utilise the Developer Integration module are to purchase the basic Scan2x Web Access Server license; minimum 1 Scan2x Unit. Additionally, the Developer Integration module requires purchasing a yearly page limit, which can be topped up on demand.
Technical Documentation
Request Parameters
Job_SysRef (Integer) - Specify the Job SysRef as configured in Scan2x Job. SysRef is the internal ID of the Scan2x Job and can be found in the header of the job in Scan2x Job manager.
Username (String) - Specify a Scan2x Username that has access to the Job_SysRef.
FileBase64 (String: Base64) - Convert the document into a base64 string; and send it as parts. For e.g. 99mb parts. The current default request limit of the ScanWebServer is 4mb. This will be increased to 100mb.
EndOfDocument (Boolean) - Pass this as false, except for the final part of the document. If sent in 1 part, set to true immediately.
FileName (String) - The file name of the included file, including the file extension.
SaveToWebServiceOnError (Boolean) - Pass as true to receive any conversion, processing, or saving error back to the endpoint configured in the "Webservice" section of the "Output settings" tab in Scan2x Job manager. This does not handle invalid metadata scenarios. The converted file will not be included. This is false by default.
DiscardScanOnError (Boolean) - Pass as true to automatically discard the scan if there is an error. The SaveToWebServiceOnError boolean, if set to true, will run before the scan is discarded from the queue. This is false by default.
SaveToWebServiceOnInvalidMetadata (Boolean) - Pass as true to receive an "invalid metadata" error message to the endpoint configured in the "Webservice" section of the "Output settings" tab in Scan2x Job manager. The converted file will not be included. This is false by default.
DiscardScanOnInvalidMetadata (Boolean) - Pass as true to automatically discard the scan if there are any missing mandatory fields or invalid metadata rules. The
SaveToWebServiceOnInvalidMetadata boolean, if set to true, will run before the scan is discarded from the queue. This is false by default.
ExternalMetadata (Dictionary<string, string>) - Specify the metadata to be passed and mapped to the Scan2x Job.
ConnectionId (String) - Send as empty in the first request. It will be generated by the server and returned as part of the first response. Please, specify it for any subsequent parts. If sent in 1 part, leave empty.
Response parameters
ConnectionId (String) - This is created and returned on first request. It is to be specified in every subsequent request
Status (Enum) - 0: Transferring, 1: Processing, 2: Error
ErrorMessage (String) - Any error in the request will be returned here. Note - this does not refer to any processing or saving errors in the Scan2x job execution.
Example Request
Part 1
Endpoint: https://ScanWebServerAPI/api/Scan/CreateScannedDocExternalWS
Sample Request:
{ "Job_SysRef" : 85,
"Username" : "ADMIN",
"FileBase64" : "FIRSTPARTHERE",
"FileName" : "filename.docx",
"EndOfDocument" : false,
"SaveToWebServiceOnError" : true,
"DiscardScanOnError" : true,
"SaveToWebServiceOnInvalidMetadata" : true,
"DiscardScanOnInvalidMetadata" : true,
"ExternalMetadata" : { "regionId" : "MT", "processInstanceId": "123456789", "documentActionId" : "987654321" },
"ConnectionId" : ""
}
Sample Response:
{
"ConnectionId": "ae13385d-b729-4eaa-88b6-762fb289749a",
"Status": 0,
"ErrorMessage": ""
}
Part 2
Endpoint: https://ScanWebServerAPI/api/Scan/CreateScannedDocExternalWS
Sample Request:
{ "Job_SysRef" : 85,
"Username" : "ADMIN",
"FileBase64" : "SECONDPARTHERE",
"FileName" : "filename.docx",
"EndOfDocument" : true,
"SaveToWebServiceOnError" : true,
"DiscardScanOnError" : true,
"SaveToWebServiceOnInvalidMetadata" : true,
"DiscardScanOnInvalidMetadata" : true,
"ExternalMetadata" : { "regionId" : "MT", "processInstanceId": "123456789", "documentActionId" :
"987654321" },
"ConnectionId" : "ae13385d-b729-4eaa-88b6-762fb289749a"
}
Sample Response:
{
"ConnectionId": "ae13385d-b729-4eaa-88b6-762fb289749a",
"Status": 1,
"ErrorMessage": ""
}
|
