Home > Launching the IAR Visual App

Launching the IAR Visual App

This section describes the overall process and steps involved for a Client Application to launch the IAR Visual app.

NOTE: The client application must be pre-registered with IAR as a prerequisite prior to launching the IAR Visual App.

The overall sequence of launching the IAR Visual App is shown below. The use case starts immediately after the client application (such as an EMR or HIS) has a patient in context, and requests to view IAR assessments. Typically, there would be a link within the Client Application that would allow the user to launch the IAR Visual App.

Note that the numbers in the diagram correspond with the numbered steps below

Step 1 - Receive request for IAR assessment data

From within the client application (i.e. EMR, HIS, portal), the user initiates a request to retrieve IAR assessment data for a patient.

Step 2 – Prepare Authentication and Authorization JWTs

The client application prepares and digitally signs each of two JWTs, one for authentication and the other for authorization. Refer to Authentication and Authorization Tokens for more details.

Step 3 – Launching IAR Visual App

The user is already authenticated in the Client Application. A link will be exposed on the Client App to allow the user to launch the IAR Visual App. The Client Application has the option of embedding the IAR Visual App within iframe or launching it in a new browser window or tab.

The launch of the IAR Visual App is completed using secure HTTPS with the following mandatory URL parameters:

Example of a launch request:

https://{visual app base url}?assertion={signed authorization JWT}&client_assertion{signed authentication JWT}&patient_hcn={patient HCN}

Step 4 – Forward JWTs to the IAR Authorization Server

Once the IAR Visual App receives the launch request, it extracts the authentication and authorization JWTs from the request parameters and sends a request to the IAR Authorization Server to validate the tokens.

Step 5 – Validate JWTs and medicate access

The IAR FHIR authorization will validate the authorization and authentication JWTs and mediate access accordingly. The IAR authorization server performs the following steps:

• The authorization and authentication tokens are unsigned using the client application's public key
• The Client ID and Issuer specified in the JWTs are known and trusted by the IAR authorization server
• The IAR user ID specified in the authorization token exists in the IAR user registry
• All fields in the authorization and authentication tokens are specified correctly (see Authentication and Authorization JWTs section)

Step 6 (Alt flow) – Access Denied

If there is an issue with any of the authentication or authorization steps, an appropriate error is displayed in the IAR Visual App.

Step 7 – Prepare OAuth access and refresh tokens

If authentication and authorization is successful, the IAR Authorization Server creates the OAuth access and refresh tokens. The access token is managed by the IAR Visual App, and is presented to the IAR FHIR server for data requests.

For security reasons, the lifetime of the access token is short lived. As a result, when the access token expires, the refresh token is used by the IAR Visual App to renew the access token. Note that the renewal process is managed by the IAR Visual App, and is seamless to the Client Appilication.

Step 8 – Access token response

The OAuth access and refresh tokens are returned to the IAR Visual App. These tokens are managed by the IAR Visual App and is used for subsequent requests to the IAR Data API.

Steps 9 and 10 – Visual App is launched

The IAR Visual App is launched within the Client Application (either iframe or separate browser tab) is rendered in the browser. During the initital launch, an IAR Terms of Use is displayed and must be accepted before any clinical data is displayed.

Step 11 – Terms of User accepted

Terms of use is accepted by the end user.

NOTE: If the terms of use is rejected, the IAR Visual App will not launch

Step 12 – Retrieve IAR assessment list

Using the access token from Step 8, the Visual App sends a FHIR request to the IAR Data API to retrieve the patient's assessments. Only data from the past two years are returned.

Step 13 – Validate Access Token

IAR Data API validates the access token to ensure that it's valid and has not expired

Steps 14 to 16 – IAR assessment data returned

A patient's IAR assessment data is returned and rendered in the IAR Visual App.

NOTE: If not all of patient's assessments can be displayed due to a consent directive, a warning message will be displayed