Find here answers to some common question around the iConnector development and implementation. If you have questions to the API, please contact us via email at enquiry@cumuluspro.com.
- Is there a reason why the document metadata and the document image are being sent in two or more separate HTTP transactions (TXs)? The reason why I’m asking is because this puts a burden on the developer (me in this case J ) to store the metadata for a document using its configurationUniqueId (GUID) and then wait until the document contents arrive.
Answer: Sending the files separately in UploadDocument requests allows for streaming each file as binary without much overhead. It keeps the basic API simple to implement in all languages / environments. Also, e.g. in Straatos we use several threads to pre-process the document (pages) as soon as they come in. In that case the state is kept in one of our databases, which keeps the server stateless and enables scaling out.
- Given that networks are unstable (connectivity can be lost) and upredictable (HTTP requests can be reordered in flight), do I have to deal with the following failure cases?
A) Metadata TX arriving first, bud document TXs never arriving (or arriving very late)
B) Document TXs arriving first, but metadata TXs never arriving/arrive very late
C) Some TXs arrive first, but the web service detects an error while processing the TXs; then other TXs that were "in flight" arrive later
D) All TXs arrive and downstream system fails during the final processing of the collected TXs
Answer: Scenario A) and B) will never happen, the UploadMetadata is always called/completed before any UploadDocument is Started. If only temporary problems occur (e.g. network related) and all documents acan be re-sent, it is not necessary to cleanup after a timeout. Just for clarification, as teh client(s) currently send UploadMetadata / UploadDocuments(s) sequentially and in order, the fransfer is complete once the following condition holds in UploadDocument (as shown in the reference implementation):if ((!isJPG && !isOtherFiles) || numberOfPages == pageNumber)How can the iConnector server notify the originator app (ScanApp, Mobile Capture or Straatos) that something went wrong?
Answer: As HTTP is using TCP, no transfer should have gone ‘missing’ / there should always have been an error on both sides, so there should never be a situation where the receiver is missing DocumentUpload calls and the sender has the notion that it has been delivered. We should either get an HTTP 2XX (ok) / 4XX / 5XX (not ok) from the code and / or server or a timeout (which is normally configured around 10 minutes max). If an error / timeout occurred, Straatos will keep the document in the workflow step together with the error message.
If multiple documents were scanned, will they have separate GUIDs or will they be given a shared GUID? If the latter, am I correct that our server will have to track the X-Number-Of-Pages and X-Page-Number headers of the incoming documents in order to know when all documents have arrived? Naturally we won’t assume that the TXs arrive in order.
Answer: Yes, one UploadMetadata is followed by one or more UploadDocument calls. In the case of a multi-page format this is only one UploadDocument call. In the case of a single page format (JPG), there will be one UploadDocument for each page. Currently, the client(s) send the pages in order, but it would be better to use the X-Page-Number to determine the sort order.