App Connection

Before the NoahES App can access the NoahES Web API it must initially request which patient fields, (e.g. FirstName, LastName, BirthDate), action data types, (e.g. Fittings, HearingInstrumentSelections, Journals) and user account fields (e.g. FirstName, Image) that must be accessible to the app allowing it to perform its intended behavior.

The app won’t be able to make use of the API before the request has been approved by a user.

Checking current data access

It is assumed that an app will retrieve its current access permissions soon after being launched by calling GET AppConnection/GetCurrentDataAccess.

If HTTP status code 404 Not Found is returned it means that the app has never been connected before.

The app should check whether the patient fields, data types and user account fields that it intends to use have already been requested, but is either denied or is still in pending approval state.

Requesting data access

The app requests access by specifying patient fields, action data types and user account fields in the 'AppConnectionRequest’ data structure.

It is suggested to request commonly used permissions and include already granted permissions in the new request, in order not to remove access to features that the user has previously approved.

The information in the response ‘AppConnection’ received from the GetAppConnection call will allow the app to determine:

Whether the current user has permission to approve the request.
Where to redirect a web-browser in order for the user to approve the request.

An App can always request new permissions to access Patient Fields, Action Data Types and User Account Fields.
In case the App has a pending ‘AppConnection' for the Tenant it will be replaced by the latest 'AppConnection’.

When the AppConnectionRequest has been posted and later accepted through the URL that is returned, a AppPermissionsUpdated event will be sent as an RTM event. The app can then retrieve the current data access by calling GET AppConnections/GetCurrentDataAccess.

Please observe that the data access requested by the App may be fully or partially granted.

Main patient management system

A business system app can request 'Control Patient Management' right and become the main patient management system if the right is granted. There can only be one main patient management system, which means that an app which have been granted 'Control Patient Management' right will lose that right if another app is granted 'Control Patient Management' right at a later point in time. The main patient management system has permission to add, update and delete patient data. The business system app requesting 'Control Patient Management' right has the option to allow other apps (business and non-business apps) patient management i.e. allow other apps to add and update patient data, by specifying non-exclusive patient management. Likewise it can specify exclusive patient management to prevent other apps from adding and updating patient data.

Examples

Below is shown data structures followed by a sequence diagram where a user with the permission to approve requested access permission has launched a ‘NoahES User Interactive’ App.

AppConnectionRequest example:

{
	PatientFields: {
		"FirstName",
		"LastName",
		"BirthDate"
	},
	DataTypes: {
		0,
		3,
		256
	},
	UserAccountAccessLevel: "Limited", ("Basic", "Advanced")
	ControlPatientManagement: "DoNotRequest" ("RequestWithNonExclusivePatientManagement", "RequestWithExclusivePatientManagement")
}

AppConnection example:

{
    AppConnectionId : {
		"6c9e1877-4299-4c4a-b88a-d42188c1cb15"
	},
	CurrentUserCanApproveRequests: true,
	AppPortalUrl : {
		"https://portal.eu.noah-es.com/ManageAppConnections/Approve?id=6c9e1877-4299-4c4a-b88a-d42188c1cb15"
	}
}

CurrentDataAccess example:

{
	PatientFields: [
		{
			Field: "FirstName",
			Access: "Granted"
		},
		{
			Field: "LastName",
			Access: "Denied"
		},
		{
			Field: "BirthDate",
			Access: "PendingApproval"
		}
	],
	DataTypes: {
		{
			Field: 0,
			Access: "Granted"
		},
		{
			Field: 3,
			Access: "Denied"
		},
		{
			Field: 256,
			Access: "PendingApproval"
		}
	},
	UserAccountAccessLevels: [
		{
			Field: "Basic",
			Access: "Granted"
		},
		{
			Field: "Advanced",
			Access: "Denied"
		},
		{
			Field: "Limited",
			Access: "PendingApproval"
		}
	],
	ControlPatientManagement: "Denied", ("Granted", "PendingApproval", "NotRequested")
    CanManagePatients: true, // If true then app can add and update patient data
    ExclusivePatientManagement: false, // If granted 'ControlPatientManagement' then this will indicate if patient management is exclusive
    MainPatientManagementSystemName: "string", // The name of the current main patient management system
    Created: "2023-02-23T08:46:57.956Z"
}