Integrating the Healthcare Enterprise (IHE)

Automated notifications of new content in Terminology Gateway

A webhook is an HTTP callback. When new content is published in the Terminology Gateway, a publishing event will be POSTed to each registered webhook, notifying their respective owners about the publication.

Webhook registration

Individual users can register for webhook notifications by sending an email to: Cette adresse courriel est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser. and specifying the webhook endpoint. Upon registration, a unique api_id will be assigned to the webhook. Each notification POSTed by the Terminology Gateway will contain the api_id, allowing the endpoint to verify that the notification was indeed issued by the Terminology Gateway. The api_id must be echoed back by the webhook endpoint in the body of the notification response.

Webhook interface

The webhook endpoint must serve HTTP requests conforming to the following interface:

HTTP Request

{
  "api_id": "cb570e5a2748f349f9119431db836b3a23fdb6571afee34c0432d87220f2431b",
  "base_url": "https://termapi.infoway-inforoute.ca/rest/v1/",
  "notification_time": "2017110711:07:00",
  "targets": [
    {
      "id": "2.16.840.1.113883.2.20.6.1",
      "name": "Canadian Clinical Drug Data Set (CCDD)",
      "type": "package",
      "version": "20171016",
      "effective_date": "20171016",
      "publication_time": "2017103015:20:23",
      "message": "Monthly CCDD update for October 2017"
    },
    {
      "id": "2.16.840.1.113883.2.20.3.443",
      "name": "PrescribeIT",
      "type": "package",
      "version": "LPR2",
      "effective_date": "20171103",
      "publication_time": "2017110309:37:22",
      "message": "PrescriptionMedicinalCode version reflecting the October 2017 CCDD update"
    }
  ]
}
				

• api_id: as previously mentioned, each notification POST contains the api_id granted at registration.
• base_url: the base URL for the native REST API endpoint of the originating system. This can be used to call back the Terminology Gateway via APIs in order to programmatically download updated content.
• notification_time: the timestamp of the webhook notification in yyyyMMddHH:mm:ss format.
• targets: list of updated targets. Each entry in this array corresponds to a Terminology Gateway artifact (subset, codesystem, map, package) that was updated and is therefore subject to the notification. The target list will only include artifacts for which the user has registered to receive notifications. Users can register to receive notifications about content updates using the Terminology Gateway User Interface or by invoking the native REST APIs.
  
  Each of the notification targets contains the following fields:
  • id: the artifact id, typically an OID
  • name: the artifact name
  • type: the artifact type: subset, codesystem, package or map
  • version: the published version id
  • effective_date: the effective date associated to the artifact version, in yyyyMMdd format
  • publication_time: the publication time in yyyyMMddHH:mm:ss format
  • message: optional message describing the published artifact version

HTTP Request

HTTP Response code: 200 for success, any other response code will be interpreted as an error
Sample HTTP Response Body:

{
  "api_id": "cb570e5a2748f349f9119431db836b3a23fdb6571afee34c0432d87220f2431b",
  "result": "success",
  "message": "Successful processing of the webhook notification"
}

• api_id: as previously mentioned, each notification response must echo back the api_id granted at registration.
• result: success if the web hook notification was successful, any other value will be interpreted as an error.
• message: optional response message.

Error handling

When receiving an error as a result of a webhook notification, the Terminology Gateway will retry the notification four times at 15 minutes intervals. If still unsuccessful after four notification attempts, the system will drop the notification and will notify the user by email that the webhook couldn't be invoked.

Sample code

Demo code for a sample webhook endpoint can be found here: 

https://github.com/CanadaHealthInfoway/tgateway-webhook

A Uniform Resource Identifier (URI) is a globally unique string of characters that provides a simple and extensible means for identifying a resource. URIs are used to identify a namespace or the location of a resource. URIs are human-readable and offer the potential for resolvability. The HL7 FHIR^® specification recommends using URIs to have all resources resolvable and to comply with the FHIR RESTful paradigm.

URI Registration Process

1. Requestor shall first check that the URI does not already exist in the Canadian URI Project, Jurisdictional Registry (if exists) or HL7 FHIR Specification. 
2. FHIR URIs must not be proposed for Subsets to be published on the Terminology Gateway as they will be generated automatically.
3. Requestor shall contact the owner or respresentative for either:
   • Jurisdictional URI, requestor shall contact Jurisdictional Representative who will post a suggested URI in accordance with the URI guidelines, to the HL7 Canada forum and FHIR Implementations WG forum
   • Non-jurisdictional URI, requestor shall contact the owner or responsible body who will post a suggested URI in accordance with the URI guidelines, to the HL7 Canada forum and FHIR Implementations WG forum
