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

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:

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
  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 to avoid unexpected changes to the API token.

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

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:

Example of the init function:

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

Example of the destroy function:

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

Additional notes