Web API (Noah Mobile) Developers Guide - Full Document

IMPORTANT: Noah Mobile will require Noah 4.9 after November 7th 2018 !

Noah Mobile is an extension of the Noah 4 Framework which allows apps e.g. on a mobile device to access Noah data from a Noah 4 Business System via the Noah Mobile REST API.

When this feature is enabled in Noah System (or in another Noah-compatible Business System), an app will be able to access Noah data in an alternative way to a traditional Noah module on a PC. For a general overview, read the Noah Mobile Whitepaper.

The SDK documentation provides the information necessary to develop your own Noah Mobile app.

• locally over a LAN network or 

• over the Internet using a secure cloud connection

• When a Noah Mobile enabled Business System (Noah Server Remote Host) has been configured and enabled, it will establish a message queue connection (Service Bus Queue) to the Noah Mobile Cloud solution.

• When an App (Noah Mobile Client Application) wants to connect to the Business System (Noah Server Remote Host), then the client application performs a discovery on the Cloud Noah Mobile WebAPI. This causes a ‘wakeup message’ to be sent to the Noah Server Remote Host requesting it to establish a Service Bus Relay connection. 

• When the Service Bus Relay connection has been established then it will be active for a set period of time or as long as there is data traffic. The Service Bus Relay will automatically close a set period of time after the last detected data exchange.

• The client application must then authorize using the ‘Cloud Authorization Server’ to obtain an access token. The access token allows it to access the Cloud Noah Mobile WebAPI. Access tokens are valid for a limited period and the client application must acquire a new one upon expiration.

NOTE: When a Noah Mobile client application accesses a Noah Server Remote Host through the cloud, you will observe that the response is not immediate. Requesting data through the cloud will add some latency to the total response time for the request.

Encrypted Communication

– NoahMobile relies on encryption to protect the communications between the client application and NoahMobile. NoahMobile has support for TLS 1.1 and TLS 1.2 cryptographic protocols. Note: TLS 1.0 is not supported!

Authorization

Noah Mobile supports OAuth 2.0 ‘implicit grant flow’ Authorization in this release, and requires that client applications authorize in order to access the Noah Mobile API. The Implicit Grant flow is used when the user-agent will access the protected resource directly, such as in a rich web application or a mobile app. A successful Authorization will return an Access Token required to access to Noah Mobile API. 

We provide detailed information on using OAuth 2.0 ‘implicit grant flow’ with Noah Mobile here.

1. You should have a working knowledge of the Noah 4 Framework and its object hierarchy.

2. You have a solid knowledge of app development.

Here is a checklist to make sure you are ready to develop your app:

• Company name (may be displayed by the business system accessed by the app)

• Contact person(s), first and last name

• E-mail address for contact person(s)

• App name (may be displayed by the business system accessed by the app)

