Pair Split Annotations with Parent Annotations

Sometimes, it happens that operators receive a document with multiple invoices. For each of these invoices, the data should be extracted separately. Using the editor feature, the operator can split the document accordingly in the UI.

When a document is split, new annotations are created and sent to the importing status. While convenient for a user, this behavior may be problematic for integrations with third-party systems. Luckily, there is a way to find a link between the original and new annotations or prevent users from splitting the document if this action is not desired within your integration process.

Pair split annotations with the original annotation

If your workflow allows or even encourages users to split annotations that contain multiple invoices, you can easily pair the original (parent) annotation with its newly created children via API. You can do this in two steps:

1. Getting the information about the split - get an annotation (or all annotations) in the split state.
2. Finding more information about the split results - use the annotation ID to find more details (annotation status, etc.) about children annotations.

You can use the combination of a webhook object (to get the notification about splitting events) and API calls (to retrieve additional information about the split results). Or you can substitute the webhook with periodical polling of annotations.

If you are using a webhook, assign the hook that listens on annotation_status.changed event to your queue. After a document is split, you will receive a notification for the original (parent) annotation to this hook, where annotation.status value will be “split”.

When you receive the notification, take the annotation ID and use it to find children annotations. You may also use other filters to eliminate the number of results in the response and allow easier processing. So the final endpoint can look like this: https://example.rossum.app/api/v1/annotations?relationsparent={ANNOTATION_ID}&relationstype=edit&queue={QUEUE_ID}
Under the results key, you will find all the children annotations that were created from the originally split annotation object.

If you are not using hooks, you may periodically call GET to get annotation objects with split _status and sideloaded relations objects. Similarly to the previous scenario, you may also use other filters to lower the amounts of requests that you need to do. The request would look like this:
https://api.elis.rossum.ai/v1/annotations?status=split&relations__type=edit&queue={QUEUE_ID}&sideload=relations
This way, you can find the newly created children annotations in the _relations.annotations array.

Suppose you would like to find the statuses of the children annotation. In that case, you can get them in a single request by aggregating all the children ID: https://example.rossum.app/api/v1/annotations&id=2974841,2974841.

Or you can get the children annotations of a specific parent by executing:: https://example.rossum.app/api/v1/annotations?t&relationsparent={ANNOTATION_ID}&relationstype=edit&queue={QUEUE_ID}

This way, you can find the newly created children annotations in the _relations _array.

Splitting in embedded mode

Suppose the user splits the document via UI. In that case, they will be redirected to return_url when they press the Confirm button in the editor.
If the user only rotates the annotation or removes some pages, they will be kept in the embedded mode, seeing that the current document is being processed. Once the document processing is finished, the user can continue annotating in the same window.

Disable splitting

If you want to disable the splitting feature completely, contact Rossum at [email protected] to disable this feature for you.