IDP Integration API (2.1)

Scenario 1: Masterdata & validation

To upload masterdata files, or validate their content, use corresponding method from the idp-masterdata group.

Note: Masterdata upload is a 2 step process. Successful response from any upload API call should be interpreted as a valid request to a masterdata upload. Actual lookup storage import is done asynchronously.

Scenario 2: Process document – get result using polling method

Prerequisite for this process is to have a published preset with which we want to process the document.

1. To start document processing use one of methods from the idp-import group, depending on the input document type (pdf, png, tiff, jpeg)

   In a response to any of these methods, if document upload is successful, system will respond with process UUID assigned to uploaded document. Subsequently, obtained UUID can be used as an input parameter in the next step.

2. Get-status from the idp-process group

   Provides document processing status. Get-status method returns a JSON payload with the status and last activity timestamp. Possible statuses are available in the method description. Both EXPORTED and REJECTED status are final statues and once process reaches one of those two states, no more processing is performed. If a process ended up in the EXPORTED state, processing result is available and one can proceed with the next step.

3. Get-xml-result from the idp-process group can be used to download XML file with the results of processing.

   To fetch the resulting XML, the client needs to provide IDP process UUID. In this scenario it is expected of client to store process UUID within its own datastore and use it to periodically check processing status. (polling get-status method)

Scenario 3: Process document – get result using push method

This scenario omits Get-status method and relies on the status push functionality to notify client system that processing has completed. Push functionality is configured on a pipeline level and can be combined with the pull method as well. This scenario begins with one of upload methods and, after the processing is completed, IDP will send status push notification. At this point the client can use Get-xml-result method to download resulting XML.

Scenario 4: Process document – use IDP as a solution state store

Scenario 2, and to some extent Scenario 3, require management of the overall document processing state (was it processed by IDP and subsequently the result was downloaded). In the Scenario 4, IDP keeps information about downstream processing status (result processed status) communicated to the system through the acknowledge-result-processed endpoint. Standard workflow in this scenario has the following steps:

1. Start document processing within IDP using one of the existing upload methods, but ignore assigned process UUID. (fire and forget upload)
2. Upload client is expected to periodically poll get-process-list from the process-administration-controller group to fetch a list of documents in an EXPORTED / REJECTED status with result processing not been acknowledged yet.
3. Process results obtained in 2. are then downloaded using get-xml-result endpoint if the processing status is EXPORTED. If the status is REJECTED there is no artifact for download.
4. Acknowledge result processing.

Note 1: Irrespective of the process result, if a process reaches one of the final states, get-document-pdf endpoint from the idp-process group can be used for obtaining input document pdf.

Note 2: Endpoint acknowledge-result-processed from the group idp-process must be called upon finishing steps for any of the scenarios 2-4. This call signalizes to the IDP system formal closure of the process and is used in IDP internally to appropriately handle such processes.