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:

• Supervision:

  • Document Classification

  • Identification

  • Transcription

  • Flexible Extraction

  • Custom Supervision

• QA:

  • Document Classification

  • Identification

  • Transcription

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

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.

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.

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:

• The widget’s min-width property is 1000px.

• The widget’s min-height property is 700px.

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

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:

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

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

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