SMART App Launch - Local Development build (v2.2.0-preview). See the Directory of published versions

Patient-Access Brands and Endpoints

Introduction

This specification provides a standardized method for Electronic Health Record (EHR) systems to publish Fast Healthcare Interoperability Resources (FHIR) endpoints and associated branding information to create a seamless user experience connecting patients to their health records through various applications. The specification focuses on the concept of “Patient-access Brands,” where apps display recognizable cards or tiles representing different healthcare providers, payers, or organizations offering patient access through their FHIR endpoints.

The specification defines FHIR profiles for Endpoint, Organization, and Bundle resources. It outlines the process for API providers to publish Brands associated with their FHIR Endpoints and for apps to collect and present these Brands to users. Each Brand includes essential information such as the organization’s name, logo, and patient access details, which apps can display in their user interface.

EHR systems, healthcare providers, and app developers can ensure a consistent and recognizable user experience when connecting patients to their health records across various platforms and services by following this specification.

Brands and Endpoints

Definition Of Brands And Endpoints In The Context Of The Specification

This specification is designed to support a model UX where apps display a collection of cards or tiles, each representing a “Patient-access Brand” that patients can recognize and connect to. App developers are not expected to follow this model UX precisely; the model exists to keep the design grounded and establish a shared vocabulary.

Design goals:

• Providers can publish Brand details (name, logo, etc.) that patients will recognize
• Brand details can be published alongside endpoint details
• Brand and Endpoint details can be published in aggregate (e.g., by EHR vendor, by region, or globally)
• Apps display Brands to create a “connect to my health records” UX

Patient-Access Brand Bundle Examples

The Patient-Access Brand Examples illustrate how providers can represent diverse scenarios including:

• National laboratory with thousands of locations
• Regional health system with independently branded affiliated practices that share a patient portal
• Cancer center affiliated with one portal for adult patients and another portal for pediatric patients
• Clinical organization that has recently merged and still uses distinct brands
• Aggregation publication of brands by EHR level
• Distributed publication of brands at the healthcare provider organization level

Demonstration Brand Editor

The SMART Patient Access: Brand Editor is a demonstration brand editor with FHIR export that showcasing the capabilities of the API through a user interface. It allows users to edit and preview branding configurations for an example SMART on FHIR app.

Guidelines For API Providers Publishing Brands Associated With Their FHIR Endpoints

A healthcare provider, payer, or other organization exposing a FHIR patient access API can decide which brands to publish with their FHIR endpoints. Each Brand includes data describing the organization offering patient access (e.g., organization name and logo) together with details about their patient access offering (e.g., name and description of their patient portal) in terms that patients should recognize.

An app can:

• Display the Brands it has collected (e.g., as cards or tiles in a UX)
• Allow users to filter or search Brands based on names, locations, or categories
• Allow users to select and connect to a Brand’s API endpoint

Brand Information

Essential Information Included In Each Brand

Each Brand includes the following information intended to support an app-based card or tile UX:

Patient Access Details

The details of the Patient Access Brand communicated to the patient.

Explanation Of The Relationship Between Brands And Endpoints

Commonly, a single Brand is typically associated with a single Endpoint. But the following cases are supported by this conceptual model:

• One Brand is associated with one Endpoint
  • For instance, a national lab might publish a Brand associated with their overall organization, including a complete list of zip codes where they operate.
• Multiple Brands are associated with one Endpoint
  • For instance, a regional health system might publish a small collection of brands based on a specific hospital or clinic that their patients will recognize.
• One Brand is associated with multiple Endpoints
  • For instance, a Hospital offering more than one patient portal for legacy purposes, or a patient portal hosting multiple FHIR API versions simultaneously
  • Becaues Brand information may be published in multiple place, Organizations include the same identifier to facilitate matching, merging, and de-duplication. Apps can merge Brands into a single target Brand’s card by displaying the target Brand’s title and logo. Within the Brand’s card, the app displays a distinct “connect” button for each set of Patient Access Details.

FHIR Profiles

Explanation Of FHIR Profiles For Endpoint And Organization Resources

An app assembles its collection of Brands (potentially as an offline, configuration-time process) by gathering FHIR PatientAccessEndpoint (Endpoints) and PatientAccessBrand (Organizations) data from:

• Vendor-consolidated Brand Bundles
• FHIR resources linked from .well-known/smart-configuration for each endpoint

which are defined below. For fine-grained organizational management, apps SHALL select the FHIR resources linked from .well-known/smart-configuration if they differ from the resources in a vendor-consolidated Brand Bundle.