4. Forum posts shall have the following format:
   
   Subject: New URI Request
   • Description: “A description of the URI”
   • Responsible Body & Contact Information
   • Proposed FHIR URI: URI as per URI Guidelines
   • Existing OID (if exists)
   • To be published (optional): Jurisidictional repository/ Canadian URI Registry
5. There will be a wait period of five business days for the communities to react to the forum post with comments, questions or requests for clarification.
6. Update Forum post will be updated with the new URI.
7. Publishing the URI in the Canadian URI Registry and Jurisdictional Registry. This is highly recommended to prevent any misuse or duplication of URIs but it is optional.

See a flowchart of the FHIR URI Registration Process (pdf).

Pan-Canadian Standards use Object Identifiers (OIDs) to distinguish between objects by assigning a numeric string that enables other systems to understand the unique information that is being shared between various systems.

Canada Health Infoway (Infoway), as the HL7 Canada Affiliate, has an arrangement in place with HL7 International that allows Infoway to submit OIDs to HL7 International free of charge, on behalf of Canadian Implementers who are members of the HL7 Canada Affiliate. There is a $500 USD fee per OID request if done directly with HL7 International.

To submit an OID, download the registration form that corresponds to your OID request.

• For Infoway owned subsets, email the completed form to Cette adresse courriel est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.
• For all non-jurisdictional requests, please follow the instructions below
• All other requests must be sent to the Jurisdictional Representatives for OIDs

OID submission guidelines

1. Jurisdictional Teams require 5-7 business days to process each request. It will be incumbent on the requestor to reply within this time frame to any questions and follow up as required. Any failure to do so will result in an automatic rejection and require resubmitting the request.
   
   
2. The Requestor must post the OID requests on the following forums ONLY after consulting with the Jurisdiction/Infoway SME:
   • For jurisdictional/non-jurisdictional OID Requests: HL7 Canada Community and FHIR Implementation WG
   • For Subset OID Requests: Public Health Surveillance and Health Terminologies.
   
   TIP How to upload and link a document to an InfoCentral Forum
   
   
3. Forum posts shall have the following format:
   
   Subject: New Namespace/CodeSystem/Subset OID Request
   • OID Description: “A description of the OID”
   • OID Symbolic name: Symbolic name guidelines
   • Responsible Body & Contact Information
   • Proposed FHIR URI: URI as per URI Guidelines
   • To be published: Canadian URI Registry/Terminology Gateway
     
     
4. There will be a wait period of 5 business days for the communities to react to the forum post with comments, questions or requests for clarification.
   
   
5. FHIR URIs must be proposed for all jurisdictional and non-jurisdictional OID requests according to the URI Guidelines and must be published in the Canadian URI Registry. Publishing the URI is an optional but highly recommended step. The Requestor will submit a validated FHIR® NamingSystem resource object based on the NamingSystem profile to their jurisdictional representative who will then upload it.
   
   
6. FHIR URIs must not be proposed for Subsets to be published on the Terminology Gateway as they will be generated automatically.
   
   
7. The Forum post will be updated with the new OID.

Le registre canadien d'identificateurs uniformes de ressources (URI) a été créé pour regrouper l'information concernant les espaces de noms des identificateurs et des systèmes de codes. L'utilisation des ressources NamingSystem de FHIR® rend la saisie des métadonnées propice à la consultation et au traitement informatique. Elle permet aussi le mappage bidirectionnel automatique entre les identificateurs d'objets (OID) et les URI.

Afin de rendre la recherche de ces artéfacts plus souple, le registre d'URI canadien (alpha) permet d'effectuer des recherches via du texte en clair, des OID ou des URI. Les identificateurs URI sont créés à l'aide des lignes directrices URI et affichés sur la page du groupe de travail sur l'architecture de solutions FHIR en vue d'être approuvés.

Tous les artéfacts NamingSystem sont organisés par le Canadian URI Project dans Simplifier et peuvent faire l’objet de recherches après une période de 20 minutes.

Consultez le registre d’URI canadien(alpha)

The Canadian FHIR^® Registry supports collaborative development in an effort to accelerate sustainable growth of FHIR, locally and internationally. The registry is the home of national FHIR profiles recommended for use in Canada, including extensions, value sets, URIs and other useful, commonly used components. It is also host to a growing number of national, jurisdictional and locally shared FHIR projects, and is open at no cost to all Canadian implementers.

The Canadian FHIR Registry offers:

• seamless integration of profile editing using Forge (free FHIR profile editor)
• designated project space
• supports project teams of up to 100 individuals
• online authoring of implementation guides
• integration with source control tools such as GitHub
• version controlled environment
• a sandbox project where users are encouraged to test the different features of the tool before officially requesting a new project 

