Embedded Mode

In some use-cases, it is desirable to use only the per-annotation validation view of the Rossum application. Rossum may be integrated with other systems using so-called embedded mode.

In embedded mode, special URL is constructed and then used in iframe or popup browser window to show Rossum annotation view. Some view navigation widgets are hidden (such as home, postpone and delete buttons), so that user is only allowed to update and confirm all field values.

Embedded mode can be used to view annotations only in status to_review, reviewing, postponed, or confirmed.

For security reasons it is strongly recommended to use annotator_embedded user role for this feature as this user role has limited permissions to only be able to interact with resources necessary for embedded validation screen.

Embedded mode workflow

The host application first uploads a document using standard Rossum API. During this process, an annotation object is created. It is possible to obtain a status of the annotation object and wait for the status to become to_review (ready for checking) using annotation endpoint.

As soon as importing of the annotation object has finished, an authenticated user may call start_embedded endpoint to obtain a URL that is to be included in iframe or popup browser window of the host application. Parameters of the call are return_url and cancel_url that are used to redirect to in a browser when user finishes the annotation.

The URL contains security token that is used by embedded Rossum application to access Rossum API. When the checking of the document has finished, user clicks on done button and host application is notified about finished annotation through save endpoint of the connector HTTP API. By default, this call is made asynchronously, which causes a lag (up to a few seconds) between the click on done button and the call to save endpoint. However, it is possible to switch the calls to synchronous mode by switching the connector asynchronous toggle to false (see connector for reference).