Toolbar Widgets

The conneQt Toolbar can display one or more widgets to end users, expanding their functionality beyond what's available in their native patient administration system (PAS). Widgets are individual control items on the conneQt Toolbar, enabling end users to access system functionality. While some of these functionalities are directly related to patient care, others support staff members in clinical organisations.

Every toolbar widget that has been registered is linked to one or more end-user organisations, where Toolbar users within these organisation shall see available widgets on their personal toolbar.

Quicksilva Toolbar

When a new widget becomes available to end-user organisations, it will appear on the toolbar for all users. However, each user can choose to toggle the display of widgets based on their job role. Since your widget is associated with a clinical organisation, some users may opt to display only a subset of available widgets.

Widget Registration

Your widget must be registered before it can appear on the conneQt Toolbar. Registration provides the Toolbar with access information and specifies the necessary data for your widget's proper functioning.

Prerequisites

To register your widget with the conneQt Toolbar, you need the following information in advance:

  • Display name for your widget, visible to Toolbar users.
  • Icon selection - for more details see - Widget Icons.
  • Secure HTTPS URL of your system for the Toolbar to launch.
  • Encryption string for data sent to your widget - Encryption secret.
  • Indication of whether your widget requires data about the current Toolbar user.
  • Indication of whether your widget requires data about the current patient (subject) in the local PAS of the user.
  • Optional: Encryption method preference for data sent to your widget.

For more information on how data is securely sent from the conneQt Toolbar to your widget, see Communicating with Approved Widgets

Note

A widget requesting patient data must also request user data. Requests registering for patient data without user data will be rejected by the Toolbar.

Step 1: Encryption secret

The encryption secret is a string used by the Toolbar to securely communicate with your widget, ensuring data privacy. This secret is employed to encrypt all tokens sent from the Toolbar to your widget, limiting access to your widget alone.

Your system must provide this encryption secret during widget registration, and your widget can use it to access user or subject tokens as needed. It is your system's responsibility to store this secret securely.

You can either create a 32-character UTF-8 encryption secret yourself or use the provided PowerShell script for generation:

# Define the length of the encryption secret string
$length = 32

# Create an array to store the valid characters we want to include
$validCharacters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"

# Create an array to store the random bytes
$randomBytes = New-Object byte[] $length

# Create a cryptographically secure random number generator
$cryptoProvider = New-Object System.Security.Cryptography.RNGCryptoServiceProvider

# Generate random bytes
$cryptoProvider.GetBytes($randomBytes)

# Initialize a StringBuilder to store the resulting alphanumeric string
$randomStringBuilder = New-Object System.Text.StringBuilder

# Loop through the random bytes and convert them to characters from the valid characters array
foreach ($byte in $randomBytes) {
    $randomIndex = [math]::Floor($byte % $validCharacters.Length)
    $randomChar = $validCharacters[$randomIndex]
    [void]$randomStringBuilder.Append($randomChar)
}

# Convert the StringBuilder to a string
$randomString = $randomStringBuilder.ToString()

# Output the random alphanumeric string
Write-Host "Encryption Secret String: $randomString"

After generating an encryption secret, your system should store this for future registration and decryption.

Step 2: Registering your widget with the conneQt Toolbar

Once you have prepared all of the prerequisites, you can use this information to register your widget with the conneQt Toolbar.

This is achieved by an API call made from your system to the Toolbar containing the information detailed above.

Registration for Integration

Please fill in the appropriate placeholders:

  • API_KEY - the API key which will have been sent to you by a member of the Quicksilva team.
  • WIDGET_NAME - the name of your application.
  • WIDGET_ICON - the image that will appear on the Toolbar for your widget, for more details see - Widget Icons.
  • YOUR_APP_LAUNCH_URL - the launch URL of your application.
  • ENCRYPTION_SECRET - the encryption string for data sent to your widget, for more details see - Encryption secret.
POST https://int.conneqt.health/api/v1/widgets HTTP/1.1
Content-Type: application/json; charset=utf-8
ApiKey: <API_KEY>