The Canadian FHIR Registry blends software development best practices with the requirements of modelling in FHIR, essential to delivering successful project requirements while having continuous access to structure validation, rendering and publishing.

There is an expectation that all projects in the Canadian FHIR Registry will be public, to promote Pan-Canadian interoperability, and so that others can see what is being worked on across Canada. Please note that ‘public’ does not mean ‘published’. Project owners are encouraged to use the Description and/or Subtitle properties to indicate the status of their projects (ie. Draft, For Internal Use).

Organization projects can be viewed without logging in.

How to Request a New Project

Please email Cette adresse courriel est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser., please use Subject: Requesting Simplifier.net Project

In addition, please provide

1. Name of Organization requesting the project
2. Project title
3. Brief Project Description
4. Version of FHIR for project
5. Registered email addresse(s) of project administrator(s) (To register on Simplifier.net, please sign up here - https://simplifier.net/signup)
6. Status of the project - Private/Public (please note that a new project can be in private status for 2 to 3 weeks after which it will be made public. This enables promotion of re-use and interoperability.

How to Request Access to Sandbox

Please email Cette adresse courriel est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser., please use Subject: Requesting Access to Sandbox

In addition, please provide

1. Name of Organization requesting the project
2. Version of FHIR for project
3. Registered email addresse(s) of indvidual(s) to be added to sandbox (To register on Simplifier.net, please sign up here - https://simplifier.net/signup)
4. Duration (in days) you intend to test, after which your reservation will be recycled for other users

View projects in the Canadian FHIR Registry

Service Level Agreement and Business Continuity

Simplifier.net should not be used in a production setting, as 24/7 support is not provided by Infoway or Firely^®.

A project created in the Canadian FHIR Registry can be linked to an existing GitHub account. GitHub serves as a secondary backup and can sync the content in the project accordingly. Read details on how to set this up. 

Users of the Canadian FHIR Registry on the Simplifier platform can expect the following response time from the Firely team for any issue encountered.

Read an overview of the Service Level Agreement between Infoway and Simplifier.net.

All project artifacts are backed up weekly at midnight on Sundays. Each snapshot will be retained for 10 days. The project owner can request an as-is snapshot containing all the necessary artifacts such as text, xml, json, md and image files by contacting Cette adresse courriel est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser..

Forge License Agreement

As per the statement issued on the Firely blog,  Securing the future of Forge, the free version of Forge will be licensed for non-commercial use only starting January 1, 2020. To continue using Forge, users will need to be part of a paid plan on Simplifer.net. The current contract between Infoway and Firely for Simplifier.net allows for an unlimited number of users of Forge. Infoway has received confirmation from Firely that this will remain unaffected until December 31, 2021. If the authors in Simplifier.net belong to projects that are part of the Canadian FHIR Registry, they will be given rights through the administration processes of the platform conducted by Infoway.

Browse, download and leverage the terminology used in Canada

Terminology Gateway is a web based solution framework that enables the distribution and sharing of terminology concepts, subsets and concept maps, making them available for web browsing, download or real time query.

Browse Terminology Gateway Now

Open source integration tool useful for health IT integration projects

HAPI for HL7 v2 messages is an open-source, object oriented HL7 v2.x parser developed for the Java platform.

HAPI v2

RESTful web services used to browse terminology data

Terminology Service RESTful APIs enable automated exchange of clinical terminology content and resources. It allows developers to easily implement healthcare applications that programmatically consume codes and subsets without requiring in-depth expertise in the details of terminology.

Terminology Service API

Browse International and Canadian Content

SNOMED International's SNOMED CT browser allows users to search for existing concepts and explore relationships. It also provides access to browse national extensions from SNOMED International member countries including the Canadian Edition of SNOMED CT in English and French.

Browse SNOMED CT Now

FHIR® web services used to access terminology data

FHIR Terminology Service APIs enable automated exchange of clinical terminology content and resources. It allows developers to easily implement healthcare applications that programmatically consume codes and subsets without requiring in-depth expertize in the fine details of terminology.

FHIR Terminology Service API

Open source integration tools useful for health IT integration projects

HAPI FHIR® is a simple-but-powerful library for adding FHIR messaging to applications. It is pure Java compatible and licensed under the business-friendly Apache Software License, version 2.0.

HAPI FHIR

Request Management Solution

Infoway Request Management System (InfoRMS) is Infoway's Request for Change (RFC) tool for SNOMED CT, pCLOCD/LOINC^® and pan-Canadian Subsets. Not sure if you have access to InfoRMS? Manage your InfoRMS Access in your user profile.