# Embedded Supervision Widget (Beta)

- Published on Sep 24, 2025

- 5 minute(s) read

The Supervision widget enables you to embed our Supervision & QA tasks within a third-party workflow system. Thus, you no longer have to switch between Hyperscience and your existing workflow system to complete tasks.

Our Supervision widget supports the following types of tasks:

- **Supervision:**
  - Document Classification
  - Identification
  - Transcription
  - Flexible Extraction
  - Custom Supervision
- **QA:**
  - Document Classification
  - Identification
  - Transcription

> **Not supported for SaaS instances**  
> The Supervision widget is available only for on-premise / private cloud instances of Hyperscience.

Note that the Supervision widget feature is in beta, and it is subject to change in future releases. If you’d like to embed a Supervision widget into your third-party system, contact your Hyperscience representative for more information.

The Supervision widget also supports Custom Supervision tasks. To learn more about Custom Supervision, see [Custom Supervision](https://help.hyperscience.ai/v42/docs/custom-supervision).

## Embedding a Supervision widget

You can embed a Supervision widget by following the below steps:

1. **Get access to a Hyperscience instance**.

To embed the Supervision widget into a third-party system, you need to get access to a Hyperscience instance installed on version 32+.

2. **Create a method for accessing our API tokens**.

Users are authenticated in the widget, using their API token. To get the API token, we recommend querying the _/profile/user//token_ endpoint on your server. You can then forward the obtained API token to the frontend that implements the widget.

#### Step 2a: Set the _ALLOWED
_ORIGINS_ variable
   Ask your system admin to do the following, and then restart and reinitialize the Hyperscience application:

In the “.env” file, set the _ALLOWED_ORIGINS_ variable to include the domains of where you will embed the Supervision widget:

```plaintext
   ALLOWED_ORIGINS=https://example.com
   ```

#### Step 2b: Create a superuser
   To access the API token endpoint, you have to create a _superuser_. To create a superuser:

1. Run the following command.
   
   ```powershell
   docker exec -it /var/www/venv/bin/python /var/www/forms/forms/manage.py createsuperuser
   ```
   
   Note that you can run Docker commands on Podman with the _podman-docker_ package. To learn how to install the _podman-docker_ package, see step 2 in [Configuring Podman in RHEL 8](https://help.hyperscience.ai/deployment/docs/configuring-podman-in-rhel-8#configuring-podman).

2. Follow the on-screen instructions.
   3. Open the Hyperscience application.
   4. Go to **Users > Users**.
   5. Click on the superuser’s username.
   6. Copy the superuser’s authentication token.

We recommend adding the superuser’s username to the _TOKEN_REVALIDATION_EXEMPTED_USERS_ variable in the “.env” file. Thus, you will avoid unexpected changes to the API token. To learn more, see [External Authentication Methods and API Users](https://help.hyperscience.ai/deployment/docs/external-authentication-methods-and-api-users).

#### Step 2c: Create a new endpoint to return the current user’s API token, if necessary
   Depending on whether your server sends user data to your third-party system, you may need to create an endpoint that returns the user's token.
   
   | **If...** | **Then...** |
   |------------------ |---------------------------------------------------------- |
   | Your server sends user data to your third-party system. | You can add the users’ API tokens to the relevant entity in the third-party system. |
   | Your server does not send user data to your third-party system. | You need to create a new endpoint that returns the user’s API token. |
   
   Here is an example of how to create a new endpoint in the backend that returns the user’s API token:
   
   ```http
   @app.route('/hyperscience/user-token', methods=['GET'])
   def get_user_api_token():
       # get request user. Ex:
       username = request.user.username
       username = quote(username, safe='~()*!.')
       res = requests.get(
           f'https:///profile/user/{username}/token',
           headers = { 'Authorization': f'Bearer {SUPERUSER_API_TOKEN}'}
       )
       return res.text
   ```

3. **Import the Supervision widget into your third-party system**.

Import the widget’s JavaScript and CSS to the frontend:

```javascript
   <link rel="stylesheet" href="https://<HS Instance>/static/widget/main.css">
   <script src="https://<HS Instance>/static/widget/main.js" type="text/javascript"></script>
   ```

Add a container for the widget. You must set the container’s _position_ property to _relative_:

```css
   <div id="hs-1" style="position:relative;"></div>
   ```

Initialize the widget in JavaScript:
   
   ```javascript
   <script type="text/javascript">
     fetch('https://<Server>/hyperscience/user-token')
       .then(res => res.text())
       .then((apiToken) => {
         HyperscienceWidget.init('hs-1', {
           url: 'https://<HS Instance>,
           api_token: apiToken,
           <widget_options>
         });
       });
   </script>
   ```

Note the following about the widget:
   - The widget’s _min-width_ property is 1000px.
   - The widget’s _min-height_ property is 700px.

4. **Configure the widget**.

After importing the widget, _window.HyperscienceWidget_ will become available. The following functions are available in _window.HyperscienceWidget_:
   - _Purpose_
   - _MessageType_
   - _init_
   - _destroy_

#### Purpose
   _Purpose_ is an enum of task purposes.
   
   ```java
   enum Purpose {
     DOCUMENT_CLASSIFICATION = 'document_classification',
     IDENTIFICATION = 'identification',
     TRANSCRIPTION = 'transcription',
     FLEXIBLE_EXTRACTION = 'flexible_extraction',
     CUSTOM_SUPERVISION = 'custom_supervision',
     DOCUMENT_CLASSIFICATION_QA = 'document_classification_qa',
     IDENTIFICATION_QA = 'identification_qa',
     TRANSCRIPTION_QA = 'transcription_qa',
   }
   ```

#### MessageType
   _MessageType_ is an enum of message types for the callback function.
   
   ```java
   enum MessageType {
     ERROR = 'error',
     COMPLETE = 'complete',
   }
   ```

#### init(id, options)
   _init_ is a function that initializes the widget to an HTML element. The parameters of the _init_ function are the following:
   - Element ID: string
   - Options: object  
     - url: string  
       URL of the Hyperscience instance  
     - api_token: string  
       User’s API Token  
     - callback: (message_type: MessageType, info: object) => void _(optional)_  
       The callback is currently called for two different events:
       - Errors - when the widget hits an error, the callback will be called with _message_type === MessageType.ERROR_ and info will be an Error object.
       - Completed tasks - when all tasks are complete, the callback will be called with _message_type === MessageType.COMPLETE_, and _info_ is an object with _Purpose_ types as keys and the corresponding number of completed tasks as values.
     - One of the following parameters:
       - submission_id: string | number
         To complete tasks for a given submission ID.
       - document_id: string | number
         To complete tasks for a given document ID.
       - case_id: string | number
         To complete tasks for a given case ID.
       - task_uuid: string
         To complete a specific task.
       - purposes: Array
         To complete tasks for specific task purposes.

You can find an example of the _init_ function below:
   
   ```javascript
   <script type="text/javascript">
     const hyperscienceCallback = (message_type, info) => {
       if (message_type === HyperscienceWidget.MessageType.ERROR) {
         console.error(info.message);
       } else if (message_type === HyperscienceWidget.MessageType.COMPLETE) {
         console.log('Tasks Completed', info);
         HyperscienceWidget.destroy('hs-1');
       }
     };
     HyperscienceWidget.init('hs-1', {
       url: 'https://<HS Instance>',
       api_token: '12345678910',
       submission_id: 10,
       callback: hyperscienceCallback,
     });
   </script>
   ```

#### destroy(id)
   _destroy_ is a function that destroys the widget in an HTML element. The parameters of the _destroy_ function are the following:
   - HTML element ID

You can find an example of the _destroy_ function below:
   
   ```javascript
   <script type="text/javascript">
     HyperscienceWidget.destroy('hs-1');
   </script>
   ```

## Additional notes

- Upon first login, the system automatically creates and assigns an API token to the user who is logging in. To be able to log in through the Supervision widget, a user needs to have logged in at least once to the main Hyperscience application. All subsequent logins can happen through the widget, using the user’s API token.