Smile CDR v2024.08.PRE
On this page:

25.1.1EasyShare SMART Health Links Public module


The EasyShare SHL Public module is the public-facing (i.e. typically accessible via the public internet) web endpoint for implementing SMART Health Links (SHL). See EasyShare SMART Health Links for an overview of how this works.

This module provides the following functionality:

  • It provides the data API used by capable applications to fetch data associated with a SMART Health Link.
  • It provides the web-based viewer application available to consumers of SMART Health Links who do not have specific software that can consume the data API.
  • It provides a REST API that can be used to create new SMART Health Links.
  • It handles storage and retrieval of SMART Health Link data in a database.



This module requires a connection to a database, using any supported RDBMS platform (see platform requirements) for storage. It is possible to share a schema with other modules of Smile CDR (Cluster Manager, FHIR Storage) but it is recommended to use a dedicated schema if you expect nontrivial data loads in your system.

To configure this module, a listener port and database connection must be provided. You must also provide a Public Base URL, which is the internet-facing web address that clients will use to access the module endpoint.

Accessing SMART Health Links (i.e. allowing users to scan QR codes served up by this module and view the SHL contents) does not require any security configuration, as passcode verification is handled entirely within this module and does not use any external security modules.

If you want to support the SHL Creation API however, you will need to enable a Web Service API authentication mechanism.

To test this module out, you can manually create a SMART Health Link using the SHL Creation API or by adding an EasyShare SHL Admin module and using the SHL Creation Application.

25.1.3SHL Creation API

This method requires the EASYSHARE_CREATE_SMART_HEALTH_LINK permission.

The SHL creation API is a REST service that is used to create a new SMART Health Link, using a raw FHIR payload as input, along with a few metadata elements. The FHIR payload currently must be an International Patient Summary compliant document, although this restriction may be removed or changed in the future.

To invoke:


The request should include the following parameters:

  • label – This is a label for the SHL that will be embedded in the link. This value will be visible to anyone who scans the QR code, even before they enter the passcode.
  • passcode – (optional) This can optionally contain a passcode which must be entered in order to access the data.
  • Link expiry time – (optional) An expiry time after which the SHL will no longer be usable, using either of the following formats:
    • By timespan (both of the following parameters must be present):
      • expiresIn – A number, e.g. expiresIn=5
      • expiresInUnits – A unit, e.g. expiresInUnits=DAYS. Valid values are: YEARS, MONTHS, WEEKS, DAYS, MINUTES, SECONDS, MILLIS.
    • By exact time:
      • expiryTime – An exact time in ISO-8601 format, e.g. expiryTime=2024-01-10T13:00:00Z
  • entryContentType – The content type for the FHIR payload in the SHL. This currently must be set to application/fhir+json although this limitation may be removed in the future.
  • entryContentString – The FHIR payload in the SHL. This currently must be a JSON-encoded International Patient Summary document, although this limitation may be removed in the future.

The server will produce a response resembling the following:

  "publicId": "a1b2c3d4",
  "shlQrCodeImageBytes": [
    "...[base 64]..."
  "shlString": "[SHL string]...",
  "encryptionKey": "a1b2c3d4"

Note that the shlQrCodeImageBytes element will contain a Base64 encoded form of the QR code image, which will be in PNG format.