How to open documents in Rossum from your own application

When you have your own document management application, you usually want your users to access Rossum only to perform data capture. The rest of the actions, such as document management and other workflows, are managed in your own application. Therefore, the first question you should answer is how you want to manage your users in Rossum. There are two options available.

One Rossum user account for everyone

You have only one Rossum user account, which is used to obtain limited one-time access tokens for each document, regardless of which user is working in your application. This option is easy to set up and integrate.

A new Rossum user account for each user

With this option, you can distinguish who modified the document, which might be necessary for your workflow. For example, you might want to track change logs for security reasons. However, implementing the workflow for creating new users and giving them access to Rossum can be complex.

For both options, Rossum provides the create-embedded-url-for-annotation endpoint, which returns a URL that can be used in a browser iframe or pop-up window. The URL includes a token that is valid only for the specified document, for a limited period, and for the specified user. The view is limited to the Rossum validation screen, where data capture is performed. The user cannot navigate to the standard Rossum document dashboard or settings.

After obtaining the URL, redirect the user to Rossum or show Rossum in an iframe, where the user can perform data capture.

Generating the one-time document URL

The best practice for generating a one-time document token is to create an API endpoint on your own server backend, where you store the credentials of the Rossum user account. Whenever a user clicks the Open document in Rossum button in your application, send a request to your API endpoint. Your endpoint uses the Rossum user credentials to call create-embedded-url-for-annotation. The Rossum document URL is then returned to the user.

Keep this logic in your backend because of browser CORS restrictions. Rossum limits access so the API can be called only from web pages on the same rossum.ai domain. Otherwise, the browser blocks the request to the Rossum API, and you cannot obtain the one-time document token.

This approach prevents users from embedding Rossum credentials directly in the source code of a webpage and enforces higher security.

Opening Rossum in IFrame

You can use an iframe to embed the Rossum validation screen directly in your application. The following HTML is an example:

<html>
<body>

<h1>My own app</h1>

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

</body>
</html>

How to handle different user actions from the Rossum IFrame

You might want to react differently to user actions performed on the Rossum validation screen. Typical examples include:

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

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

• return_url
• delete_url
• postpone_url

To highly customize where the user is taken, you can write your own handler for the URL returned in the iframe.

For example, clicking the confirm button in Rossum could redirect the iframe to https://my-company-application.com/success. The iframe can contain a handler that redirects the user to another document for a smooth workflow. Similarly, you can catch a redirect to https://my-company-application.com/delete and redirect the user to the document detail in your system. You can implement this by using postMessage from the child page to the parent webpage.

For an example, see the custom iframe handling implementation.

Storing the one-time document URLs

When storing document URLs generated by the create-embedded-url-for-annotation endpoint, remember that the URLs have a limited lifetime and expire within 162 hours. Therefore, call the endpoint every time a user wants to open a document in Rossum.

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

Hiding buttons in the Rossum validation screen

You can customize the visibility of these buttons on the Rossum validation screen:

1. The delete icon is shown only if delete_url is provided.
2. The postpone icon is shown if postpone_url is provided.
3. The icon for downloading the original document can be hidden. Contact support@rossum.ai if needed.
4. The editing icon for splitting and rotating documents can be hidden. Contact support@rossum.ai if needed.

Embedding the whole Rossum application into your system

Embedding the entire Rossum application—including the document dashboard, settings, and validation screen—is available only on demand. By default, Rossum supports only the embedded Rossum mode in an iframe. Embedding elis.rossum.ai in an iframe results in an error because the site does not allow framing. Contact support@rossum.ai if you want to embed the entire application. This capability is a paid add-on.