On this page:

16.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.

16.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

16.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

16.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. Modified- 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.

16.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 appSphere 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 appSphere 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

16.5.5Sandbox Testing: UI Description

 

‘My Sandbox’ can be accessed by developers from the dev portal landing page if it has been enabled during the setting-up process (see here). 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
  2. OIDC Redirect URLs: The URLs to which users are redirected upon successful authentication
  3. 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.
  4. Requested Scopes: Enter the SMART scopes required for the app. Each scope should be separated by a space
  5. FHIR Endpoint: The base URL of the FHIR server. To connect using OpenID connect, see here
  6. Discovery Document: FHIR Authorization Endpoint and Capabilities Discovery
  7. Client ID: automatically generated and can only be used by the app for testing in the sandbox
  8. 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”.

16.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.
  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 HIPAA, 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

In order to gain more information about public vs. confidential Apps, 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.

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

Once the 7-step process to provide an App submission request has been completed, the App will be sent for review. The status of the App submitted for review can be seen by developers under 'My Registrations' in the developer portal.

16.5.7App Information Page

 

The App Information Page is accessible by selecting the App name from the list under 'My Registrations' and will contain the information submitted by the developer at the time of registration. The information submitted will be categorized and made available under 'Description', 'Connection', 'Privacy & Security', 'Contact Information', and 'Documents' as shown below.

App Monitor

Description

App Info page

Connection

App Connection

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

Public Apps

Registered App Checklist

The 'Connection' tab can be viewed to check if the following have been assigned:

  • Client ID (randomly generated)
  • Client Secret (randomly generated, only available for confidential apps)
  • Scope (as provided from registration, along with default scopes)
  • 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)

Privacy & Security

App Privacy & Security

See here for more information on attestation & managing attestation documentation.

Contact Information

App Contact Info

Documents

App Document Upload

The 'Documents' tab is available for developers to submit documents that support their submission for registration.

Once, 'Documents' is selected, the following options are made available for document uploads:

  1. Upload documents: documents can be uploaded by clicking to select files from your computer or by dragging and dropping files (note: documents should be in .pdf format, and the maximum file size accepted is 10MB. A warning sign will appear if 4 or more documents are being uploaded together as this might slow down the process).
  2. File name: name given to the document uploaded based on how it is saved on your computer. Once the upload is successful, documents can also be selected from this list to be downloaded
  3. Description: an option to add a description for the uploaded document (note: the description should not exceed 200 characters).
  4. Flag for use: once a document is successfully uploaded, it is flagged/checked by default to inform the reviewer that it is 'ready for viewing'. The checkbox can be unchecked for any old or obsolete documents
  5. Timestamp: provides a log of the date and time for all uploads made

** IMPORTANT NOTE **

Documents cannot be uploaded for "Rejected" or "Retired" Apps as those are terminal states.

16.5.8Attestation

 

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. Developers can re-register their App by using the App registration process, as shown in the next section.

16.5.9New 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.

16.5.10Additional 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 appSphere 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