On this page:

14.5Developer Portal

 

A public-facing website where vendors can register one or multiple applications and provide information about the apps for system administrators and patients who use the apps. Vendors can also track the status of their application registrations.

14.5.1API Documentation for Dev Portal

 

These are resources that we recommend for internal or third-party SMART on FHIR developers to help get SMART on FHIR App running and connected to Smile CDR. Developers should also review the RESTful API documentation for FHIR here.

While Smile maintains this documentation, we recommend that the Developer Portal feature users include these resources in a publicly accessible web page for app developers to access conveniently.

SMART on FHIR

Transacting with the FHIR Server

14.5.2Developer Registration

 

An account is required to gain access to the developer portal and begin registering 3rd party Apps. Creating a developer account requires the developer’s first name, last name, email address, and creation of a password.

Login page

Account creation

The developer registration process continues after the developer has logged in for the first time. The developer will be prompted to enter more identity information to set up their account:

A. Individual

  1. Legal First name and Last name
  2. Address
  3. Contact number
  4. Position/Designation

B. Business

  1. Legal First name and Last name
  2. Legal Business name
  3. Position/Designation
  4. Address
  5. D.U.N.S number (If applicable)
  6. Business contact number

This information can be found in the “Vendor Account” tab under the profile dropdown list in the developer portal. Only the following information is editable:

  1. Address
  2. Contact number
  3. Position/Designation
  4. Full Legal Business address
  5. Business contact number

Vendor Account page

14.5.3Developer Portal: UI Description

 

Developer Portal

Below is a description of the UI for the Developer Portal:

  1. Register App- Start here to register your first of many Apps or new App versions, using the App registration wizard.
  2. Status- Displays the current state of the App on the system. Statuses range from:
    • In Review- Waiting for a decision from reviewers on registration.
    • Live- App is registered and approved to be on the App gallery, and to access required scopes.
    • Rejected- An App is rejected when it does not meet the necessary requirements for approval. A rejection reason would be sent to the developer in this event.
    • Suspended- An App can be suspended by Admin if it is found to be in violation of the Terms and Conditions or Privacy Policy.
    • Retired- An App is automatically labeled as “Retired” after a new version is promoted to “Live” status.
  3. Message- Messages posted in the audit log for an App are displayed here. This allows Admin/Reviewers to communicate with developers.
  4. Date of change- Shows the date of the latest change of status.
  5. Version- The number that represents the iteration of an App that has been registered more than once.

14.5.4Setting-up a Sandbox Environment

 

To set up a sandbox environment for developers to test their apps, the following steps need to be followed:

  • Create a new SMART Outbound Security module
  • Create a new FHIR REST Endpoint (R4) module
  • Add the relevant OpenID Connect Authentication and Sandbox FHIR Endpoint dependencies in the App Management Tools module

Create a new smart_auth (SMART Outbound Security) module called smart_auth_sandbox. Full configuration for the smart_auth module is described here. However, ensure the following changes are made so that the smart_auth_sandbox module is distinguishable from the already configured smart_auth (SMART Outbound Security) module:

  • Module ID: smart_auth_sandbox
  • Listener Port: an open port (e.g., 19301)
  • Context Path: /auth-sandbox/
  • Issuer URL: https://[your-domain]/auth-sandbox
  • Username/Password Authentication: local_security (Local Inbound Security)

After the configurations have been made, select “Save” at the top of the page to get redirected to the “Configuration” page. A confirmation message would be displayed for the newly added module. It is recommended to “Restart” the module if any changes are made.

On the same page, the newly added module will be displayed under the “Manage Node Modules” table and in the Security Modules section in the menu pane on the left with a green checkmark icon to indicate a correctly functioning module.

Create a new fhir_endpoint (FHIR REST Endpoint R4) module called fhir_endpoint_sandbox. Full configuration for the fhir_endpoint module is described here. However, ensure the following changes are made so that the fhir_endpoint_sandbox module is distinguishable from the other fhir_endpoint module:

  • Module ID: fhir_endpoint_sandbox
  • Listener Port: an open port (e.g., 19302)
  • Context Path: /fhir-sandbox/
  • Username/Password Authentication: local_security (Local Inbound Security)
  • OpenID Connect Authentication: smart_auth_sandbox (SMART Outbound Security)

After the configurations have been made, select “Save” at the top of the page to get redirected to the “Configuration” page. A confirmation message would be displayed for the newly added module. It is recommended to “Restart” the module if any changes are made.

On the same page, the newly added module will be displayed under the “Manage Node Modules” table and in the FHIR Modules section in the menu pane on the left with a green checkmark icon to indicate a correctly functioning module.