FHIR Patient Access Endpoint Profile

Profile on Endpoint associated with a Patient Access Brand.

• extension
  • 1..* MS http://hl7.org/fhir/smart-app-launch/StructureDefinition/endpoint-fhir-version to convey the endpoint’s FHIR Version. This element is a denormalization to help clients focus on supported endpoints. The valueCode is any version from http://hl7.org/fhir/valueset-FHIR-version.html. (As of this publication, 4.0.1 is expected for ONC-certified EHRs).
• 1..1 MS status
• 1..1 MS connectionType – fixed Coding for hl7-fhir-rest
• 0..1 name fallback or default name describing the endpoint and the organization offering Patient API access at this endpoint. This value MAY contain technical details like FHIR API Version designations and apps SHOULD preferentially use names from an associated PatientAccessBrand rather than displaying this value to users.
• 1..* MS contact website where developers can configure access to this endpoint
  • 1..* MS system is url
  • 1..* MS value is an https:// URL for app developers
• 1..1 MS payloadType – fixed Coding for none
• 1..1 MS address FHIR base URL for server supporting patient access

Formal Views of Profile Contents

Example

Endpoint Example

{
  "resourceType" : "Endpoint",
  "id" : "example",
  "meta" : {
    "profile" : ["http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-endpoint"]
  },
  "extension" : [{
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/endpoint-fhir-version",
    "valueCode" : "4.0.1"
  }],
  "status" : "active",
  "connectionType" : {
    "system" : "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
    "code" : "hl7-fhir-rest"
  },
  "name" : "FHIR R4 Endpoint for Example Medical Center",
  "contact" : [{
    "system" : "url",
    "value" : "https://dev-portal.example.org"
  }],
  "payloadType" : [{
    "coding" : [{
      "system" : "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
      "code" : "none"
    }]
  }],
  "address" : "https://example.org/r4"
}

FHIR Patient Access Brands (Organization) Profile

Profile on Organization to communicate the branding associated with a Patient Access API endpoint.

• Extensions about the Brand
  • 0..* MS Logo
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/brand-logo
    • valueUrl SHOULD be optimized for display as a 1” square and formatted as SVG or 1024x1024 pixel PNG with transparent background. Logo should be be legible at small sizes (e.g., as small as 50x50 pixels). Tips to achieve this: if the logo contains both a brandmark and a wordmark, separate them and use just the brandmark. If the logo is predominantly horizontal, consider creating a vertically-oriented logo that is still recognizable when scaled to smaller sizes. Multiple logos may be supplied. The URL can be an absolute URL with the https:// schema, or a Data URL with the data: schema that directly embeds content.
  • 0..1 MS Logo use agreement
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/brand-logo-use-agreement-agreement.
    • valueUrl MAY include a link to terms for logo use by patient access apps.
  • 0..* Brand flags
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/brand-flags.
    • This flag is intended to help app developers understand and debug the organizational relationships that underpin published Brands. For example, a valueCode of hidden allows systems to designate Organizations as part of a hierarchy without necessarily being shown in a UX card or tile. Marking Brands hidden can also be used to associate many affiliated organizations with a parent Brand (e.g., each with its street address) without apps displaying redundant information to users.
• Extensions about the Brand’s Patient Access (“portal”). These extensions represent the “Patient Access Details” described in the conceptual model above. These extensions are “inheritable”, which means Brand entries in the Brand Bundle systems MAY be omit these extension whenever correct values are inferrable by following the entry’s “Patient access provided by” links (Organization.partOf).
  • 0..1 MS Patient access name (“portal name”) Note: A Brand MUST include a this extension or inherit the value from the Brand referenced by Organization.partOf.
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-name.
    • valueString indicates the name by which patients know the portal (e.g.,”MyChildren” or “Patient Gateway”)
  • 0..1 MS Patient access URL (“portal URL”) Note: A Brand MUST include a this extension or inherit the value from the Brand referenced by Organization.partOf.
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-url.
    • valueUrl indicates the location of the patient portal associated with this Brand – i.e., a URL where patients can go to see their data and manage access.
  • 0..1 MS Patient access description (“portal description”)
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-description.
    • valueMarkdown explains, if necessary (in patient-friendly language), the subset of patients eligible to connect and the data available. This capability supports (for example) a cancer center that uses one EHR for pediatric patients and another for adult patients. In this scenario, each EHR would publish a different PatientAccessBrand; apps would display the description to disambiguate the user’s selection. For instance, one Brand might indicate “Access records for childhood cancer care” and another might indicate “Access records for adult cancer care”.
  • 0..* MS Patient access logo (“portal logo”). Used if the portal has its own logo in addition to the Brand’s logo
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-logo
    • valueUrl See documentation for “brand logo”
  • 0..1 MS Patient access logo use agreement
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-logo-use-agreement.
    • valueUrl See documentation for “brand logo use agreement”.
