Noah ES Service App

Introduction

The sample app will provide coding samples for common use cases when developing an app using the Noah Cloud API.

Scope

The following use cases will be covered:

• App connection

• RTM Event subscription

• Read patient information

• Read action information

Technology

The sample app is developed as a ASP.NET Core MVC app. This makes it possible to present a UI for the service app to connect new tenants and show the service state.

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 service application which makes server to server communication, it can be trusted with secret information and the client is set up to use client credentials grant flow. Client id and client secret is obtained after app registration. Read more during app registration: App Registration for Noah ES Apps . Read more about authentication: Security and Authentication.

The Solution

Prerequisites

• .NET 6 SDK.

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 are located in the file: .\NoahESSampleServiceApp\appsettings.json. In app settings you can configure:

• Authority service URL

• Noah Cloud API URL

• Client ID

• Client Secret

The sample app is preconfigured to use HIMSA test environment with a sample app client id.

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 .\NoahESSampleServiceApp\NoahESSampleServiceApp.csproj
2: Open the browser and navigate to: https://localhost:5035/.

3: Use your test tenant ID to connect.
4: App will determine if it’s connected to the tenant. If it’s not, it will present a message saying it’s not connected with a 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, select ‘Registered' menu item to confirm the tenant connection state.

6: Select the 'Events' menu item to view received Noah ES events. By default the event subscription is setup to listen for all event types. Event subscription is setup in RtmEventSubscriptionService.cs.

7: If an action is created or updated and access is granted for that action data type, then a link to view the public blob data will be presented. By default the sample service app only ask for permission to access audiogram action data type 1. App permissions are setup in AppConnectionService.cs.

Open

Solution structure

The solution contains 1 projects:

• NoahESSampleServiceApp: Contains the sample service app.

Sample Service App Project structure

• Controllers: Contains the MVC controllers.

• Models: Contains data models.

• ViewModels: Contains view models.

• Views: Contains MVC views.

• Repositories: Contains the repositories for storing and retrieving data.

• 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. The project has following services:

  • IPatientService: Provides patient read operations.

  • IActionService: Provides action read operations.

  • ITenantRegistrationService: Handles registration of new tenants, updating tenant connection state and starting/stopping event listening. This interface is implemented by TenantRegistrationService, which is registered as a background service to receive app start/stop events.

  • IEventSubscriptionService: Handles setting up event subscription, start/stop listening for events and handling of incoming events. This interface is implemented by RtmEventSubscriptionService which listens for RTM events using SignalR.

  • IAppConnectionService: Manages app state and makes necessary app connection operations. The GetTenantAppState method 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. SignalR (Overview of ASP.NET Core SignalR ) is used to handle event subscription. To subscribe to events call the hub method "SubscribeTenant" with the tenant id and event subscription id as arguments. There are 2 types of event subscriptions:

    • App connection event subscription used when app is not connected with tenant. To subscribe invoke "SubscribeTenant" with the tenant id and client id as arguments.

    • Noah event subscription used when app is connected with tenant. To subscribe invoke "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.