In the App Management Tools module, ensure that the following are assigned under the Dependencies section:

  • OpenID Connect Authentication: smart_auth_sandbox (SMART Outbound Security)
  • Sandbox FHIR Endpoint: fhir_endpoint_sandbox (FHIR REST Endpoint (R4))

App Gallery Dependencies

** IMPORTANT NOTE **

Ensure that ONLY the fhir_endpoint_sandbox (FHIR REST Endpoint (R4)) is selected to access test data for sandbox testing.

After the configurations have been made, select “Save” at the top of the page to get redirected to the “Configuration” page. It is recommended to “Restart” the module if any changes are made.

** IMPORTANT NOTE **

In order to ensure developers can access the sandbox, ensure that the "OPENID_CONNECT_ADD_CLIENT" permission is granted. See here to learn how to grant the required permission.

OIDC Add Client

14.5.5Sandbox Testing: UI Description

 

‘My Sandbox’ can be accessed by developers from the dev portal landing page. Simply, click ‘Go to Settings’ or select ‘Sandbox Settings’ from the dropdown list as shown below:

Access Sandbox

An OIDC client is needed for developers to have their own sandbox to test in. In order to set up an OIDC client, certain information is required as shown below:

Sandbox UI

Sandbox Edit Setting

  1. App name: Name of the App as it appears in supported App stores and download sites 1. OIDC Redirect URLs: The URLs to which users are redirected upon successful authentication 1. Confidentiality: Declare if an app runs in an execution environment that enables the app to protect secrets. If not, toggle to “Public”. See here for more information.
  2. Requested Scopes: Enter the SMART scopes required for the app. Each scope should be separated by a space 1. FHIR Endpoint: The base URL of the FHIR server. To connect using OpenID connect, see here 1. Discovery Document: FHIR Authorization Endpoint and Capabilities Discovery 1. Client ID: automatically generated and can only be used by the app for testing in the sandbox 1. Client Secret: automatically generated (for confidential apps) and can only be used by the app for testing in the sandbox

Success Message

Developers can test one app at a time by changing these settings as needed using “Edit Settings”.

14.5.6App Registration

 

The developer portal utilizes an App registration wizard built to be easy to use and provide everything a developer needs to showcase their App to the reviewers and potential consumers in the App gallery.

The 7-step process to provide an App submission request includes:

Step 1: Provide App name as it appears in supported App stores and download sites

App Registration Step 1

Step 2: Select the operating system i.e., web, iOS or Android for which the App is available and to be published in the public-facing site.

App Registration Step 2

Enter the following information:

  1. App Homepage URL: The URL where the App’s download sites can be found (note: provide homepage URL if no specific App page exists)
  2. URL to the App’s Privacy Policy: URL of a webpage providing the App’s Privacy Policy
  3. URL to the App’s Terms of Service: URL of a webpage describing the App’s Terms of Service
  4. OAuth Redirect URL: URL to which developers are redirected upon successful authentication
  5. Web App Launch URL: URL used to start the authentication process for web apps only

Step 3: Provide App description for the public-facing site

App Registration Step 3

  1. Upload App Icon: use the guidelines from the Google Play store (link provided) to upload an app icon of the acceptable specifications. Option to preview the uploaded image is provided
  2. Short App Description: between 20-150 characters for the public-facing site
  3. Long App Description: between 200-1000 characters for the public-facing site

Step 4: Select categories that apply to your App (multiple options can be selected for each category)

App Registration Step 4

  1. Audience Category: options include payer, provider, pharma, patient, and developer
  2. App Use Category: options include Health & Therapy Management, Provider Care Coordination, Clinical Applications, Research, and Data Monitoring Analysis
  3. FHIR Version Supported: options include DSTU1, DSTU2, STU3, and R4
  4. Privacy & Security Compliance: options include HIPPA, GDPR, CARIN Code of Conduct, and ONC Model Privacy Notice (note: users may be asked to provide supporting documents)
  5. Confidentiality: if the App runs in an execution environment that enables the app to protect secrets leave at confidential; if not, toggle to public

Step 5: Enter scopes to request app permissions (note: link is provided for more information on SMART App Launch: Scopes and Launch Context)

App Registration Step 5

Step 6: Option to enter notes for the reviewer to help in the evaluation of the submission. If a re-submission is provided, then users are required to summarize the changes made.

App Registration Step 6

Step 7: Review legal attestation and either accept or decline adherence to the terms that describe the minimum privacy and security criteria to sufficiently protect patients' protected health information in accordance with the CMS and ONC.

** IMPORTANT NOTE **