• Extensions about customer-managed Brands
  • 0..* MS Logo
    • url is http://hl7.org/fhir/smart-app-launch/StructureDefinition/brands-bundle
    • valueUrl for a customer-managed Patient Access Brands Bundle that defines this Brand and related Brands. It allows customers to self-publish additional information about the Brand.
• 0..* MS identifier(s) that apps can use to link this Brand across publishers or with external data sets. EHRs SHALL support customer-supplied identifiers (system and value).
  • It is RECOMMENDED that each Brand include an identifier where system is urn:ietf:rfc: 3986 (meaning the identifier is a URL) and value is the HTTPS URL for the Brand’s primary web presence, omitting any “www.” prefix from the domain and omitting any path component. For example, since the main web presence of Boston Children’s Hospital is https: //www.childrenshospital.org/, a recommended identifier would be:

  { "system": "urn:ietf:rfc:3986", "value": "https://childrenshospital.org" }

• 0..* type Categories for this organization (system: http://hl7.org/fhir/smart-app-launch/CodeSystem/patient-access-category, code from: clinical, lab, pharmacy, insurer, network, aggregator)
• 1..1 MS name Primary brand name to display on a card
• 0..* MS alias Aliases (e.g., former names like “Partners Healthcare”) for filtering/search
• 1..1 MS telecom with system of url and value conveying the primary public website for the Brand. Note this is distinct from the patient access portal website (described below)
• 0..* MS address Locations (e.g., zip codes and/or street addresses) associated with the Brand. The following combinations are allowed:
  • State
  • City, state
  • City, state, zip code
  • Street address, city, state, zip code
  • zip code alone
• 0..1 MS partOf “Patient access provided by”, to convey that an affiliated Brand hosts this Brand’s API technology and patient portal. The hierarchy of “access provided by” links SHALL NOT exceed a depth of two (i.e., a Brand either includes portal details or links directly to a Brand that provides them).
• 0..* MS endpoint references one or more PatientAccessEndpoints. Typically, this property associates a single “primary brand” with the endpoint. Additional affiliated Brands or parent brands can be associated via “Patient access provided by” links (Organization.partOf). EHR vendors SHALL support integrated publication of Organizations in the same JSON Bundle, as well as external customer-managed publications:
  • 0..1 MS reference containing a relative URL to an Endpoint within a Brand Bundle

Formal Views of Profile Contents

Example

Organization Example

{
  "resourceType" : "Organization",
  "id" : "example",
  "meta" : {
    "profile" : ["http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-brand"]
  },
  "extension" : [{
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/brand-logo",
    "valueUrl" : "https://example.org/logo/main.1024x102.png"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/brand-logo-use-agreement",
    "valueUrl" : "https://example.org/logo/use-agreement.html"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/brand-flags",
    "valueCode" : "hidden"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-name",
    "valueString" : "Example Health Portal"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-url",
    "valueUrl" : "https://example.org/myportal"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-description",
    "valueMarkdown" : "This is the description of the portal. It can be multiple lines.\nIt can also be **markdown**.\n"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-logo",
    "valueUrl" : "https://example.org/portal-logo/main.1024x102.png"
  },
  {
    "url" : "http://hl7.org/fhir/smart-app-launch/StructureDefinition/patient-access-logo-use-agreement",
    "valueUrl" : "https://example.org/portal-logo/use-agreement.html"
  }],
  "identifier" : [{
    "system" : "urn:ietf:rfc:3986",
    "value" : "https://examplehospital.org"
  }],
  "active" : true,
  "type" : [{
    "coding" : [{
      "system" : "http://hl7.org/fhir/smart-app-launch/CodeSystem/patient-access-category",
      "code" : "clinical",
      "display" : "Clinical Care provider"
    }]
  }],
  "name" : "Example Organization",
  "alias" : ["Example Health System"],
  "telecom" : [{
    "system" : "url",
    "value" : "https://example.org/brand-home"
  }],
  "address" : [{
    "line" : ["100 1st Avenue, Suite 227"],
    "city" : "Pleasanton",
    "state" : "MA",
    "postalCode" : "01002"
  }],
  "partOf" : {
    "display" : "Larger Health System"
  },
  "endpoint" : [{
    "reference" : "Endpoint/example",
    "display" : "FHIR R4 Endpoint for Example Medical Center Brand"
  }]
}

FHIR Patient Access Brand Bundle Profile

JSON FHIR Bundle (type: collection) of Endpoint and related resources is hosted at a stable, publicly available, publicly disclosed location. Bundle Entries include:

• Patient Access Endpoint Profile resources.
• Patient Access Brand (Organization) resources. Vendors SHALL publish at least a “primary brand” for each endpoint and SHOULD support the publication of a more detailed Brand hierarchy.

Brand Bundles SHALL populate Bundle.meta.lastUpdated to advertise the timestamp of the last change to the contents. In addition, Brand Bundles SHOULD populate Bundle.entry.resource.meta.lastUpdated with a more detailed timestamp if the system tracks updates per Resource.

Formal Views of Profile Contents

Partial View Of Brand Bundle Example

The following Bundle fragments in the example below illustrate how Brand data is compiled into a Bundle and how a Brand (in other words, an Organization) references an Endpoint within the same Bundle. See the Patient-Access Brand Examples for complete examples.

{
  "resourceType": "Bundle",
  "meta": {
    "lastUpdated": "2022-03-14T15:09:26.535Z"
  },
  "entry": [{
    "fullUrl": "https://pab.example.org/Endpoint/example",
    "resource": {
      "resourceType": "Endpoint",
      "id": "examplelabs",
      // ...
    }
  }, {
    "fullUrl": "https://pab.example.org/Organization/example",
    "resource": {
      "resourceType": "Organization",
      "name": "Example Hospital",
      /// ...
      "endpoint": [{
         "reference": "Endpoint/examplelabs",
         "display": "FHIR R4 Endpoint for ExampleLabs Brand"
      }]
    }
  }],
  // ...
}

Rules And Best Practices For Creating And Using Patient Access Profiles

Guidelines For Caching And Managing Cross Origin Resource Sharing (CORS) For FHIR Resources

Publishers SHALL support Cross-Origin Resource Sharing (CORS) for all GET requests to the artifacts described in this guide.

Publishers SHOULD include a weak ETag header in all HTTP responses. Clients SHOULD cache responses by ETag and SHOULD consist of an If-None-Match header in all requests to avoid re-fetching data that have not changed. See https://www.hl7.org/fhir/http.html for background.

Metadata in .well-known/smart-configuration

FHIR servers supporting this IG SHOULD include the following property in the SMART configuration JSON response:

• 0..1 patientAccessBrandBundle URL of a Brand Bundle. The Bundle entries include any Brand and “peer endpoints” associated with this FHIR endpoint.
• 0..1 patientAccessPrimaryBrandIdentifier: FHIR Identifier for this server’s primary Brand within the Bundle. Publishers SHALL populate this property if the referenced Brand Bundle includes more than one Brand. When present, this identifier SHALL consist of a value and SHOULD have a system.

The Brand Bundle SHALL include a Brand whose Organization.identifier matches the primary Brand identifier from SMART configuration JSON.

The Brand Bundle SHOULD include only the Brands and Endpoints associated with the SMART on FHIR server that links to the Bundle. However, the Brand Bundle MAY have additional Brands or Endpoints (e.g., supporting a publication pattern where endpoints from a given vendor might point to a comprehensive, centralized vendor-managed list).

Example .well-known/smart-configuration

{
  // details at http://hl7.org/fhir/smart-app-launch/conformance.html
  "patientAccessBrandBundle": "https://example.org/brands.json",
  "patientAccessPrimaryBrandIdentifier": {
      "system": "urn:ietf:rfc:3986",
      "value": "https://example.org"
  },
  // ...
}

Dereferencing the patientAccessBrandBundle URL above would return a Brand Bundle.

Must-Support Definition (MS) and Data Absent Reasons

For this specification a profile element labeled as “must support” means publishers must provide a way for Brands to populate value. For example, marking a Brand’s “address” as 0..* MS means that a publisher needs to give Brands a way to supply multiple addresses, even if some choose not to provide any.

The EHR that publishes a Brand Bundle may not have some required data elements (Brand Website, Portal Website, Portal Name). If the EHR has asked, but a Brand administrator has not supplied a value, the EHR MAY provide a Data Absent Reason of asked-declined or asked-unknown. The EHR SHALL NOT use other Data Absent Reasons.