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.

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.

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

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

  2. Follow the on-screen instructions.

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

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