Exporting data over API with Confirmed tab

When designing a stable and robust integration workflow, you may have been considering more possibilities on how to integrate Rossum over API with your ERP system. There are more ways to do it with Rossum. In this article, we are introducing an option that proved to be very effective for many users in terms of the integration reliability, easiness while keeping the workflow friendly to the manual operators as well. This option includes the usage of the Confirmed tab to allow the users to correct mistakes made during manual review and the robots go through confirmed documents before exporting them to the ERP.

The article will include Postman examples of the API requests. You can read more about using Postman here.

The Scenario

The scenario introduced in this article is the one where you want to download the extracted data from Rossum, validate it against your ERP system. In case the data were validated correctly, you would finish the workflow by moving such data to the exported state. If there were some validation errors, you will give the human operator the option to review the document again.

Some ERP/AP systems perform validation checks before storing the data. If such a check fails, then you might want to tell the operators to have a look at the document once again within Rossum and correct the existing issues. Therefore, it would be very useful to let the users know about the failed exports.

From Rossum's current experience, the best solution for achieving such workflow would be to:

  1. Download the documents from the Confirmed tab
  2. Try to export the documents to the ERP/AP system
  3. Move the successfully exported documents to the Exported state
  4. Keep the unsuccessfully exported documents in the confirmed state or switch them to the failed_export state where user will see a red error icon on the Exported tab.

The API calls needed for such workflow will be described in the sections below.

Step 1: Downloading data for confirmed documents

Firstly, you will need to download the data captured in the confirmed documents so you could try to export them the the EPR/AP system:

The API request would look like this:

  • call the /v1/queues/<queue_id>/export
  • use GET method
  • select documents in the confirmed state (status=confirmed)
  • choose the output file format (f.e. format=xml)

You would get the captured data in the response as you can see in the image above.

Step 2: Exporting data to the ERP/AP

We assume that once having the captured data, you can try to export them to the ERP/AP system. After the attempt to store the data, the system should return status whether the data was successfully exported or not. Based on such information, you would move the documents in Rossum to the correct status.

Step 3: Move successfully exported documents to the Exported state

The successfully exported documents should be moved to the Exported tab in Rossum. In order to achieve this, the following request should be sent to the Rossum API:

  • call the /v1/queues/<queue_id>/export
  • use POST method
  • select documents in the confirmed state ("status=confirmed")
  • choose the output file format (f.e. "format=xml")
  • move the documents workflow by moving such data to the exported state ("to_status=exported")

As an optimization, you could pass to the request a set of document IDs that should be exported within the single request. Passing the IDs as a parameter would ensure that only the documents which were validated by export checks will be moved to the Exported tab. Or you could just export each document individually. However, this might not be as efficient and would lead to the unnecessary API traffic load.


Do not PATCH the status of confirmed documents to "exported" state

Another way how to move the documents to the "exported" state is to PATCH the status of the annotation, as done in Step 4. However, we highly recommend using the /export endpoint which ensures that the data corrections will be considered for updating the AI Engine capabilities.

Step 4: Marking documents as failed exports in Rossum

Some of the documents might not have been exported successfully to your ERP/AP system. In such a case, you should switch the state of the documents to the failed_export so the user can see that some documents were not processed correctly.

A request for switching the document to the failed_export would look like this:

Afterwards, your users would see the document on the Exported tab marked with a red icon. By clicking on the circle-with-arrow icon the user could move the document back to the To Review tab.

An annotation with a failed_export status.An annotation with a failed_export status.

An annotation with a failed_export status.