Embedded Supervision Widget (Beta)

Embedded Supervision Widget (Beta)

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.

Supported Tasks

Our Supervision widget supports the following types of tasks:

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.

Embedding a Supervision widget

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

  1. Get access to a Hyperscience instance.
  2. Create a method for accessing our API tokens.
  3. Import the Supervision widget into your third-party system.
  4. Configure the widget.

Step 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+.

Step 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:

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.
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.

  1. Follow the on-screen instructions.
  2. Open the Hyperscience application.
  3. Go to Users > Users.
  4. Click on the superuser’s username.
  5. 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.

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:

@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

Step 3: Import the Supervision widget into your third-party system

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

<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:

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

Initialize the widget in 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:

Step 4: Configure the widget

After importing the widget, window.HyperscienceWidget will become available. The following functions are available in window.HyperscienceWidget:

Purpose

Purpose is an enum of task purposes.

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.

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:

You can find an example of the init function below:

<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:

You can find an example of the destroy function below:

<script type="text/javascript">
  HyperscienceWidget.destroy('hs-1');
</script>

Additional notes