Constellio External Document Viewer

Introduction

Constellio's external document viewer allows your users to view documents directly in their browser via an iframe. Access to the viewer URL is secured through OAuth, requiring the creation of an OAuth application and obtaining a JWT access token.

Key features

1. Document consultation :

   • Supports many formats, including PDF, images, and Office documents.

2. Dynamic URL generation :

   • An API provides a URL that is ready to be used in an iframe.

3. Securing via OAuth :

   • Access is protected by a secure authentication process with JWT tokens.

Configuration

Initial steps (to be completed once)

1. Generate a token for the OAuth API

To create an OAuth app, you must have a valid token. You can generate this token using the following API:

Endpoint :

GET https://{domaine}/constellio/generateToken?username={username}&password={password}

Parameters :

• {username} : Valid username in Constellio.

• {password} : The password associated with the user.

Answer : If the API returns an XML response, here is an example of the expected format:

<response>    <serviceKey>abcd1234-ef56-7890-ab12-cd34567890ef</serviceKey>    <token>12345678-abcd-90ef-1234-567890abcdef</token> </response>

Keep this token to authenticate your request when creating the OAuth app.

2. Create an OAuth app

Endpoint :

POST https://{domaine}/constellio/oauth/v2/credentials?applicationName={applicationName}&client_type=CONFIDENTIAL&scope=all

Required Headers :

Authorization: Bearer {token}

Answer :

{    "client_id": "votre-client-id",    "client_secret": "votre-client-secret" }

Keep this information to generate a JWT token.

Regular steps (after initial setup)

3. Generate a JWT token

Endpoint :

POST https://{domaine}/constellio/oauth/v2/token

Payload :

{    "grant_type": "password",    "client_id": "votre-client-id",    "client_secret": "votre-client-secret",    "username": "votre-nom-d'utilisateur",    "password": "votre-mot-de-passe" }

Note: Data must be submitted in a x-www-form-urlencoded.

Answer :

{    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",    "token_type": "Bearer",    "expires_in": 3600,    "refresh_token": "d41d8cd98f00b204e9800998ecf8427e" }

Keep it access_token to call the viewer API.

4. Generate the viewer URL

Endpoint :

GET https://{domaine}/constellio/api/v2/documents/{documentId}/viewer

Dynamic settings :

• {domaine} : Domain of your Constellio instance.

• {documentId} : Unique identifier of the document to be consulted.

Required Headers :

Authorization: Bearer {access_token}

Answer : A direct URL, ready to use.

Example :

https://{domaine}/viewer/{documentId}?token={singleUseToken}&mimeType={documentMimeType}&documentTitle={documentTitle}

Generated URL Details

Structure :

https://{domaine}/viewer/{documentId}?token={singleUseToken}&mimeType={documentMimeType}&documentTitle={documentTitle}

Parameters:

1. {domaine} : Domain of the Constellio instance (e.g. https://moninstance.constellio.com).

2. {documentId} : Unique identifier of the document.

3. token : A one-time JWT token used to retrieve binary content.

4. mimeType : The MIME type of the document (e.g. application/pdf, image/jpeg).

5. documentTitle : Readable title of the document displayed in the viewer (e.g. Contrat_Client.pdf).

Configuring the Viewer App

The visualization application is provided as a Docker image. To configure it, it is necessary to define certain environment variables:

• CONSTELLIO_BASE_URL : The base URL of the Constellio instance (for example: https://moninstance.constellio.com).

These variables must be configured at deployment time to allow the application to communicate successfully with the Constellio instance.

Example of integration with iframe

<iframe
    src="https://moninstance.constellio.com/viewer/12345?token=eyJhbGciOiJIUzI1NiIsInR...&mimeType=application/pdf&documentTitle=Contrat_Client.pdf"
    width="100%"
    height="800px"
    frameborder="0"> </iframe>