In compliance with regulations, a developer may decline the terms and still successfully register the app. However, refusing the attestation terms will result in the display of a warning to patients both in the App Gallery as well as after patient authentication. Patients will be informed explicitly of the risks involved in using apps where the developer has declined the attestation terms and have the opportunity to refuse consent to the app during the OAuth process.

App Registration Step 7

Public vs. Confidential Apps

As part of the App registration process, developers are required to follow a 7-step process to provide an App submission request. The 4th step of this process enables developers to switch between the "public" or “confidential” option for the App to be submitted. By default the toggle switch is set to the “confidential” option.

In order to gain more information, the user can hover over the “i” icon and select the “learn more” option that leads to the “Smart App Launch Implementation Guide” webpage. Under the “Smart App Launch Framework”, the webpage provides information on support for “public” and “confidential” Apps and when to select the private versus confidential profile for Apps. The main differentiation is based on whether the execution environment within which the App runs enables the App to protect secrets or not, in the OAuth2 sense.

Public vs. Confidential Apps

Once the appropriate option (public versus private) has been selected and the subsequent steps of the 7-step process to provide an App submission request have been completed, the App will be sent for review. The status of the App submitted for review can be seen by developers in the Registered App page.

If the App has been reviewed and promoted by the admin to “Live” in the status column, the flyout that appears when the App name is selected shall contain the following information.

App Monitor

App Info page

As shown below, the "System Generated Secret", "Activation Date" and "Expiration Date" will not be included for public Apps.

Public Apps

Registered App Checklist

  • Client ID (randomly generated)
  • Client Secret (randomly generated)
  • Scope
  • FHIR Endpoint (e.g., https://try.smilecdr.com/baseR4); if multiple partitions, this endpoint is unique for each partition
  • OAuth 2.0 Authorize Endpoint (e.g., https://try.smilecdr.com/smart-outbound/oauth/authorize), generic
  • OAuth 2.0 Token Endpoint (e.g., https://try.smilecdr.com/smart-outbound/oauth/token), generic
  • Client Consent Revocation (e.g., https://try.smilecdr.com/smart-outbound/oauth/revoke), generic
  • Launch Request URL (OAuth2.0AuthorizeEndpoint?response_type=code&client_id=client_id&redirect_uri=client_redirect_uri&scope=scope&state=optional randomly generated by client&aud=FHIR Endpoint)

14.5.7Attestation

 

Developers are asked to attest that their App has privacy and security policies that meet or exceed the minimum standards required to protect a patient’s private health information.

To comply with regulations set by the CMS and ONC, app developers are allowed to decline the attestation terms and still register their App. Apps that have refused the attestation will be labeled in the App Gallery to warn potential users against its use. Additionally, patients are made aware of the risks of using these potentially harmful apps during the authentication process.

Attestation Documentation

The attestation document for each App can be accessed from an App’s information page.

  1. Select the App from the registered App list
  2. Select the “Attestation document” link from the information page
  3. A separate window or tab will open displaying the document.
  4. Print or save to pdf through the browser print console for your records.

Each attestation document will be electronically signed with the developer’s: Legal name, Position/ Designation, Legal business name and Date of attestation.

Managing Updated Attestation Documents

Developers are required to re-attest when attestation documents are updated. Developers will be notified of updated attestation via two methods. An email will be sent to their registered email address for the App, and a notification will be displayed next to the App on the Developer portal.

Updated Attestation Warning

The notification shows how many days has passed since the attestation document for an App has been out of date. Hovering over the notification displays a pop-up message asking the Developer to re-register the App and accept the updated attestation.

** IMPORTANT NOTE **

Developers can re-register their App by using the App registration process (outlined in the "App Registration Section")

14.5.8New App versions

 

A developer can register a new App version via the register App button on the registered App list page and by selecting “submit a new version” in the registration wizard. Developers should select the existing App from the drop list and edit the existing information to suit their new version.

New App Versions

A "Change Notes" section is provided in the registration wizard to allow developers to summarize any changes made in the App to help expedite the review process.

When registering a new App version, the App information from the previous version would be pre-populated in the registration wizard. This makes it easier for developers to keep the standard information while making the necessary changes.

14.5.9Additional Considerations

 

** IMPORTANT NOTE **

Google Chrome blocks third-party apps from sending cookies back to the server when using incognito window mode, which can have some unintended effects on the performance of Smile’s App Management Tools application.

To avoid this, please enable cookies manually by following the instructions below.

Step 1: Select the eye icon in the URL bar and the “site not working” link.

Google Chrome Incognito

Step 2: Select “Allow cookies".

Allow cookies