Getting Started

LMA

Assuming that users have already installed SmileCDR, the following steps describe how a customer can begin to use appSphere.

• Log in to the Smile CDR Web Admin Console (the administration UI for configuring the system).

• Create a new appSphere module by going to the “Manage Node Modules” section, selecting “appSphere” from the “Add Module of Type” drop-down list, then clicking “Add”.

The following page will open after clicking "Add" which allows the user to enter additional any configurations.

** IMPORTANT NOTE **

After a module has been created, “Default” configuration mode will be visible to users. To view “Advanced” configuration mode, check the box provided at the top right corner of the module page.

"Advanced Config" include fields such as Company Logo Small URL and Company Logo Large URL , for the location of the logo you’d like to show on appSphere's login page and navigation bar. Smile CDR’s logo is a placeholder by default. Appropriate domain and context path should be used to configure the URLs. There are examples of the URLs for each field.

** IMPORTANT NOTE **

The Auth URL, FHIR URL, and JSON URL must match those used in the respective modules. Similarly, the ** Client ID** name used in this section must match the name of the OpenID Connect Client that needs to be created, which is described under the Client Creation and Configuration section. The names of each of the components can also be changed to suit your preferences. In addition, the parent page for the link provided for the PHI Warning URL can be found here.

In the Initial appSphere Seedingsection, the Attestation Title and HTML file for both the legal and plain version are already added by default for the first version.

In the Email Configuration section, ensure the following configurations are made (detailed steps are available here) to enable developers to get notified if the status of their app changes, or if a new attestation version is created that requires them to re-attest:

• Email From Address: (e.g., name@yourcompany.com)
• Notification Emails: (Console Managers will use these emails to receive notifications for new registrations and document uploads)

Ensure that the necessary details are provided for the following fields as described below:

• In the Listener Port field, enter an appropriate port number (e.g., 19300).
• In the Context Path field, enter a name you’d like to use for the URL path (e.g., /app-gallery/).
• Toggle Respect Forward Headers and CORS Enabled to Yes
• Under the Dependencies section, for the OpenID Connect Authentication dropdown, select the SMART Outbound Security module that matches the value in the Auth URL field, e.g., smart_auth (SMART Outbound Security).

After entering the necessary details, click “Save”. On the "Module Config" page, you should see appSphere added to the list of modules in the Master node, under the Administrative Modules section in the menu pane on the left. It is recommended to “Restart” the module if any changes are made. A green checkmark icon indicates a correctly functioning module.

The appSphere module can then be selected from the list of modules listed under “Manage Node Module” on the "Config" page to make changes in the configurations, save the changes made, and archive them.

Auto-Approving Registrations in a Testing Zone

LMA

By default, a submitted App stays In Review until an administrator promotes it to Live from the App Management Console. A dedicated testing zone may have no administrator to do this, which leaves a developer's registration In Review and without an OpenID Connect client. The appSphere module can instead approve eligible registrations on its own, on a schedule.

** IMPORTANT NOTE **

ONLY FOR TESTING ZONE. DO NOT USE FEATURE IN PRODUCTION. USE WITH CAUTION. Auto-approval issues a working OpenID Connect client to a registration that nobody has reviewed. While it is enabled, the appSphere module reports a warning on the "Config Diagnostics" page.

Auto-approval is off by default. To enable it, set the following on the appSphere module in "Advanced" configuration mode, then restart the module:

• Auto-approving for Public and Confidential registrations (auto_approve.enabled): toggle to Yes.
• Auto-approve scheduler frequency in minutes (auto_approve.frequency_minutes): how often the module looks for registrations to approve — 5, 15, 30 or 60 minutes. Defaults to 15. The scheduler runs once per cluster rather than once per node.

Whether a registration is auto-approved depends on the authentication the developer declared for the App:

Each run approves every eligible App that is currently In Review, whichever route brought it there — a new registration, a re-registration, or an App an administrator moved back to In Review. An approved App reaches Live by the same path an administrator's approval takes: an OpenID Connect client is created for it, the developer is emailed about the status change, and the approval is recorded in the App's Audit Log.

An App using JWKS or a JWKS URL stays In Review for an administrator to promote from the App Management Console.

Config Diagnostics

LMA

On the landing page of Smile CDR Web Admin Console, the “Config Diagnostics” page is also available in the drop-down list under “Config” on the header's navigation menu.

The “Config Diagnostics” page provides a summary of warnings and errors in relation to the configurations made to set up all modules, including appSphere. A warning is meant to show configurations that would lead to an issue. An error shows issues caused as a result of incorrect configurations. The issue column provides recommendations on how the warnings or errors should be addressed (more information can be found here).