Event Notifications

Table of contents

1. Overview
2. Registering a Listener
3. Subscribing to your SNS Topic
4. Notification Types
5. Message Structure for Single Notifications
6. Base notification fields
7. Examples of Additional Information or Special Cases
8. Enabling "Changed Data in SNS Notification"
9. Enabling Bulk SNS Messages

 

Overview

---

QBench provides API users the ability to take action based on an event that occurs in the application. Third party applications can listen for events such as a sample being updated to programmatically fetch or update data. There are endless possibilities for how this functionality can be used, below are only a few basic examples:

• Fetch data about an order to prepare and invoice for downstream accounting systems.
• Listen for a test being completed to fetch result data to perform analysis
• Listen for tests being completed to render a complex report using third party software and reattach the report
• Aggregate data for report or emailing business metrics
• Many, many, more

This guide describes the underlying architecture, how to register a listener, the notification structure, and the event types.

Built on Amazon’s Simple Notification Service (SNS)

---

The QBench notifications API uses AWS Simple NotificationService (SNS) to send notifications to listeners. SNS already offers various options to bind listeners of which QBench supports two: HTTP(S) endpoint and AWS SQS.

Registering a Listener

---

1. HTTP(S) endpoint
   This option allows you to specify an HTTP URL that can receive a POST request when the notification is fired. Contact our development [e-mail] your request and we will assist you in registering your endpoint. AWS provides detailed documentation on how to receive messages and confirm subscriptions here: http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html
2. AWS SQS
   With this option you are required to have your own AWS account. Contact our development team at [e-mail] with your request and we will assist you in subscribing to the SNS topic. Details on subscribing your topic can be found here: http://docs.aws.amazon.com/sns/latest/dg/SendMessageToSQS.cross.account.html

Subscribing to your SNS Topic

---

Please see this article on how to subscribe to your SNS topic: Have QBench trigger your AWS Lambda function

Notification Types

---

1. Single
   An individual notification related to one entity.
2. Bulk
   A "bulk" notification related to multiple entities. For example, if multiple test statuses are updated on the test list page using a bulk action.

Message Structure for Single Notifications

---

QBench event notifications may also have slightly different structure depending on the entity type and how the notification was triggered. We'll start with the base fields that are generic to all notifications, then outline specific notification fields based on entity type. Additionally, notifications that are triggered by qbn_entity of order, sample, test, invoice, quotation, *-report, and *-printdoc will contain the customer ID in the qbn_addl field.

Base notification fields

Below are the data types and short descriptions for the base fields in a notification

Name	Data Type	Description
qbn_id	int	ID of the entity that triggered the notification
qbn_entity	string	Entity type that triggered the notification
qbn_type	string	Type of notification
qbn_modified_by	dictionary	Details about the user, contact, or API client that triggered the notification
qbn_object_history_id	int	History ID for the action that triggered the notification
qbn_addl	dictionary	If present, this field will contain additional context for special cases
changed_fields	array	If present, this will will contain details of what fields were changed

Details for qbn_entity

Below are the possible values for this field in a notification. Additional information specific to each entity notification can be found further in the article.

Value

order

sample

test

batch

customer

contact

source

patient

patient_contact

assay

panel

invoice

quotation

order-report

sample-report

test-report

order-printdoc

sample-printdoc

test-printdoc

testlist-printdoc

batch-printdoc

project

batch-protocol-worksheet

attachment

Details for qbn_type

 Below are the the possible values for this field in a notification

Value	Description
entity-created	An entity was created
entity-updated	An entity was updated
entity-deleted	An entity was deleted
status-changed	The status of an entity was changed. This may affect qbn_addl
attachment-uploaded	An attachment was uploaded
attachment-deleted	An attachment was deleted
custom	A custom action button was clicked in QBench

Details for qbn_modified_by

The qbn_modified_by field will have the following structure:

{
  "id": <string>
  "type": <string>
  "name": <string>
}

If the notification is triggered by a portal user then the field structure will be as follows:

{
  "id": "<contact ID>"
  "type": "CONTACT"
  "name": "<contact first name> <contact last name (if present)>"
}

If the notification is triggered by a LIMS user the the field structure will be as follows:

{
  "id": "<user ID>"
  "type": "USER"
  "name": "<user first name> <user last name>"
}

If the notification is triggered by an API client then the field structure will be as follows:

{
  "id": "<API client ID>"
  "type": "API_CLIENT"
  "name": "<API client name>"
}

Examples of Additional Information or Special Cases

These are the cases where the notification has additional information beyond what is in the base notification. This is not a complete list of every possible notification.

LIMS User Changes Test Status

Changing a test status will populate the qbn_addl field. The notification structure is as follows:

{
    "qbn_addl": {
        "customer_id": <int>,
        "new_status": "<new status>",
        "order_id": <int>,
        "sample_id": <int>,
        "status": "<original status>"
    },
    "qbn_entity": "test",
    "qbn_id": <int>,
    "qbn_modified_by": {
        "id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_history_id": <int>,
    "qbn_type": "status-changed"
}

LIMS User Changes Order Status

Changing an order status will populate the qbn_addl field. The notification structure is as follows:

{
    "qbn_addl": {
        "customer_id": <int>,
        "new_status": "<new status>",
    },
    "qbn_entity": "order",
    "qbn_id": <int>,
    "qbn_modified_by": {
        "id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_history_id": <int>,
    "qbn_type": "status-changed"
}

 

LIMS User Uploads an Attachment

Uploading an attachment will add a few extra fields to the notification: : asset_id, attachment_id, attachment_upload_type, attachment_data_type, key, version, qbn_data_type, qbn_object_id:

{
    "asset_id": <int>,
    "attachment_id": <int>,
    "attchment_upload_type: "<string>",
    "attchment_data_type: "<string>",
    "key": "<string>",
    "version": <int>,
    "qbn_data_type": "order",
    "qbn_id": <int>,
    "qbn_modified_by": {
        "id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_id": <int>,
    "qbn_type": "attachment-uploaded"
}

 

LIMS User Deletes an Attachment

Deleting an attachment will add a few extra fields to the notification: asset_id, attachment_id, qbn_data_type, qbn_object_id:

{
    "asset_id": <int>,
    "attachment_id": <int>,
    "qbn_data_type": "order",
    "qbn_id": <int>,
    "qbn_modified_by": {
        "id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_id": <int>,
    "qbn_type": "attachment-deleted"
}

 

LIMS User Updates Batch Protocol Step Worksheet

This will add the worksheet data to qbn_addl and also add batch_id:

{
    "batch_id": <int>,
    "qbn_addl": {
        "worksheet_data": <dict>,
     },
    "qbn_entity": "batch-protocol-worksheet",
    "qbn_modified_by": {
        "id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_id": <int>,
    "qbn_type": "entity-updated"
}

LIMS User Updates Test Worksheet

This will add the changed_fields array to the notification Note any other field changes will show up in the changed_fields array:

{
    "changed_fields": [
        "worksheet_json"
    ],
    "qbn_addl": {
        "customer_id": <int>,
        "order_id": <int>,
        "sample_id": <int>,
        "status": "<string>"
    },
    "qbn_entity": "test",
    "qbn_id": <int>,
    "qbn_modified_by": {
        "id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_history_id": <int>,
    "qbn_type": "entity-updated"
}

LIMS User Generates a Sample Report

Generating a sample report will add customer_id, report_config_id, sample_id, test_ids, and uploaded to qbn_addl: 

{
    "qbn_addl": {
        "customer_id": <int>,
        "report_config_id": <int>,
        "sample_id": <int>,
        "test_ids": <array of strings>,
        "uploaded": false
    },
    "qbn_entity": "sample-report",
    "qbn_id": <int>,
    "qbn_modified_by": {
        id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_type": "entity-created"
}

LIMS User Publishes a Sample Report

Publishing a sample report will add customer_id, report_config_id, new_status and sample_id to qbn_addl: 

{
    "qbn_addl": {
        "customer_id": <int>,
        "new_status": "PUBLISHED",
        "report_config_id": <int>,
        "sample_id": <int>
    },
    "qbn_entity": "sample-report",
    "qbn_id": <int>,
    "qbn_modified_by": {
        id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_type": "status-changed"
}

LIMS User Generates a PrintDoc

Generating an order PrintDoc will add customer_id, order_id and printdoc_config_id to qbn_addl: 

{
    "qbn_addl": {
        "customer_id": <int>,
        "order_id": "<int>",
        "printdoc_config_id": <int>
    },
    "qbn_entity": "order-printdoc",
    "qbn_id": <int>,
    "qbn_modified_by": {
        id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_type": "entity-created"
}

Enabling "Changed Data in SNS Notification"

There's a setting in Configuration > Developer > Settings called "Enable Changed Data in SNS Notification". Enabling this will display the new values of the change fields that triggered the notification.

LIMS User Updates "sample_type" Field

{
    "changed_fields": [
        "sample_type"
    ],
    "changed_fields_data": {
        "sample_type": {
            "data": "Flower",
            "truncated_data": false
        }
    },
    "qbn_addl": {
        "customer_id": <int>
    },
    "qbn_entity": "sample",
    "qbn_id": <int>,
    "qbn_modified_by": {
        id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_history_id": <int>,
    "qbn_type": "entity-updated"
}

Enabling Bulk SNS Messages

There's a setting in Configuration > Developer > Settings called "Enable Bulk SNS messages". Enabling this will add qbn_is_bulk_message and qbn_part_of_bulk_action to individual notifications and additionally send an extra notification that contains all details pertaining to that bulk action. Examples of both are below:

LIMS User Changes Test Status In Bulk (3 tests)

Individual notification for each test

{
    "changed_fields": [
        "state",
        "complete_date"
    ],
    "qbn_addl": {
        "customer_id": <int>,
        "new_status": "<status>",
        "order_id": <int>,
        "sample_id": <int>,
         status": "<status>"
    },
    "qbn_entity": "test",
    "qbn_id": <int>,
    "qbn_is_bulk_message": false,
    "qbn_modified_by": {
        id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_object_history_id": <int>,
    "qbn_part_of_bulk_action": true,
    "qbn_type": "status-changed"
}

Bulk notification

{
    "qbn_data": {
        "<int>": {
            "additional": {
                "customer_id": <int>,
                "order_id": <int>,
                "sample_id": <int>,
                "status": "<status>"
            },
            "status_change": <bool>
        },
        "<int>": {
            "additional": {
                "customer_id": <int>,
                "order_id": <int>,
                "sample_id": <int>,
                "status": "<status>"
            },
            "status_change": <bool>
        },
        "<int>": {
            "additional": {
                "customer_id": <int>,
                "order_id": <int>,
                "sample_id": <int>,
                "status": "<status>"
            },
            "status_change": <bool>
        }
    },
    "qbn_entity": "test",
    "qbn_ids": [
        <int>,
        <int>,
        <int>,
    ],
    "qbn_is_bulk_message": true,
    "qbn_modified_by": {
        id": "<user ID>",
        "name": "<first name> <last name>",
        "type": "USER"
    },
    "qbn_num_objects": <int>,
    "qbn_type": "entity-updated"
}