• Redirect URI (This URI specifies where/or what the Authentication server should return after user authentication (Oauth 2.0 Implicit grant flow)

• Client secret - choose a a text string with a minimum of 8 characters. This client secret is not used in the current authentication process, but it is required by HIMSA for future use.

Once we receive your submission, HIMSA will send you the required HIMSA App ID as quickly as possible.

Distribution of Manufacturer ID

In order to have existing Noah installations to be aware of your Manufacturer ID you will have to distribute the "globob.stg" for Noah. This is automatically updated with new versions of Noah, but you may experience that your module or app is registered to an older Noah installation. In this case you will have to update the Noah installation - please follow these guidelines.

• Using HIMSA's Noah Mobile AccessLayer, a C# wrapper for the Noah Mobile REST API provided in the Noah Mobile SDK (in the Noah Mobile sample apps). The Noah Mobile Access Layer is written as a Portable Class Library using Xamarin, so it is easy to adapt to multiple platforms such as iOS, Android and Windows.  

• You can also choose to  program your own communication for your app using the Noah Mobile Web API documentation. This method would be preferred if you are, for example, programming a web app using javascript or PHP. You can still use the HIMSA Noah Mobile Access Layer as a reference for programming examples and implementation.

• Your App redirects the user to Noah Server for Authorization: 

• client_id (this is the same as your HIMSA AppID)

• redirect_uri = This is your server-side Redirection URI hosted by the provider or yourself

• response_type = token

• state Optional; Unique identifier to protect against CSRF 

• scope Optional; what data your application can access.

The following is an example Authorization used by the HIMSA Patient Sample module:

• The user must then log into the Noah Server service and grant your App access. The login window is shown to the user with the help of the url shown below.

When the user grants access, the App must then take the code and exchange it for an Access Token using the following information:
 

• client_id (this is the same as your HIMSA AppID)

• client_secret

• code

• redirect_uri

• grant_type = "authorization_code" 

• If the client_id and client_secret are valid, the Noah Server will invoke a callback on the redirect_uri that contains an access_token: 

  • access_token

  • expires_in

Your App must then pull out the access token and use it when querying for data in the API. The access_token is inside of a #hash fragment (as some server side components cannot read this information). You may want to take time to extract other information that is sent along here such as the “state Optional” if it is used in the prior step.

The app will then follow the Redirection URI without the hash fragment.

The app should keep the access token for the Noah Mobile WebAPI secure and delete it when it is no longer required by the client application. An access token is valid for a limited period (determined by HIMSA) from the time it was acquired. 

• A normal Internet connection rate required for all apps - a slow Internet connection will provide unsatisfactory performance.

• An Internet connection is also needed even when the user is using Noah Mobile locally on a LAN. Noah Mobile uses Internet to access Azure so it can resolve the Noah Server IP and redirect URI.

• Local access and Internet access use separate Access Tokens. Your app cannot use a Local Access Token and switch to the Cloud Noah Mobile WebAPI on the fly. Likewise, a Cloud Access Token cannot be used to access the Local Noah Mobile WebAPI.

What’s in the NoahMobile delivery?

The Noah Mobile Software development kit (SDK) includes the following:

• the latest Noah System release

• two C# sample Windows Desktop applications,‘PatientSample’ and ‘EZJournal,' that make use of the AccessLayer to retrieve data from a NoahMobile enabled Noah System.

• The C# source code for the ‘PatientSample’ and ‘EZJournal’ applications

• Note: The HIMSA AccessLayer code for NoahMobile app development is included in the source code of the ‘PatientSample’ and ‘EZJournal’ applications. It is written in C# using Portable Class Library, PCL.

• one example Web App, written using HTML 5, javascript and css web technologies

NOTE: There is no information on designing an App’s user interface or determining an App’s feature set. The source code supplied is for example purposes only.

1. Install Noah System

2. Reboot if prompted to during the installation process.

3. Start Noah System and log in with the default account, 'ABC.'

4. Go to “Setup>Administration>Noah Mobile Configuration” and the following dialog appears.

5. Check the ‘Enable Noah Mobile over the Internet’ feature. (If disabled - you may need to install a Noah license!)

6. Configure a ‘Noah Mobile Alias’. The ‘Noah Mobile Alias’ is a friendly name that can be used by NoahMobile client applications to access the Noah Server.

7. Enter a support email address and click OK.

With the completion of the above steps you have now enabled Noah System to be accessed over the Internet from NoahMobile API based applications. 

Important: The default ‘ABC’ user cannot be used to register a Noah Mobile app. Therefore, you will also need to add a new Noah user with administrator privileges before you can remotely register your Noah Mobile application.

The Noah Mobile cloud infrastructure currently includes the following environments for the development process:

• External Test - when you develop and test new apps or Business Systems  

  • Base API URL: https://apiexttest.noahmobile.net

  • Base Authentication URL: https://authexttest.noahmobile.net

• Production - when you release the finished app or Business System and it is accessible by your end users  

  • Base API URL: https://api.noahmobile.net

  • Base Authentication URL: https://auth.noahmobile.net

For example: https://api.noahmobile.net/api/patients/17/sessions will GET the sessions belonging to the patient with id 17 in the Production environment.

IMPORTANT: The Noah Server and the App must point to the relay in the same environment or they will not be able to communicate.

If you are using the Noah System pre-release version in the Noah Mobile SDK, it will point to the External test environment by default. 

The official Noah release (4.5 and later) on our end user site will point to the Production environment, allowing it to be used by end users. 

You can use the “NoahMobileEnvSelect” on the Noah 4 Mobile Development page to switch environments.  Please look in the top blue box on the right side of the web page.  This box is labeled, "Downloads."   You will want the Environment Selector Tool.

• Make sure that Internet Explorer 10 or later, or a recent version of either the Chrome or Firefox web browser, is installed.

• The PatientSample application requires .NET 4.5 or better is installed.

• When running the PatientSample application for the first time.  Make sure the application runs with administrative privileges.

Assuming a NoahMobile enabled Business System has been installed and is running, see Install and configure Noah System (4.5 or later). It should now be accessible to the PatientSample application.

Double-click on the PatientSample.exe file to start the app. Then enter the ‘Noah Mobile Alias,' that you configured in Noah System, into the ‘Friendly name’ field and press the ‘Discover’ button.

This will allow the application to resolve the identity of the RemoteHost, the Business System being accessed, and access it over the Internet.
Now click the ‘Register’ button to perform the registration of PatientSample application.

Once the app is registered, it will be possible to log in and use the application to retrieve patient and action data.

Note: PatientSample is designed to run against the External Test Environment. If needed to test it against the Production environment, the following code snippet should prove useful. It can be called from a .bat file with elevated access to allow PatientSample to run against the Production Environment. Make sure to correct the "PATH" to the location of PatientSample.exe

echo off
@echo Patient sample using Production
start "" "C:\PATH\PatientSample.exe" -r "https://api.noahmobile.net/" -a "https://auth.noahmobile.net" -c "urn.clientId.aa9c787f-ceed-4002-b661-dda67693908e" -l "prod" -t "MeasurementApp"

Example Usage - Search for a patient, Select, Read the latest Audiogram

• In Noah System 4, create a patient record (e.g. Joe Smith)

• Use the Noah 4 Audiogram module to store a pure tone audiogram (e.g. plot AC curve points for the left and right ear). Save the action

• Open the Patient sample app, select or type in the Noah mobile alias name

• Select Cloud access

• Login (remember that the default user ABC is not supported)

• Click on “Select Patient”

• Search for “Smith”

• Select Joe Smith

Selecting the button “Get Actions for patient” will return the actions that are present

If you would like to see further detail:

• Use the button “Modify Actions”

• click on “Get All Actions”

• Use the pull down menu for Actions and Select the Audiogram action

  • Then select “Read Action” at the bottom of the window

• The public data field will now populate. You can save to file and save as XML.

• make sure that Internet Explorer 10 or later, or a recent version of either the Chrome or Firefox web browser, is installed.

• The EZJournal application requires .NET 4.5 or better is installed.

• When running the EZJournal application for the first time – make sure the application runs with administrative privileges.

Assuming a NoahMobile enabled Business System has been installed and is running.  Please see Install and configure Noah System (4.5 or later).   The Business System should now be accessible to the EZJournal application.

Double-click on the NoahMobileDemo.exe file to start the app. 

To connect to a server, press the “Add New Server” button. Then enter the Noah Mobile Alias, that you configured in Noah System, as the Noah Mobile Service Name. Press the right-arrow or select enter and the app will check if the server name is valid. 

Provided the server name is valid and the right-arrow button has a ‘Green’ background, you can now save the server and “Log in” to it from the previous server browser dialog.

• make sure that Internet Explorer 10 or later, or a recent version of either the Chrome or Firefox web browser, is installed

Assuming a NoahMobile enabled Business System has been installed and is running.  Please see Install and configure Noah System (4.5 or later).  The Business System should now be accessible to the Webapp application.

Double-click on the WebAppHost.exe file to start the app. 

To connect to a server, enter the Noah Mobile alias of the server and press the “Discover” button. 

Provided the server name is valid, you can now “Log in” to it using the "NoahMobile Login" button.

HIMSA strongly recommends that you review the Noah Mobile API Certification Materials early on in your development process.

• You are welcome to use the HIMSA MobileAccessLayer as the accesslayer in your own app.

• You can also use the HIMSA MobileAccessLayer as a reference for programming examples and implementation when programming your own communication with the NoahMobile WebAPI.

1. Discovery - Find desired Noah installation.
   

   • WebAPI: Discovery

   • LAN /Cloud access

2. Authentication- Login and receive token.

   • We provide detailed information on using OAuth 2.0 ‘implicit grant flow’ Authentication with Noah Mobile here.

3. Request Settings/Properties for Noah Installation

   • WebAPI: NoahServerSettings

4. Request data (search/get patient) - 

   1. WebAPI: Patient

   2. Select existing patient or create new patient.

   3. Make changes to patient data if needed.

   4. Select existing action or create new action.

   5. Make changes to action data as necessary. 

5. Log off user (mandatory)

   • With an interface component such as a Button or automatically, a set period of time after the last detected data exchange.

   • You perform a Log off by deleting the access token permanently.

1. Find desired Noah installation.

   • Discover the Remote Host Id using the Noah Mobile Alias

   • The Noah Mobile Alias can be found in the Noah Mobile Setup dialog in Noah.

2. Login and receive token. 

   • To get access to Noah data, the user must login on to Noah through Noah Mobile. The user types his/her usual Noah credentials on the dedicated Noah Mobile authentication site. Authentication is based on OAuth2 Implicit Grant.

   • The outcome of the login process is a token that the application can use to gain access to Noah data.

   • 1. The application opens a web browser, and points it towards the authentication web site.
     2. User types in credentials at the authentication web site.
     3. The browser is redirected to another web site (the “redirect URI” in OAuth terminology). Embedded in the url (address) is the token.
     4. The application extracts the token from the url, and can now use the token to access Noah data. 
     5. The most complex part is “catching” the url after the redirection. This can be done by using a web browser embedded in the app, or an un-embedded webbrowser. Please see below.

3. Register application (if this is the first time you have access the Remote Server). The application must be registered on the Noah installation in order to allow the administrator to decide the Data Access Level. The application should register only once in its lifetime, although it is not harmful to register multiple times.

4. Request Settings for Noah Installation. These will rarely change, so requesting them one time after login should be enough.

5. Select existing patient or create new patient. Create a patient (First and last names are mandatory when creating a new patient) or search for patients that match the search text. Note that there might be an upper limit on the number of patients returned, even though more patients match the search text. This is to prevent overwhelming amounts of data, if the search text is too short.

6. Make changes to patient data if needed. 

7. Select an existing action or create a new action. 
   Note: Referenced actions and public/private data are not included by default in the action returned to the App. This is because this data is often not needed (e.g. when showing a list of actions which the user can choose between). To get these types of data, use GetActionReferences(…), GetActionPublicData(…) and GetActionPrivateData(…) from the MobileAccessLayer, or use the equivalent functions in the WebAPI. 
   A new action can be added by using the CreateAction(…) method. The action will be associated with the session with the same date. If no such exist, a new session will automatically be created.

8. Make changes to action data as necessary. 

9. Repeat process as many times as wished for, by going to step 5 or 7. 

10. Log off. 

    • You perform a Log off by deleting the access token permanently.

Using a non-embedded web browser (This approach is typical for Android and iOS apps):

1. Make your application a Single instance application (if needed).

2. Add a Custom Uri Scheme so your application is automatically opened whenever the browser is redirected to a special url (which could be in reverse domain name notation).

3. Start authentication by going to the authentication URI (or use the AccessLayers InvokeImplicitGrantAuthentication(…) method) to open the authentication web site.
   Now, when the browser is redirected, the browser will (re)open the application again, but since it is a single instance application, the already running application will be passed the url as an argument. Extract the token from the url (or use the Token class’ FromArgs(…) method to extract the token).

Using an embedded web browser (This approach is used by the sample apps provided by HIMSA):

1. Add a web browser to the application.

2. Monitor the event the browser fires when a new site has been loaded.

3. Point the browser toward the address provided the by Access Layers GetImplicitGrantAuthenticationUri(…).
   Now, when the browser is redirected, the monitored event will fire. Get the redirected url from the browser and extract the token (or use the Token class’ FromUri(…) method to extract the token).
   
   Notes:
   • Web browsers should be of a newer date.
   • The application should not remember the token when it closes.

• External Test - when you are developing and testing a new app or a new app version.

  •  Base API URL: https://apiexttest.noahmobile.net

  • Base Authentication URL: https://authexttest.noahmobile.net

• Production - when you release the finished app and it is accessible by your end users  

  • Base API URL: https://api.noahmobile.net

  • Base Authentication URL: https://auth.noahmobile.net

For example: https://api.noahmobile.net/api/patients/17/sessions will GET the sessions belonging to the patient with id 17 in the Production environment.

IMPORTANT: The Noah Server and the App must point to the relay in the same environment or they will not be able to communicate.

If you are using the Noah System pre-release version in the Noah System SDK, it will point to the External test environment by default. We therefore recommend that you use this version during the app development and testing.

The official Noah System release (4.5 and later) on our end user site will point to the Production environment, allowing it to be used by Noah end users. If you are using the official Noah System release, you will need to switch the Noah Server environment to External Test before you use the Noah Server for app development and testing. In order to change the environment for a Noah Server, you should run the Environment Selector tool: “NoahMobileEnvSelect” and select the environment you wish Noah to point to. You choice will be remembered by Noah until you change it again.

When you are ready to release your new app or new app version, be sure to switch from the External Test to the Production environment. Otherwise the app will not be usable by Noah end users.

• Are personal devices allowed? (BYOD – Bring Your Own Device)

• Remote Wipe of corporate data, is this feature needed?

• Remote Wipe of entire device, is this feature needed?

• For more information please see https://en.wikipedia.org/wiki/Mobile_device_management

In general the topic of Mobile Device Management (MDM) will be considered differently depending on the type of and size of the business the Noah end user works for.

Minimum Computing Device Security 

At the very minimum Noah end users need to take responsibility to:

• Enable drive/storage encryption

• Take steps to regulate immediate access to the device (e.g. lock screen with authentication).

For commonly used mobile devices using the iOS or Android operating systems both points above are implemented by enabling the lock screen with password/pin code/biometrics.  When this is enabled then the drive/storage is encrypted and immediate access to the device is also regulated.

For Microsoft PC’s the user will need to enable MS BitLocker (or other similar product) to encrypt the drive/storage.  The user will also need to enable the lock screen with password/biometrics as well.

Q: Is an App developer required to ensure that the end user has taken the above precautions?
A: No, but the developer is strongly encouraged to help promote at least these minimum settings.  Most modern systems do support  methods for checking to see if these tools have been enabled.  If the App is able to make a determination then the App can, and is encouraged to, alert the user to the potential risks they are taking.

HIMSA will also dedicate resources to provide information as well as provide marketing on this subject.

Monitoring for Inactivity

In addition to the minimum device security settings and additional MDM features that should be set by a Noah user HIMSA requires that apps automatically log off a user if the session is deemed to be inactive.  This requirement is in place to provide another fairly standard security approach to safeguard the Noah database

HIMSA’s  requirement is that all apps are responsible to monitor for an inactive session.  If the user is deemed to be inactive then the app will be responsible for logging the user off of Noah.  Inactive means that the user has not performed actions within a number of minutes such as: 

• Moved their mouse or touched the screen

• Entered data

The default number of minutes used to determine an inactive session will be 20 minutes.

Q: Can the app fix the number of minutes lower than the HIMSA set 20 minutes?
A: Yes.

Q: Can the app display a preemptive message before the session expires?
A: Yes, and the user can respond as long as the session time has not been exceeded.  For example, at 19 minutes of inactivity the app could display a message “Your connection to Noah is about to end due to inactivity, would you like to continue?”, if the user indicates “yes” then the user can continue without needing to be authenticated.

Q: Can the app allow the user to change this default behavior?
A: Yes, the app can allow the user to set the number of minutes to be 1 to unlimited.  However, the access token that is granted when first logging in will only, as currently set, be useable for 4 hours so at some point the user will be asked to log in no matter if their session is deemed active or not by the app.
 
If a hearing care professional wishes to take advantage of an apps optional offering to allow the session timeout to be longer than 20 minutes, then setting up the minimum computing device security features will become even more important.

Q: What should the app do in the event that session is expired and there is unsaved data?
A: HIMSA’s suggestion is that the app save the data to Noah and then indicate that the data was saved due to session inactivity (e.g. add helpful text to the action description or other means). 
 

Q: Can the default inactivity timer be set to 30 minutes or more?
A: No, the default inactivity cannot be changed to 30 minutes or more.

Web Browser Autocomplete Considerations

Before an app can interact with Noah it must receive an access token and this process is facilitated by the app asking the Noah authentication server login GUI to be made available to the HCP.  This GUI is implemented as an HTML page and will be shown to the user by a web browser installed on the device.

Depending in the web browser and other possible browser settings the HCP may or may not be able to save the user name and password.  

The HCP will need to take responsibility as to whether the passwords should be remembered or not.  

HIMSA and member companies will both need to promote the use of good security choices so that HCP's can set their balance between ease of use and appropriate security.

If a HCP is to allow auto completion to occur then it would be recommended that it only be allowed when the computing device is only used by 1 HCP, or the device supports individual logins for HCP's, and, that a screen locking tool is in place and activated. 

Other Related Topics

Apps are also required to provide the following authentication related items:

• A GUI item to log off.  When selected by the user the app will not be able to interact with Noah until being authenticated again.  It is, of course, O.K. to confirm with the user first (e.g. check for unsaved data).

• As currently implemented Noah System does not require a “strong password” be used to gain access to Noah mobile functionality.  HIMSA does have plans to change this in a near future release where a strong password will be required for a Noah user to use the relay service.  HIMSA feels that it is very standard practice today to require this type of password on any typical web site.

• Noah Mobile opens the level of access to patient’s records. It is important that Hearing Care Professionals (HCP’s) feel that their patient data remains private.

• The introduction of the Noah Mobile Relay service to remotely connect computing devices (e.g. tablets) to Hearing Care Professional Businesses (HCPB’s) does raise the bar in regards to ensuring that HIMSA’s overall security plan for Noah is well thought out.

Reader’s prerequisite - please read “App Development Categories” before the content in this document.  The explanation of category types (user interactive vs. service) is essential.

REVIEWING AND USING DATA CREATED BY OTHER HEARING INSTRUMENT MANUFACTURERS

Today, with modules, it is possible for Manufacturer A to see that there is a fitting record for Manufacture B for a given selected patient. Module A cannot read the fitting data as it is not standardized and as there is only one patient selected, it is hard to imagine misuse of data (e.g. learning about the HCPB practices).

With Noah mobile, apps will have the technical ability to see other manufacturer activity across many patients. It was once considered if Noah should hide data, such as Manufacturer B created data from A, but that idea was rejected by the hearing instrument manufacturers. Including data hiding rules would then have adverse usability aspects such as:

• Manufacturer A’s app would not be able to look for the presence of previous hearing instrument selections (from other manufacturers). Without this ability, the app would not be able to determine in an automated fashion, that the patient is not a first time instrument user.

• It is envisioned that many apps will show a list of patient activity after a patient has been selected – something similar to what the Noah 4 session browser showstoday. Without having access to all actions, it would be impossible for the app create the complete session history and it is felt that many HPC’s would find this confusing, some may feel that the app is not working correctly. An app developer is prohibited to use other licenses fitting actions for the purpose of getting information on competitors’ business.

DATA ACCESS CONTROLS AVAILABLE TO THE HCPB

The HCPB has the following tools available to control access to their data:
 

• They will have the ability to first grant that an app has access to the data in Noah; the app has to be approved by a Noah user having administrative privileges.

• The HCPB can also restrict access to the amount of patient demographic data that is available to the app.

• Logging of all data access is supported by an extensive audit trail system. The audit trail system provides the HCP with the ability to review data access as monitored by Noah. This is seen as the most effective tool to help ensure that app developers are accessing and using the data contained in Noah correctly.  The Noah mobile API SDK documentation will also mention the fact that all access is being tracked and can be reviewed by the HCP. This should provide as a natural deterrent to data misuse.

Please see the user stories available in section 2.X of the Noah Mobile user story collection for more information.

OVERVIEW OF USE OF COPIED DATA

Once an app has gained access to a piece of data it then has the technical ability to use it to create another piece of data. A prime example of this would be that of a fitting module reading a pure tone audiogram in order to create a fitting action.

Who is the owner of the data? HIMSA assumes that the true owner of the data is the HCPB that ran the software which created the resulting data. The concept of ownership can become confusing depending on the data consumer’s point of view.

If the app does copy data, then the real important aspect is how properly the data is controlled once it has been copied.

In order to make this simple for all parties to follow HIMSA will design policies which deal with data that is copied. HIMSA believes that all member companies do want to handle data in an ethical and legal manner. These policies are not written with the assumption that a member will at some point misuse data but, rather, to address the topic that is on everybody’s mind these days. It is wise to have good policies in place to help deter any misuse. If one company misuses data, then there is a very good chance that HCP’s will lose trust in the complete system thus affecting all member companies relying on Noah Mobile.

Default use of data restrictions

Rather than focusing on the ownership of data the following default data restrictions will be in place for all apps.
In general an app can copy data to different computing systems but in a restrictive manner. The data can be copied for its stated intended use and nothing else.

Apps are not allowed to copy data except in the following situations:

1. Explicit notification of data copy. The app clearly makes it known in the GUI that the data will be transferred to another system and for what purpose.

2. Implicit notification of data copy. Through the use of the app it is reasonably obvious to a HCP that the data will be transferred to another system. Examples being:
   1. A browser based order app where the pure tone audiogram is needed as part of the order and is shown on the order form. The audiogram was copied to the server hosting the browser based page.
   2. An Android based app running on a tablet may read all actions for a selected patient record so that it can create a list of past activity and then create a session list similar to what Noah System provides today. In this case it is assumed that the app will have a copy of the data on the device in order to display the data.
   3. A synchronization feature where the app will copy all or large subsets of patient data for use when the app does not have the possibility to be connected to Noah.

3. Service apps can work in an automated fashion as an interactive user is not necessarily watching what is going on. HIMSA will require contractual assurances that the service app developer clearly state to their users, in writing, how they use the data collected.

4. Data copied by A, B, and C above cannot be used for any other purpose then originally copied for. This also means that even if the data is patient de-identified (i.e. name is stripped off) it still cannot be used for any other purpose. Using the order app – audiogram example above, this would mean that the company copying the audiogram could not combine this audiogram with other patient audiograms to run analysis on hearing loss vs. types of instruments ordered.
   a. Note: Please keep in mind that most countries today have strict rules on the use of patient related data (e.g. HIPAA). These rules will also act as a very powerful deterrent from inappropriate use of data. However, once data has become de-identified HIPAA no longer applies.

5. The HIMSA certification process will be fashioned to ask for details about what data might be copied out of Noah and then verify that either A, B, or C is met. HIMSA will not be able to test for the compliance on this particular point but will rather ask the member company to document the use of this data. HIMSA assumes that the member company will provide the users with a EULA or reference to some other document which outlines the apps use of data.

6. What happens if somebody breaks the rules? What happens if a member company uses data (or data in a manner not approved by the HCPB)? Besides the HCPB taking whatever action it feels is necessary, HIMSA will reserve the right to consider options such as:
   a. Revoking certification of the app(s) involved
   b. Blocking the app from using the HIMSA provided cloud services.

Special provisions for use of data? 
Q: Can an app developer make an agreement (e.g. a contractual agreement) with an HCPB to gather (copy) and use the copied data for other uses, compared to default restrictions listed above?
A: Yes, as long as the end user is aware that this activity is taking place, then this is a business relationship issue between the app developer and the HCPB.
 

STATES OF DATA – AUDIT TRAIL AND DATA PROTECTION

Data is often considered to be in 1 of 3 states from an IT perspective: Data in use, motion and rest. To aid in this next section the following definitions are used: 

• Data in motion / data that is being moved across a network or computer memory with the understanding that it will be read or updated.

• Data in use / data that is ready to be read or potentially updated

• Data at rest / data that is not in use, or no intention of use. The data is stored as an archive. In the case of Noah mobile, “data at rest” is not considered as Noah does not provide a feature to archive data out of the Noah database. All data is in the database and could be called up by Noah or a module/app at any time – it is considered “Data at rest”.

 
Data will be in motion as an app reads and writes data with Noah. In this case Noah has the responsibility to exchange the data in a secure method (e.g. https). Apps do not have any special requirements to fulfill.

The main focus is the “data in use”. In the context of this section both data protection and the audit trail are of particular interest.

Today, with modules, this topic is not as important as the module which is running on the same physical computer that the Noah software is and the data being exchanged is done so in the computer’s memory, then transferred across the internal network, encrypted, and then stored in a database on a Windows computer.

It is also recommended that the computer holding the database have its drive encrypted if the computer is found to have any reasonable risk of loss or theft. Click here for more details. 

If the app is integrating with Noah using the Noah mobile API, then it does expose itself to performing more tasks that were taken care of by Windows or Noah.
 
Requirement – “data in use” must be encrypted or the HCP must have a way to enable a situation where the database be encrypted.  Examples of this would be:

• HIMSA’s recommendation for PC laptops is to enable drive encryption. 

• iOS provides encryption, see https://support.apple.com/en-us/HT202064

Why? In general it is standard data security practice but it becomes more important for portable devices such as laptop and tablets. Being portable increases the chance of loss or theft. Loss of a device with patient related data, not encrypted, would be a severe violation of security mandates (e.g. HIPAA).

What does this mean to an app developer?

• If “data in use” is used in the app then it should be encrypted if it resides on the device.   The app developer should strongly encourage the use of an encryption method they feel is appropriate for their users. HIMSA will also spend time creating support documentation on this topic for the common devices known to be used.

• It is highly suggested that any data obtained from Noah and “in use” in an app should be completely deleted/destroyed from that app immediately after use. If this method is followed, and the data obtained was not copied elsewhere, then the Audit trail requirements will be fulfilled – see US 2.03 “Recording Access to Patient Data” for more details.

• If the app does leave any of the data obtained from Noah in the app after use then the app developer has the responsibility to track which user(s) later adds data, reads, or updates any of the data – essentially the app will need to recreate the features discussed in US 2.0.3 or use the features support via the Noah mobile API to facilitate these features.

  • For example,  an iOS based app provides features to synchronize data between data stored in the Noah database and the app. The app will need to provide an authentication method as well as track the items listed in 2.0.3. The Noah audit trail be added by the app at a centralized location but the app still has the responsibility to watch for the events that need to be recorded.

Q: Why does HIMSA list the above as a requirement?
A: HIMSA would like to ensure that the same level of data security that is available today with Windows based modules are not decreased with the Noah mobile API. HCP’s place a lot of faith in storing and securing their data correctly and just assume that this will always be the case.

Web API version

A Web API version is identified by a major and minor version number i.e. <major>.<minor> e.g. 1.1.

• Breaking changes e.g. behavioral modifications - will cause the higher major version number to be increased. This should happen very rarely. Another type of breaking change is the end-of-life support for a specific version of the Web API.

• Non-breaking changes e.g. extensions – will cause the minor API version number to be increased. Non-breaking changes are new resources or extending existing Responses.

• If a remote host (the Noah Server) supports version 1.n the remote host will also support all versions less than n.

• Over time, the support for old versions may stop when accessing the remote host through the cloud. Even if an old version cannot be accessed through the cloud, it can still be accessed locally.

• The data returned from the discovery call has been extended to include the versions supported by the remote host. The versions will be returned as <1.n>, <2.m> etc. 

• When calling the Web API the application must specify the version that the application is developed against. The version is stored in the request header identified by “api-version”. If the remote host does not support the function a NoahMobileFault response is returned with error code 60065.

• In a reply, the version number of the Web API is stored in the reply header identified by “api-version”.

• Apps must handle responses that are returned using a higher or lower version than the version requested by the App. This means that an application may receive less or more data than expected by the version that the App is developed against as the remote host always will return the data that match the version of the Web API. 

• If accessing a remote host, that supports an older version of the Web API, through the cloud the response will contain the full response (the response in sky cloud may contain more data than the remote can provide) the App developer must neglect the data that not supported by the remote host Web API version.

In general an App developer must take into account that even though the App is developed against a specific version of the Web API, the App will properly connect to Web API’s with a different version and must handle this properly.

For example, strict serialization techniques can be unnecessarily intolerant of change. A more tolerant reader should only be concerned with data that it needs and ignore every other part of the response. This means that the majority of changes are unlikely to break the integration.
 

Handling responses correctly in Apps

When an App requests data via NoahMobile, the App specifies its own api version, however the response received by the App may be provided using a different api-version. It is very important that the app is very tolerant of the received data structures and can handle such responses.

The App should be able to handle the following scenarios:

1. The App’s api-version is less than the received one of the received data structure.
   • Assuming the App only has knowledge of data structures represented by api-version 1.5 or earlier and receives a data structure provided using api-version 1.7.
   Then the App must disregard all received properties that are unknown to api-version 1.5 data structures. This means that the App would have to ignore the ‘middleName’ and ‘Phone’ properties, see the Figure Below.

2. The App’s api-version is greater than the received one of the received data structure.
   • Assuming the App only has knowledge of data structures represented by api-version 1.5 or earlier and receives a data structure provided using api-version 1.4.
   Then the App must disregard all received properties that are not part of api-version 1.4 data structure. This means that the App would have to ignore the ‘zipCode’ property (See Figure 1).

3. The App’s api-version is equal to the received one.
   • Assuming the App only has knowledge of data structures represented by api-version 1.5 or earlier and receives a data structure provided using api-version 1.5.
   Then the App can use all received properties.

Figure: Sample data structure evolving from api-version 1.4 to 1.7

Version Schedules

The general rule is that an API is supported for at least 2 years, and that it will follow the Noah version it was released with. The specific end of support will be announced in the Platform strategy document.

For SDKs a version will always remain available as a downloadable package. However, if it is beyond its end-of-life date it may rely upon APIs or methods which no longer work, so you should assume an end-of-life SDK is no longer functional.