Embedding Rossum in IFrame: Best Practices

There are several best practices you should know about when embedding the Rossum validation screen into your application.

How to open documents in Rossum from your own application

In most cases when you have your own document management application, you want your users to access Rossum only for performing data capture. The rest of actions such as document management and other workflows are managed in your own application. Therefore, the first question you should answer yourself is - how would you like to manage your users in Rossum? There are two options available.

One Rossum user account for everyone
You would have only one Rossum user account that is used for getting limited one-time access tokens for each of the document, no matter what user is working right now in your application. This options is easy to setup and integrate.

Have new Rossum user account for each of your users
With this option you will be able to distinguish the modifiers of the document which might be necessary in your workflow. For example if you would like to track change logs for security reasons. However, setting up the workflow for creating the new users and letting them access Rossum might be quite complex to implement.

For both options, we have created an endpoint create-embedded-url-for-annotation that will return a url that can be used in the browser iframe/popup window. The URL includes a token that is valid only for this document, only for a limited period of time and only for this user. Moreover, this view is limited only for the Rossum's validation screen where the data capture is performed. The user cannot navigate to the Rossum standard document dashboard or settings.

After getting the url you would redirect the user to Rossum (or show IFrame) where the user can perform the data capture.

Generating the One-Time document URL

The best practice for generating the one-time document token is to create own API endpoint on your server backend where you would store the credentials of the Rossum user account. Anytime a user would click on button "Open document in Rossum" in your own application you would send a request to your API endpoint that would take the Rossum user credentials and call the create-embedded-url-for-annotation. Afterwards, the Rossum document URL would be returned to your user.

The reason why it is good to have this in your backend is because of the CORS restrictions in browsers. Rossum is limiting access to its API "api.elis.rossum.ai" so that the API can be called only from web pages that are on the same "rossum.ai" domain. If not, the browser would block the request to the Rossum's API and you will not be able to get the one-time document token.

Such Rossum's approach prevents users from embedding the Rossum credentials directly in the source code of the webpage and enforces higher security.

Opening Rossum in IFrame

If you would like to embed Rossum's validation screen directly in your application you can use the IFrame object. You can see an example of the HTML snippet below.


<h1>My own app</h1>

<iframe iframe src="https://embedded.elis.rossum.ai/document/2707700#authToken=00c7ce2f7f0f8ebf91f80b9e22ca204eb0e22b3b" style="width: 1280px; height: 800px"/>


How to handle different user actions from the Rossum's IFrame

You might want to react differently to user actions performed in the Rossum's validations screen. A typical example would be that you would like to:

  • Take user to your own document detail after deleting document in Rossum
  • Take user to your own document detail after postponing the document
  • Take user to another document in Rossum after clicking on the confirm button.

In Rossum you can define where the user is taken after each user action in Rossum by specifying special parameters of the create-embedded-url-for-annotation:

  • return_url
  • delete_url
  • postpone_url

If you would like to highly customize the logic where the user is taken, you can write your own handler of the returned URL in the IFrame.

In other words, clicking on the confirm button in Rossum could redirect user to "https://my-company-application.com/success" in the IFrame. The IFrame would contain a handler that could redirect user to a new document in order to make the workflow perfectly smooth. Or you would catch "https://my-company-application.com/delete" action and redirect the user to a detail of the document in your system by using the postMessage from the child page to the parent webpage.

You can get inspired about the implementation of the custom Iframe handling here.

Storing the one-time document URLs

When storing the document URLs generated by the create-embedded-url-for-annotation endpoint, keep in mind that the URLs have limited lifetime and that the link will expire in up to 162 hours. Therefore, you should call the create-embedded-url-for-annotation endpoint every time the user wants to open the document in Rossum.

Using the create-embedded-url-for-annotation endpoint can show documents in all Rossum states such as "reviewing", "exported" or "deleted".

Hiding buttons in Rossum's validation screen

The visibility of the following buttons can be customized in the Rossum validation screen:

  1. Delete icon is shown only if the delete_url is provided
  2. Postpone icon is shown if the postpone_url is provided
  3. Downloading original document icon can be hidden if needed. Contact [email protected] if needed.
  4. Editing icon for splitting and rotating documents can be hidden if needed. Contact [email protected] if needed.

Embedding the whole Rossum application into your system

Embedding the whole Rossum application, i.e. the document dashboard, settings and validation screen can be done only on demand. By default Rossum supports only the embedded Rossum mode in IFrame. Embedding of the "elis.rossum.ai" into IFrame would result into error since it does not allow IFraming. Contact us at [email protected] if you would like to embed the whole app. However, keep in mind that this is a paid add-on.

Standard Rossum app cannot be put into IFrame.Standard Rossum app cannot be put into IFrame.

Standard Rossum app cannot be put into IFrame.

Error seen when trying to embedded the whole app by default.Error seen when trying to embedded the whole app by default.

Error seen when trying to embedded the whole app by default.