NoahES and HIMSA SSO User Interactive App
The User Interactive Sample App can be used for both HIMSA SSO App and Noah ES App development.
Introduction
The sample app will provide coding samples for common use cases when developing an app using the Noah Cloud API.
The sample app can be downloaded here: https://www.himsa.com/members-2/noah-es-development/. Login is required.
The sample app for the QA Environment is available as a web application at https://noahessampleapp-qa.azurewebsites.net/
Scope
The following use cases will be covered:
App connection
Patient search
Create, read, update, delete and search patient identification
Create, read, update and delete patient metadata
Create, read, update patient
Read session information
Read and update action information
Create, read, update and delete user metadata
Create, read, update and delete app metadata
Technology
The sample app is developed as a WebAssembly app (https://developer.mozilla.org/en-US/docs/WebAssembly) using the .NET Blazor Framework (https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor), which makes it possible to develop the majority of the app in .NET C#. Blazor Wasm is SPA (https://en.wikipedia.org/wiki/Single-page_application) type of app.
Authentication
The sample app is set up to authenticate users against HIMSA's IDP, which supports the OIDC specification (How OpenID Connect Works - OpenID Foundation). Because it’s a web application it can’t be trusted with secret information (like a refresh token) and the client is set up to use authorization code grant flow with pkce and silent authentication (Configure Silent Authentication ). Read more about authentication: Security and Authentication.
The Solution
Prerequisites
.NET 6 SDK.
3rd party libraries and tools
MudBlazor(https://github.com/MudBlazor/MudBlazor): MudBlazor is a Blazor Component library, that provides free UI components based on Material Design. It allows developers to make a good-looking UI without having to struggle with CSS and Javascript.
API Client library
The sample app is using the recommended HIMSA generated API client to access NoahES REST API. Read more about API clients: API Clients.
Configuring the sample app
The app settings is located in the file: .\NoahESUserInteractiveApp\wwwroot\appsettings.json
. In app settings you can configure:
Authority service URL
Noah Cloud API URL
Client ID
The sample app is preconfigured to use HIMSA test environment with a sample app client id, which is set up as a User Interactive app with an allowed redirect URL https://localhost:5030/authentication/login-callback
.
For more advanced configuration of the app look into the Program.cs
file, where service registration and configuration is done.
Starting the sample app
1: Open the solution in VS and build/run it from the IDE. Or run it from CLI with the command from solution root: dotnet run --project .\NoahESUserInteractiveApp\NoahESUserInteractiveApp.csproj
2: Open the browser and navigate to: https://localhost:5030/
.
3: Login.
4: App will determine if it’s connected to the user tenant. If it’s not it will present a message saying it’s not connected with an URL to Noah App Portal to approve the connection. Click the URL to open Noah App Portal and approve the app permissions.
5: After permissions are approved the sample app should reload its page and display patients.
Solution structure
The solution contains 3 projects:
NoahESSampleApp: Contains the sample app.
NoahESSamleApp.Server: ASP.NET Core webserver host of sample app.
NoahResource: Example of a Noah resource dll if app should be displayed in the Noah client module bar.
Sample App Project structure
Components: Contains Blazor UI Components. Notable is '
ActionCard.razor(.cs)
', 'PatientCard.razor(.cs)
' and 'PatientSessionsCard.razor(.cs)
' that retrieves data and displays the information cards for a selected patient. Most of the components are made with a code-behind approach, where the view (.razor file) is separated from the logic in separate files (.razor.cs file).Extensions: Contains a few helpful extension methods.
Mappers: Contains mappers to convert between data types.
Pages: Contains the pages that can be reached by an URL.
Services: Contains application services. A service is an abstraction level above the Noah Cloud API, that can contain validation or business logic and makes it easy to retrieve and store data. It is the services that are injected into the Blazor components. The project has following services:
IPatientService: Provides patient related CRUD operations.
IActionService: Provides action and session related CRUD operations.
IGlobalSettingsService: Provides read operations for global settings and data types.
IUserAccountService: Provides user account related CRUD operations.
IAppService: Provides app scope related CRUD operations.
IUserContext: Provides information about the authenticated user.
IETagService: Provides caching of ETags. The ETag (ETag - HTTP | MDN ) header is cached when the
CallApi
method is called inNoahCloudServiceBase.cs
if anObjectToETagCacheKeyConverter
is registered for the returned object type.ObjectToETagCacheKeyConverter
provides conversion from object to ETag cache keys, so an object of an object type which aObjectToETagCacheKeyConverter
is registered for, can be used to retrieve and store ETags. A list ofObjectToETagCacheKeyConverter
is registered with theETagService
inProgram.cs
.IAppStateService: Manages app state and makes necessary app connection operations.
AppStateService
has one methodDetermineAppState
which determines the current app state and makes app connections requests to:Request initial app connection.
Request new permissions.
Determine if app has sufficient permissions to continue.
IRtmEventService: Provides operations to set up RTM event listening and publish the events to the event aggregator. SignalR (Overview of ASP.NET Core SignalR ) is used to handle event subscription.
RtmSetupComponent.razor
starts theHubConnection
and contains logic to check the current app state and start listening for events using theIRtmEventService
. TheRtmSetupComponent.razor
component is created inMainLayout.razor
. Also created inMainLayout.razor
is theRtmEventHandlerComponent.razor
component, which subscribes to RTM events and displays them as a popup.
There are 2 ways to subscribe to events:App connection event subscription used when app is not connected with tenant. To subscribe invoke hub method
"SubscribeTenant"
with the tenant id and client id as arguments.Noah event subscription used when app is connected with tenant. To subscribe invoke hub method
"SubscribeTenant"
with the tenant id and event subscription id as arguments. The app is responsible for creating an event subscription with the events it’s interested in.
IEventAggregator: The Event Aggregator acts as a single source of events for many objects. Used for easy messaging between components.
Shared: Contains the main layout of the app.