{
  "name": "<WIDGET_NAME>",
  "icon": "<WIDGET_ICON>",
  "launchUrl": "<YOUR_APP_LAUNCH_URL>",
  "encryptionSecret": "<ENCRYPTION_SECRET>",
  "requiresUserData": true,
  "requiresPatientData": true
}

Registration for Live

Please fill in the appropriate placeholders:

  • API_KEY - the API key which will have been sent to you by a member of the Quicksilva team.
  • WIDGET_NAME - the name of your application.
  • WIDGET_ICON - the image that will appear on the Toolbar for your widget, for more details see - Widget Icons.
  • YOUR_APP_LAUNCH_URL - the launch URL of your application.
  • ENCRYPTION_SECRET - the encryption string for data sent to your widget, for more details see - Encryption secret.
POST https://live.conneqt.health/api/v1/widgets HTTP/1.1
Content-Type: application/json; charset=utf-8
ApiKey: <API_KEY>

{
  "name": "<WIDGET_NAME>",
  "icon": "<WIDGET_ICON>",
  "launchUrl": "<YOUR_APP_LAUNCH_URL>",
  "encryptionSecret": "<ENCRYPTION_SECRET>",
  "requiresUserData": true,
  "requiresPatientData": true
}

This API call is outlined more thoroughly in Register Widget.

Upon a successful registration API call, your widget will undergo a review by Quicksilva to confirm the accuracy of the provided details. Please Contact Quicksilva directly to inform us of your request. Once the review is complete, your widget will be linked to one or more end user organisations within the Toolbar as needed.

Details of how the Toolbar will interact with your widget, once approved, are outlined in Communicating with Approved Widgets.

Note

During this review process, the encryption key provided by your system through the API call will never be available to Quicksilva team members.

Note

By default, you will only be able to create and register a maximum of 5 widgets on the Toolbar. If more are required then please get in touch with our sales team to discuss the options and pricing available to you.

Widget Identification

All widgets in your client system are associated with an API key for authentication in API requests. Each widget must have a unique name. If a duplicate name is used in a registration request, it updates the existing widget with the new details, rather than creating a new registration.

Widget name comparisons are case-insensitive, and leading/trailing spaces are ignored. For instance, "Widget-1," "widget-1," and " WIDGET-1 " are considered identical.

Widget names can only include letters, numbers, spaces, hyphens, and underscores. Requests with other characters in the widget name field will be rejected.

Widget Integration

When developing a custom widget, you need to create an HTTP endpoint to serve web-based content to end users. During widget registration, specify the URL that should load when a user selects your widget in the Toolbar's desktop client.

When a user selects your widget, the Toolbar triggers a web request to this URL, opening it in their local PC's web browser.

The Toolbar can include data in the URL, such as user and patient information from the local PAS, if your system requests it during widget registration. If requested, this data is securely sent as signed and encrypted JWTs, included as query string parameters in the launch URL of your system.

For more information on the JWTs created by the toolbar, please see Communicating with Approved Widgets.

Widget Icons

The Toolbar currently supports the use of Bootstrap Icons for widget icons.

Custom Widget Icons

If you would like to use a custom icon for your widget, please submit your widget request as per the instructions above. You must submit this request first.

Then contact Quicksilva via email and attach your custom icon(s): Email Support

Custom icon requirements:

  • Maximum size: 20 x 20px.
  • Be in one of these formats: png/bmp/jpg/jpeg.
  • The name of each icon and which widget it is for.

The Quicksilva support team will then apply the custom icon to the appropriate widget.

Note

As part of onboarding, all custom icons will be subject to review by Quicksilva.

OpenAPI 2.0 Specification

An OpenAPI 2.0 (Swagger) format specification for this API can be downloaded using the following link:

Widget Registration OpenAPI Specification

Reading JWTs received from conneQt

See Communicating with Approved Widgets for comprehensive information on the JWTs sent by conneQt to your web application, and refer to Decrypting and Reading Claims from a JWT for a detailed code walkthrough on JWT decryption

See Also