Noah 4 Business System Developers Guide Full Document
detailed information on the Noah 4 architecture
a summary of the tasks needed to integrate a business system to Noah 4.
Noah 4 Architecture
The following figure shows a logical view of Noah 4, with the focus placed on the Noah Client side, which will be of particular interest to the business system developer.
Figure: Noah 4 logical view
The Noah 4 system can be divided into 6 logical groups:
1 Business API
2 Module API
3 NOAH 3 Module Server
4 NOAH 2 Module Server and wrapper
5 Noah 4 Client
6 Noah 4 Server
One of the objectives of Noah 4 is to convert as much as possible from COM to .NET components. However, some COM remains due to the requirements of backwards compatibility. It is also a requirement that the HIMSA development platform should be the latest Visual Studio version.
The Module API
The ModuleAPI is very like the Business API, with both servers implementing almost the same object model for handling the business logic; the difference lies in the methods implemented by each API. The way in which the Module API is embedded into a module and used by Noah 4 modules is the same as for a business system.
NOAH 3 Module Server
NOAH 3 has been provided with complete backwards compatibility. The NoahClientProxy.dll converts all COM traffic from the NOAH 3 Module Server.dll into .NET, which can then be interfaced to Noah client. The NoahClientProxy.dll has support for all NOAH 3 methods.
NOAH 2 Module Server and Wrapper
In the case of NOAH 2 modules the components have been copied from latest NOAH 3.
The blue processes are all copied from NOAH 3 and ensure that the legacy system is in place and working for all NOAH 2 modules. Do note that NOAH 2 modules do not work on 64-bit operating systems, as they use 16 bit components.
Noah Client
Noah Client will normally not be visible to the end user since it is implemented as a Windows service. Noah Client will be responsible for keeping track of registered modules on the workstation and regulating the number of modules that are simultaneously connected to Noah on the same workstation. Furthermore Noah Client will buffer the most used server data in order to reduce network traffic and make faster access to data for the business systems and modules. Noah Client also acts as a communication concentrator between business server/modules and the server i.e. all communication between processes running on the client PC and the server will pass through Noah Client (this is not the whole truth as business systems may access Noah data without going through Noah if they provide their own database interface).
Noah Server
Noah Server has a number of tasks to perform;
Database access
License evaluation
Globob maintenance
Event distribution to attached Noah Clients
It is important to notice that Noah Server acts for the attached Noah Clients in the same way as the Noah Clients act for any attached business system or module . Thus, Noah Server distributes events to attached Noah Clients. These events are broadcast to all attached Clients besides the Client originating the event.
Figure: Business System Integration Model – Business System Owns Noah Data
The Database interface, to be delivered by the business system developer, must be a .NET 4.0 CLS-compliant interface, also referred to as a managed database interface.
Business system developers should choose this setup if the business system needs to be able to work actively with Noah data in order to, for example, add an action to the Noah data, display more sophisticated data such as audiograms or fittings for more than one patient at a time, or compare several audiograms for one patient.
This setup gives the business system total control of the database environment, backup strategies and other database settings.
creating an interface between Noah and the business system database.
creating an interface between Noah Business API and the business system.
deciding on the use of Noah 4 optional components
Creating a Database Interface for Noah 4
In order for NOAH to store and retrieve NOAH compatible data in the developer’s business system database, it is necessary to create a NOAH database interface. HIMSA also provides the software program Noah 4 Database Tester, which can be used to test the developer’s Noah 4 compatible database. For information on using the Noah 4 Database Tester software, please refer to the Noah 4 Database Tester software documentation,
A business system should also be able to import NOAH 2 and NOAH System 3 databases into the business system’s own database via a Nha formatted file.
Interfacing Between Noah and The Business System
The Business API dll assembly provides the interface between the Business system and the Noah Client running on each workstation. Business system developers can use the business API component in a variety of ways, based on the design of the business system, but be aware that the BusinessAPI is the only interface to Noah 4 available for Business System developers.
For more information on the BusinessAPI component object module, refer to Business API. For code examples, refer to Required Programming Tasks.
In addition, a business system must connect to the Noah License Server component. For more information on this component, refer to Business API.
Before an application can access Noah the application must register with respect to Noah Client. If the application is not registered, Noah Client will prevent the application from connecting to Noah. It is not a rule that three different applications should be registered with respect to Noah. One application can be registered as all three types. More than one application can be registered as the same type, but Noah Client only allows one of the applications to connect to Noah Client. This application is the preferred application of that type.
Noah Client will always have a preferred user manager, patient manager and business system.
The user manager handles users and user login. The user manager must provide functionality that enables Noah Client to request the User Manager to login and, upon successful login, the User Manager will return a user id to Noah Client, which is the logged-in user with respect to Noah. Please note that users and user logins are handled and owned by the business system and are not handled by Noah even though Noah has a need for a logged-in user. If Noah Client has a need for a logged-in user it will request the User Manager for it. If no user managers are running, Noah Client will start the preferred User Manager and request it for a user, which will be the logged-in user with respect to Noah. This could happen if a module connects to Noah Client and no user is logged in. The User manager will typically close after the user has been returned to Noah Client.
The patient manager handles patients. The Patient Manager must provide functionality that enables Noah Client to request a patient from it, which will be set as the current patient. Be aware that the patient is handled and owned by the Business System. A module can request Noah Client to set a new patient as the current patient. In that case Noah Client requests the Patient Manager for a patient, which will be set as the current patient. If no Patient Manager is running, Noah Client will start the preferred manager, which after returning a patient to Noah Client typically will close.
The static method RegisterNoahApp() on the BusinessAPI class must be used to register the preferred application(s) in Noah (see the BusinessAPI NameSpace in the BusinessAPI.chm file).
Additional Components
HIMSA provides licensee developers with additional components that can be used to simplify the process of interfacing to NOAH 4. These components are among others the Session Browser and Patient Banner.
Business system developers are welcome to use these components, or to develop their own programming solutions.
The database interface is necessary for the Noah 4 system to communicate with a Business System vendor’s database. A description of the objects used by Noah when interfacing to its own database is supplied. Developers can use this as a reference when designing their own database interface.
Required Data Fields
The tables below only list information relevant to the Noah 4 Managed Database Interface. The issue of inter-table relations has not been considered. The information listed in these tables should only be considered as an absolute minimum set of fields; it is possible, of course, to choose to have as many fields in the database as are deemed necessary.
NOTE: Some of the methods could potentially corrupt the relational integrity of the database. It is the implementers’ responsibility to prevent this.
Patient Table | ||
Field | Type | Description |
ID | Int32 | Unique (within the database) Patient identifier |
PatientGUID | Guid | Global unique patient identifier |
ActivePatient | Short | 1=true, 0 = false |
PatientNo | String(20) | Dispenser’s Patient identification |
CreateDate | DateTime | Date of record creation |
FirstName | String(30) | Patient’s First Name |
LastName | String(30) | Patient’s Last Name |
MiddleName | String(30) | Patient’s Middle Name |
Gender | Short (enum) | Patient’s Gender {0=Unknown,1=Male,2=Female} |
BirthDate | DateTime | Patient’s Birth date |
Salutation | String(30) | Salutation |
Title | String(30) | Title |
Address1 | String(30) | Address line 1 |
Address2 | String(30) | Address line 2 |
Address3 | String(30) | Address line 3 |
Province | String(30) | Province or State |
Zip | String(20) | Zip Code |
City | String(30) | City |
Country | String(30) | Country |
|
|
|
HomePhone | String(30) | Home phone |
WorkPhone | String(30) | Work phone |
MobilePhone | String(30) | Mobile phone |
String(50) | ||
SSNumber | String(20) | Social security number |
Physician | String(30) | Main Physician |
Referral | String(30) | Physician being referred to |
Insurance1 | String(30) | Insurance information |
Insurance2 | String(30) | Insurance information |
Other1 | String(30) | Other 1 |
Other2 | String(30) | Other 2 |
NOTE : The setup tables below, for both user and patient, store setup data as BLOB files. The setup data consist of user, or patient, preferences. For example, NOAHaud stores profile settings as User Setup data. Thus, if a user moves to a different workstation in a network, the user’s specific profile-settings are automatically transferred to that workstation.
Patient Setup Table | ||
Field | Type | Description |
PatientID | Int32 | ID of associated patient (> patient table) |
ModuleID | Int32 | ID of module that added this setup |
SetupData | BLOB | Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxSetupBlobSize |
User Table | ||
Field | Type | Description |
UserID | Int32 | Unique identifier for user |
CreateDate | DateTime | Date of record creation |
UserInitials | String(3) | Three letter initials used for logon |
UserName | String(30) | Full user name |
Action Table | ||
Field Name | Type | Description |
ID | Int32 | Unique identifier for action (NOTE: An Action object holds information about an action performed during a patient’s visit. In addition to the actual action data, an Action object contains information about what kind of action it is, what user created it, a description of the action and a reference to an Actions collection of referenced actions. A reference, which is of type long, holds an ActionID of the action it is referencing. ActionReferences link, for example, audiograms to selections/fittings.) |
SessionID | Int32 | ID of session in which the action belongs (> session) |
UserID | Int32 | ID of user who created the action (> user table)* |
CreateDate | DateTime | Date of creation |
LastModifiedDate | DateTime | Date of last modification |
Description | String(64) | Description of the action |
ModuleID | Int32 | ID of module that created the action |
DeviceType | Short | Module specific code for external equipment |
DataTypeCode | Short | Code describing the action |
DataFmtStd | Short | Code describing the format of the PublicData field |
DataFmtExt | Short | Code describing the format of the private part of the PublicData field |
Removed | BOOL | Action marked as removed |
Hidden | BOOL | Action marked as hidden |
PublicBlob | BLOB | Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxBigBlobSize |
PrivateBlob | BLOB | Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxSmallBlobSize |
ActionGroup | DateTime | Value used for Action grouping. |
*Action records must not be deleted if the referenced user is deleted.
Session Table | ||
Field Name | Type | Description |
ID | Int32 | Unique identifier for session |
PatientID | Int32 | ID of patient the session belongs to (> patient table) |
CreateDate | DateTime | Date of creation (when first action was added) |
FastView Table | ||
Field Name | Type | Description |
ActionID | Int32 | The ID of the action this FastView is related to |
LastModifiedDate | Int32 | Date of last modification |
CreateDate | DateTime | Date of creation |
Data | BLOB | Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxFastViewBlobSize |
Format | Int32 | Pdf = 1, Rtf = 2, Jpg = 3 |
Version | Int32 | Version |
The Business API Object
The BusinessAPI object is the top-level object in the Noah Object Model. This means that references to all other objects must take place through the Business API.
It is the responsibility of the Business system to inform Noah of changes in the current user and currently
selected patient (by calling the methods SetCurrentUserID and SetCurrentPatientID). Given this information, Noah offers the Business system a hierarchy of objects that reflects the current patient’s sessions and data along with a framework for the handling of modules’ access to the data (e.g., start/stop/uninstall).
The object hierarchy can be depicted as shown in the following figure.
NOTE: Noah always reflects the current user and the current patient (if any) as set by the Business system.
Figure: Business API object hierarchy
The Noah object Hierarchy describes the relation between objects in Noah.
The key concept in the Noah Object Hierarchy is the Session List associated with the current patient. The
Session List is an ordered collection of sessions for the current patient.
A Session is an ordered collection of actions, each representing an event that occurred during a patient session. The most recent patient session is the current session, that is, the session that reflects the events in the patient’s current visit.
NOTE: HIMSA provides a collection of different WPF controls, which uses MVVM design pattern, that can be used by the Business system developers.
HIMSA also provides the Active Document Container used to host NOAH 3 (and 2) modules. The Hosting of modules has, in Noah 4, been moved from the responsibility of the Business system, to be a part of the Noah 4 Framework components.
The Noah 4 object model has been divided into 4 logical entities:
Engine objects
Business/Office database objects
Registry objects
System database object
Engine Objects
The objects that are defined as Engine objects in the Object hierarchy figure are objects which embed standalone Business API functionality, such as a session filter and a module filter. This functionality can be used by business systems in order to filter the collection viewed. For detailed object descriptions, property and method information please refer to BusinessAPI NameSpace in the BusinessAPI.chm file.
Business System Database
The Business System database objects (marked in green in the Object model) are the most dynamic objects in the model, and are updated based on the event generated by the business system or any Noah module executed on the same Noah client instance on the given PC.
The Business system objects hold information on the current user logged onto the Business API, and also information on the currently selected patient, including sessions and actions covering all the consultations for the patient in question and with detailed data – e.g., audio, fitting and journal. For detailed object descriptions, property and method information please refer to BusinessAPI NameSpace in the BusinessAPI.chm file.
The group of Business Database objects feeds the following collection properties, which are available on the Business API object:
CurrentUser
CurrentPatient
CurrentSession
Unbound Actions
Registration Objects
The Registration objects hold information regarding the modules installed, which modules are Noah compatible and where the registration process has been executed for the module. Furthermore, it is possible to initiate a start or connect and a stop or disconnect for a specific module. The registration entity is also able to supply data on what the module can make and/or show, and which protocol it supports.
The group of Registration objects feeds the following collection properties, which are available on the Business API object:
Modules
ActionConverters
The Noah License Object
The Noah Engine contains a licensing system that controls run-time access. The file, demo4.lf, provided with the Noah installation, allows the customer access to the Noah Engine for a 45-day trial period. The business system can read how many days remain in the trial period using the Noah license interface. The Business system can then use this information to inform the user. In order to permanently enable Noah for a customer’s business system installation, the developer’s company or the company’s distributor will need to purchase a Noah Engine license from HIMSA, and supply a variety of user information, including:
Office Name
Street Address
City
State or Province
Zip or Postal Code
Country
Telephone Number
If upgrading from NOAH 2 or NOAH 3, the Noah serial number must be provided, along with the network license size (1-2 user, 3-6 user, unlimited user). HIMSA will use this information to generate a license file, noah4.lf, that is unique to the user. HIMSA will supply the license file to the distributor/company or to the end user. The file must then be copied to the user’s system(s). The noah4.lf file must be installed in the HIMSA Shared folder.
NOTE: The noah4.lf file may be acquired prior to the initial installation and then installed in place of demo4.lf.
Starting and Closing or Disconnecting Modules
This section describes the flow and different features available in the Business API which facilitate the launching, connecting and closing or disconnecting of a Noah module.
Overview
Noah 4 supports modules developed for Noah versions 2, 3 and 4 (except for NOAH 2 modules on 64 bit OS), which means that Noah 4 Business API together with Noah Client supplies the same functionality for launching and closing NOAH 2 and 3 modules as was available in previous versions of Noah.
For NOAH 3 based modules an Active Document Container is supplied by Noah, but the Noah 4 modules must be standalone exe files which can be launched from either a business system or a computer desktop. Noah will not be the host of the Noah 4 module process, which also means that it will not be possible to close Noah 4 modules directly merely by disconnecting them from the Noah Client.
Noah Client will keep track of the version of the actual Noah module installed on a PC. This information is used by the Business API to handle the launching differently (i.e., by executing as exe or within an Active document container). The business system developer should not be concerned about this, whether the module is a NOAH 2, NOAH 3 or Noah 4 module. It is launched by calling the same method. The difference lies within the closing or disconnecting functionality, for Noah 4 modules the Noah Client will only disconnect the module.
When a Business API is initiated it will query Noah Client for information on which modules are installed, and will also receive a list of module instances that are running for each module installed. The list of running modules consists of the following information:
an integer RunningModuleHandle which is unique to the installation and generated by Noah Client.
the ModuleID which links the running instance to an installed module.
The Business API is kept up to date regarding the status of the running module by the events, ModuleConnected and ModuleDisconnected.
Starting a Module
A module is launched from the Business API, or directly from the desktop, by starting the module exe or though an Active Document container depending on the Noah version of the module. Refer to the following figure:
Figure: Starting a module
In order for the module to be launched from a business system the method LaunchWithAction must be called. This method is located on the Module object, and takes one argument, which is either a formatted Noah Business API action 3 object or NULL. If the formatted action module is given, then the action ID will be given as the startup parameter to the module. This can then load a desired action which can be altered or used as a template for a new action.
For detailed information on the methods and objects please refer to BusinessAPI NameSpace in the BusinessAPI.chm file.
The Noah 4 architecture is event-based. In order to fulfil this requirement, it will be necessary to find a way to automatically pass information from a thread’s current call context to any thread that has been spawned from this thread.
This is solved in Noah by the implementation of a method which can carry the information to Noah Server. The information can then be obtained by the managed database interface. In all cases, every managed database interface must abide by the standard method signature. The managed database interface can freely choose to use the information or not. The functionality is made available for the Business Systems by the exposure of public property in the Business API, where the information can be set. (NoahCallContext) The picture in General Purpose Data Porter shows the principle flow of the call context header information (NOTE: The green component is Noah 4 and the pink is a given Business system).
The data the GPDP ports should be data which does not need any validation from Noah or ratification by Noah business rules. It could be external information on a patient, such as payment terms, etc.
The advantage for the Business System is that it can utilize the .NET remoting functionality, which is already in place for the Business System. The Business System developer does not need to consider how to transport data to a given Server, merely implement the needed methods in his managed database dll, which can receive or save the data. Furthermore, is it possible to save/query data to your database, which is not strictly inside the boundaries of the data definitions of Noah.
In Noah 4 the method in the Business API, which has to be used for GPDP functionality, is named HandleNoahDataWrapper and takes a ref object as argument. The developer can then wrap the data in the object argument and unwrap it on the server side. When the call is executed the Ref statement ensures that the Business system developer can receive an altered object which, for example, could indicate if the call was successful.
The figure below shows the principal flow of GPDP – note that the GPDP, in contrast to the Context header, can contain a huge amount of data and that the context header information can be used in conjunction with GPDP.
How to use the GPDP in your own Business system
It is possible to put GPDP into operation by implementing your own command set and serialized objects. In each case it is important that the BusinessAPI and the Database Interface assembly (and Noah Client for serilization) have unlimited access to the command set and serialized object definitions dll (see picture below). This implies that your custom command set for GPDP must be placed in the GAC of the PC.
How to make your own command set for GPDP
In order to implement your own GPDP command set and objects passing, you must create an assembly, which is known to both your database interface assembly and the BusinessAPI dll, as shown below. This is an extract of the Sample Business System that is downloadable from the Noah 4 Business System page on himsa.com. The request or command is wrapped in the Noah4systemCommand, whose property Data holds the serializable object or objects passed to and from the database interface assembly. It is recommended that your command set is located in its own Dll assembly and that you place this assembly in the GAC of the PC, which is to use your database assembly.
namespace NoahDatabaseCoreCeSample_CommandEnum
{
public class GPDP
{
public enum YourBusinessSystemCommandEnum
{
ValidateUser,
IsLoginSystemEnabled,
GetUsers,
GetUser,
DeleteUser,
PutUser,
GetRoles,
GetDefaultRoles,
GetRole,
GetRoleFromUserID,
PutRole,
GetPatients,
GetPatientsCount,
GetPatient,
PutPatient,
DeletePatient,
GetPatientComment,
PutPatientComment,
GetDatabaseProperties,
SetLoginSystemInf,
GetLoginSystemInf
}
[Serializable]
public class YourBusinessSystemCommand
{
public YourBusinessSystemCommandEnum Command { get; set; }
public bool SkipSendEvent; // Skipping sending notification
(PutPatient when importing) Default is to Send notifications
public object Data;
}
}
[Serializable]
public class Noah4User
{
public int ID;
public string Initials;
public string Password;
public DateTime CreateDate;
public string Name;
public int Rights;
public string UserName;
public DateTime LastChangedPswd;
public bool UserActive;
}
[Serializable]
public class Noah4ValidateUser
{
public string UserName { get; set; }
public int PasswordHashCode { get; set; }
public bool ValidatePassword { get; set; }
}
}
}
1. This feature can be disabled by the Business System. By setting the ‘EditOldActionsAllowed’ property to false. The property is in the BusinessAPI and the default is set to true.
2. The Action cannot be edited if it is referenced by another Action.
In the following two examples we will assume that the Action we are editing isn't referenced by another Action and the Business System allows Actions to be edited beyond the current calendar day.
Example 1) What happens in Noah 4 if an Action from the current calendar day is edited?
In this case, the Noah 4 behavior is identical to NOAH 3.
Example 2) What will happen if an Action not belonging to the current calendar day is edited?
In this case, Noah 4 will create an ‘Archived Action’ which is a clone of the unmodified Action. Noah 4 will create a new Action with the updated information and also a new action id. The new Action with the updated information will be added to the Session of the edited Action.
Archived Actions cannot be edited themselves.
In the following example we will assume that either the Action we are editing is referenced by another Action and/or the Business System doesn’t allow Actions to be edited beyond the current calendar day.
Example 3) What will happen if an attempt to edit the Action is made?
In this case, Noah 4 will create an ‘Archived Action’ which is a clone of the unmodified Action. This ‘Archived Action’ will no longer be accessible via the Session to which it originally belonged. Next Noah 4 will create a new Action reflecting the content of the unmodified Action apart from action id and the updated information. This new Action with the updated information will now be added to the Session of the edited Action.
These tasks include:
Initializing
o Setting the user
o Setting the patient
o Setting the language id
Event handling
o Cross threading issue
Launching/Connecting to and disconnecting from a NOAH 2/3 module.
Error handling
o Noah 4 exceptions
IMPORTANT: The code in these examples consists of extracts from the sample business system made by HIMSA. This means that the code is for illustration purposes only, and cannot be used directly as written in the developers business system implementation. The full sample code for this business system is available on Noah 4 Business System Development page on himsa.com.
Initializing the Business API
In order to get started, the Business API assembly dll must be installed on the development PC. This dll comes with the Noah 4 installation.
Figure: BusinessAPI.dll
The first step is to reference the dll in your development environment. If you are using Visual Studio 2010 this is done by opening your References folder, selecting the popup menu Add, and browsing to BusinessAPI.dll. This Dll will give a number of classes/objects which re-sample the object model and which the developer can use in the development of the business system. The figure below shows the Object browser in VS2010, which gives an overview for the Business API referenced.
Figure: Object browser in VS2010
The first step in order to use the BusinessAPI is to Register BusinessAPI instance with Noah before it tries to connect. Noah Apps will only be allowed to connect to Noah if they are set as the preferred apps of any of Noah AppType as part of registration. Therefore, we register BusinessAPI instance as preferred app.
Below is a sample Register class that contains Install() and Uninstall methods that register and unregister app towards Noah.
Note: The business system developers should call these methods appropriately.
public class Register
{
//Registration towards Noah
private const string _companyName = "HIMSA";
private const string _cmdLineArgs = ""; //"2";
private static string _exePath = System.Reflection.Assembly.GetExecutingAssembly().Location;
private static string _exeStartIn = Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().Location);
private static string _appName = Path.GetFileNameWithoutExtension(_exePath);
public static NoahAppType AppType = NoahAppType.BusinessSystem;
public static void Install()
{
bool isPreferedApp = true;
bool b = BusinessAPI.RegisterNoahApp(_companyName, _appName, AppType, _exePath, _exeStartIn, _cmdLineArgs,
isPreferedApp);
Debug.WriteLine(string.Format("Application '{0}' {1}\r\n", _appName, (b ? "installed" : "not installed")));
}
/// <summary>
/// Unregister or uninstall BusinessSystem APP from Noah.
/// </summary>
public static void Uninstall()
{
bool b = BusinessAPI.UnregisterNoahApp(_companyName, _appName);
Debug.WriteLine(string.Format("Application '{0}' {1}\r\n", _appName, (b ? "uninstalled" : "not installed")));
}
}
The second step in order to use the Business API is to declare a variable of the type BusinessAPI and then initiate the object declared. The properties available are then initiated when the method Initialize(); on the Business API object is called. During this initialize a connection is made to the Noah Client service, by the use of .NET remoting.
The sample below shows the initialize sequence made for the sample business system.
public BusinessAPI businessApiObj = new BusinessApi();
public MainWindow()
{
InitializeComponent(); //Initializing visual components
treeView1.Nodes.Clear(); // init Treeview used in component
loadTreeviewNodes(); // Load treeview nodes
try
{
businessApiObj.Initialize(“MyServer”, null, NoahAppType.BusinessSystem); //Init The Business API
InitializeBackgoundWorker(); // Setting up a bagground worker
backgroundWorker1.RunWorkerAsync("StartUpClient");
//Setting up the subscription for Noah events to be received from the Business API
businessApiObj.BusinessApiEvent += businessApiObj_BusinessApiEvent;
//Check if a patient already is set active in the running instance of the connected Noah Client
if (businessApiObj.CurrentPatient != null)
{
toolStripStatusLabel1.Text = "Current Patient: " +
businessApiObj.CurrentPatient.FirstName + " " +
businessApiObj.CurrentPatient.LastName;
toolStripStatusLabel1.Visible = true;
}
loadUserCtrl();
}
catch (Exception ex)
{
l.log.Debug("BusinessApi_TestApp.MainWindow::MainWindow: "+ex);
}
}
The next step is to set the user of the Noah system and, perhaps, a patient. The user is set by calling the method SetCurrentUserID, where the argument is an integer with the id of the user.
The language id is set by writing a value to the property LangaugeID on the BusinessAPI object. If not set the language ID is taken from the installed culture of the operating system.
The code sample below shows how the user and the language can be set:
private void LogonUser_Click(object sender, EventArgs e)
{
//Clear the text fields
NameText.Clear();
initialsText.Clear();
// businessApiObj is the BusinessAPI object, SetCurrentID returns a bool::true in case of success
bool logon = businessApiObj.SetCurrentUserID(Convert.ToInt32(UserIDText.Text,10));
if (logon == true)
{
NameText.Text = businessApiObj.CurrentUser.Name;
initialsText.Text = businessApiObj.CurrentUser.Initials;
EventArgs arg = new EventArgs();
//Send an event to the mainwindow to indicate that the logon of the user vent well
if (HandlelanguageID != null)
HandlelanguageID(this, arg);
}
}
private void Refresh_Click(object sender, EventArgs e)
{
businessApiObj.CurrentUser.Refresh();
}
private void SetLangaugeId_Click(object sender, EventArgs e)
{
// businessApiObj is the BusinessAPI object, LanguageID is a propertity on the businessApi
businessApiObj.LanguageID = Convert.ToInt32(languageID.Text,10);
EventArgs arg = new EventArgs();
if (HandlelanguageID != null)
HandlelanguageID(this, arg);
}
The patient is set by calling the method SetCurrentPatientID. This method is located on the Business API object.
The patientId is an integer greater than 0. If the id is set to 0 or less, Noah Client will deactivate the current patient and no patient will be active in Noah. When the patient ID is set it will be possible to get the session data related to the given patient from the CurrentPatient property on the BusinessAPI object.
// businessApiObj is the BusinessAPI object, SetCurrentPatientID returns a bool::true in case of success
bool setPatient = businessApiObj.SetCurrentPatientID(Convert.ToInt32(textBox13.Text, 10),false);
if (setPatient == true)
{
UpdateCtrl(bus.CurrentPatient);
OnSetPatientHandle();
}
This enables Noah to be executed as a 32 bit process on a 64 bit OS. We cannot guarantee the functionality of Noah 4 if a Business System is not compiled with the target platform – any CPU interfacing to Noah 4 on a 64 OS.
The Noah Client is the event distributer in Noah system. Noah Client distributes the events to the Noah Server, the Business API or any Module APIs which are connected to Noah Client. Noah Client sends the events to all connected components besides the component, which has created the event. This implies that if a Module creates an event by adding an action, then the event ActionAdded is sent to other connected parties besides the Module. Please refer to the figure below:
Figure: Event handling
In order for the business system to receive an event from Noah it must subscribe to the BusinessAPI event handle. The sample below shows how this is done in the sample business system. For a detailed description of the different available events please refer to the BusinessAPI Namespace BusinessAPI.NOAHEventType Enumeration in the BusinessAPI.chm file.
// businessApiObj is the BusinessAPI class initiatiated
businessApiObj.BusinessApiEvent += new BusinessAPIEventDelegate(businessApiObj_BusinessApiEvent);
void businessApiObj_BusinessApiEvent(IBusinessApiEventArg arg)
{
string argEvent = arg.EventType.ToString();
switch (arg)
{
case "ActionActivated":
break;
case "ActionAdded":
break;
case "ModuleFilterChanged":
break;
default:
break;
}
}
IMPORTANT: When handling events related to sessions and actions it is very important to test that the event is related to the current client as event related to a former current client may be received after the business system has changed client.
IMPORTANT: When using the Business API for Noah 4 the business system developer must be aware of a potential “Cross thread operation not valid exception” when trying to access a control by a thread other than the thread under which the control was created. This can be handled by either invoking any access to a control created by the event tread or implementing background work for the business system GUI when implementing in .NET. For further information, please refer to ‘Programming .NET components’, second edition, ISBEN-13: 978-0-596-10207-4 by Juval Lövel.
Overview
A description of the Noah 4 business system development process is supplied, including:
An overview of the Noah 4 software architecture and the steps required to develop a Noah 4-compatible business system
A set of guidelines for each step in the development process
References to additional information sources.
Only information on interfacing a business system to Noah 4 is included. No details are offered on how to design the architecture of the developer’s own business system.
Prerequisites
It is assumed that the developer has a solid general knowledge of programming on the Microsoft Windows. A good knowledge and understanding of .NET4.0 or later is also required for completing the Business API system interfaces.
Abbreviations
GUI Graphical User Interface
MS Microsoft
Noah 4
Noah 4 is the latest version of the Noah software developed by HIMSA II. Noah is a modular software framework/application. The figure below shows the different components which make up the Noah 4 system.
Figure: Noah 4 components
The Noah server is an MS-windows based service, which resides either on the same PC as Noah client or on a dedicated server PC. The Database used by Noah is by default a SQLCE and it resides along with the Noah server either on the local PC or on a dedicated server PC. Himsa also delivers a solution for using MS-SQL along with Noah 4. Please note that the Noah DB interface and Noah DB in the figure must be supplied by the business system developer. HIMSA supplies a complete sample of a an implementation of a DB interface.
Noah Client is the main component that Noah installs on a client PC; the Noah client will normally be executed as a MS-windows service. The business API and the module API are installed and available for the module or business system developers in the form of a .NET assembly dll. The Dlls can then be referenced within your development environment.
All inter-component communication in Noah 4 is done by using .Net remoting, except for the NOAH 2/3 module communication layer where COM is used.
The Business API
The Noah 4 Business API is a .NET 4.0 assembly, which is CLScompliant. This setup should ensure the usability of the assembly in other development environments as long as they support CLS.
The Business API exposes a number of objects and classes which implement the Noah business model. In addition, the Business API ensures communication with the Noah client, exposes all relevant Noah data for the business system and sends needed events to the business system so that it can update/restore data when needed.
A prerequisite for the Business API dll is Noah 4. Thus, the first step is to install Noah 4 by executing the installation file (setup.exe) which will guide you through the installation.
For using the Noah 4 installer process inside your own Business system installing process, please refer to Installation of Noah and Basic Modules with a Business System.
The module object can be found in the Module collection property available on the Business API. The sample code below shows the launch of a module in the sample business system: Please note that a module can be null, if the module for some reason is not available on the PC, then it is up to the business system to check if a module alias is available or check if another can be used by checking the CanShow/CanMake property.
private void TreeView1_nodeMouseDoubleClick(object sender, TreeNodeMouseClickEventArgs e)
{
string name = e.Node.Name;
if (e.Button.ToString() == "Left")
{
switch (name)
{
case "Actions":
{
Action action = (Action) e.Node.Tag;
Module module = (Module) action.Module;
module.LaunchWithAction(action);
break;
}
default:
break;
}
}
}
When asking whether it is alright to close, the Business API uses the method SafeToCloseEx with the arguments ModuleID and RunningModuleID. This method closes the module if an OK is received. The sample code below outlines this method. For a detailed description of the sequence please refer to More Information_N4 Business System API.
IMPORTANT: It’s NOT possible to close Noah 4 modules.
void Ctrl_StopModule(object obj, ModuleEventArg arg)
{
Module module = arg.Module;
RunningModule runningModule = arg.RunningModule;
foreach (Module mod in businessApiObj.Modules)
{
if (mod.CompareTo(module) == 0)
mod.SafeToCloseEx(runningModule.ModuleID, runningModule.RunningModuleHandle);
}
}
If Noah Client returns with ModuleCloseAccepted then the module is closed and the business system developer does not need to do anything.
If the Module declines the close request then the business system can force a close and/or disconnect. This is done by calling the method CloseModule on the module. The same method can be used if the business system needs to force the module to close. Refer to the sample code below:
void Ctrl_StopModule(object obj, ModuleEventArg arg)
{
Module module = arg.Module;
RunningModule runningModule = arg.RunningModule;
foreach (Module mod in businessApiObj.Modules)
{
if (mod.CompareTo(module) == 0)
mod.CloseModule(runningModule.ModuleID, runningModule.RunningModuleHandle);
}
}
NOTE: All objects in the Business API, which are defined as ‘information holders’ will implement a method called CompareTo. This is due to the base class IComparable which the information holder inherits from the Noah 4 implementation.
The following sample code shows how exception handling is implemented in the sample business system when using the remove method for unboundactions.
private void Remove_Click(object sender, EventArgs e)
{
int index = Convert.ToInt32(this.textBox2.Text, 10);
try
{
if (m_actionType == "Actions")
{
m_Session.Actions.Remove(index);
}
else
{
m_businessApiObj.UnboundActions.Remove(index);
}
}
catch(Noah_E_Action_Already_RemovedException Ex)
{
MessageBox.Show(ex.ToString(), "Exception", MessageBoxButtons.OK, MessageBoxIcon.Error);
}
catch(Exception ex)
{
MessageBox.Show(ex.ToString(), "Exception", MessageBoxButtons.OK, MessageBoxIcon.Error);
}
}
Below is a list of possible errors but several is obsolete.
public enum NOAHErrorType |
It is the module’s responsibility to register and connect to Noah when it is activated and once the connection is done, Noah will evaluate if a user is logged in or not. If not, then Noah will ask the user to log in and this dialogue is the default User manager dialog provided by the Business System.
When a module connects to Noah it can request that a certain patient is set as the active patient in the Business System. In order to do so the module must know some exact identification for this patient. The identification is data that the module itself labeled the patient with. For example, when the first fitting was saved. The request can only be fulfilled with the acceptance of the Business System and the Business System can always reply “No” to a request of this kind. Noah Client has a property that the Business System can set to “false” to not allow a Patient requested to be set by the Module. Then the flow below will stop when the module requests that a Patient is set active and Noah Client will always reply “No” to the Module. The property is called ModulesCanSetPatient and is a documented property in the BusinessAPI NameSpace in the BusinessAPI.chm file.
The Noah database contains room for modules to be able to place/label all patients with identification data – like the HI serial number or other unique data that can be read in the HI next time it is attached.
This means that for instance a fine tuning session can be done in an easier workflow:
The module is started from the desktop
The hearing instruments are connected via NOAHlink
The module reads datam e.g. serial number in the hearing instrument
The module connects to Noah
The module requests that a patient with certain data (serial number) is set active
The Business System activates the patient. (There is a process for this. See if another patient is active and other modules are connected, if not then activate.)
The module should clearly display the active Noah patient when it has connected. Since Noah is transparent, the user does not have any other places to see the active patient.
It is recommended that after the module has connected, the module, asks Noah about the active patient and immediately shows the patient data in the GUI (e.g., in the frame or having a patient banner).
If it is not the module itself that has requested that a patient is activated, it is recommended that the module requires that the user accept the active patient and if the user replies “no”, handles this.
The patient can be changed in different ways. One way is described above by letting the module request that a patient with certain identification be set as active. Another is to let Noah show the registered Patient Manager. This is a more simple Business System provided GUI that lets the user search and select a patient from the Noah database. In Noah System the module has the option to request that the Patient Manager is opened with a certain “Skin” (font and color) that matches the module. The User can also simply open the Noah System main GUI or any Noah 4 compatible Business System and select the Patient from there.
Comments:
Seen from the Business system, it is necessary to implement the ability/functionality to login and select a patient initiated from the Noah Client. In order to do this, a preferred manager must be installed to Noah, and this manager must be able handle the methods defined by the IBSCallBack.
The ModulesCanSwitchPatient property
The name of the property is unfortunately not the best name – since it implies that the Module can switch the active patient. This is NOT the case. A module can only request that the Patient is switched – and this request is sent to Noah Client through the Module API. Noah Client will ask the Business System if it is OK to switch the Patient. If the Business System reply is yes, then Noah Client will actively try to switch the patient (The flow is to next ask all open modules if they are ready to disconnect and then actually switch the active Patient).
It is mandatory to support the transparent methods in the database assembly. The module must be able to “SetPatientIdentification” and “GetPatientIdenfication”.
The ModulesCanSwitchPatient property is default set to “True” in any Noah installation. The Business System can set this property to “False." If the ModulesCanSwitchPatient is set to “False," then ANY module that requests that a patient is set active will be informed this is not possible from Noah Client and will have to handle this.
Must be implemented by a User Manager. When Noah Client has a need for a user, e.g. a module connects to Noah Client, Noah Client will start the preferred User Manager if it is not running. Noah Client will call the User Manager's implementation of the Login interface. If returning true, a valid User ID will be returned in UserID and Noah Client will set this UserID as the logged in User. The User Manager should not call SetCurrentUserID as Noah Client sets the User ID and the User manager will received a UserChanged event. This may be a little surprising, but it is consistent with the rule that the initiator of an action that causes an event does not receive the event but all other applications will receive the event.
An example:
A module connects to Noah Client and no user is logged in.
The module connect call is blocked until a user is logged in.
Noah Client will start a User Manager because of the module that connects, the module is the initiator of the action.
Noah Client calls the login function and a user ID is retuned as a result of the call. This is not an action with respect to Noah Client.
Noah Client sets the user as the logged in user .
A User Changed event is fired to the User manager
The modules connect call returns.
bool GetPatientIDsByInfo(object PatientInfo, out int[] PatientID);
// NOT USED
bool SetPatientIDByInfo(int [] PatientIDs, out int PatientID)
Given a number of patient ids, the PatientManager verifies the ids and displays the GUI that gives the user the option to select a patient or patients, if more than one. If only one patient id is given, the id is verified and the function returns immediately without showing the GUI. If PatientIDs is null, the patient GUI is shown, and the user can select a patient. If a valid patient is returned, the function returns true and the patient is set to active in Noah Client. This is the same scenario as calling Login, described above. The patient manger should not call SetCurrentPatientID as the patient manager will received a PatientChanged event.
Figure: Transparent Module, Connect
Figure: SetPatientIdByInfo
The Business system needs to call PreInit with a delegate to a method that can call connect on the BusinessAPI.
bool PreInit(RequestBSConnectNC r);
If the UserManager or PatientManager do not connect to NoahClient when the application starts, NoahClient must have a way to request the application to connect if it is running (to avoid that another instance of the same application is started). In order to make this possible the application must call PreInit. The PreInit call creates a named event based on where the application is installed and the name of the application. This information is also available in NoahClient, as it is one of the registration parameters. Whenever NoahClient needs the application to connect, the event is signaled.
Returns false if the function already has been called, and true otherwise.
bool PreUninit()
When an application shuts down it should call the PreUnint, which releases all resources allocated by the call of PreInit.
The function returns false if called without a call to PreInit and true otherwise.
delegate bool RequestBSConnectNC();
The delegate that the User/Patient manager must implement. RequestBSConnectNC() is called by NoahClient when it needs to launch a UserManager or PatientManager, to request the manager to Connect to Noah.
public class NoahPreInitSample: IBSCallBack {
public void Uninitialize() {
Himsa.Noah.BusinessAPI.NoahPreInit.PreUninit();
}
public void Initialize() {
try {
Himsa.Noah.BusinessAPI.NoahPreInit.PreInit(new
RequestBSConnectNC(ConnectRequestCallback));
}
catch (Exception ex) {
l.log.Error("PreInit()", ex);
throw;
}
}
private BusinessAPI _businessServer;
private bool ConnectRequestCallback() {
if (_businessServer == null) {
_businessServer = new BusinessAPI();
try {
_businessServer.Initialize(“MyServer”, null, this,
NoahAppType.PatientManger);
}
catch (Exception ex) {
l.log.Error("Initialize() ", ex);
}
}
return true;
}
#region IBSCallBack Members
public bool GetPatientIDsByInfo(object PatientInfo, out int[]
PatientID) {
throw new NotImplementedException();
}
public bool Login(out int UserID) {
// Simulate selecting user with id 8
UserID = 8;
return true;
}
public bool SetPatientIDByInfo(int[] PatientIDs, out int PatientID) {
// Simulating we selects patient with id 1
PatientID = 1;
return true;
}
#endregion
}
TODO:
Can IBSCallBack.Login() / SetPatientIDByInfo() be called before BusinessAPI.Initialize() returns?
Fast Data View
With Noah 4.7 HIMSA has added the Fast Data Viewing feature, providing Professionals with immediate access to patient data without opening the Noah modules!
If the Noah module supports Fast Data Viewing, the Professional will see an eye icon next to the module action in the Sessions list. Fast Data Viewing allows Noah modules to save a report with important patient information. The content and design of the report is set by the module developer.
Business API
The implementation of Fast Data view has resulted in an updated database interface. It is mandatory to comply with this database interface in order to certify for Noah 4.7 and onwards. The new functions are updated in the BusinessAPI namespace in the BusinessAPI.chm file and in the database tester.
Please note the “FastViewsEnabled Property” that can be set by the user of the Business System, if the Business System gives the user this option. If this property is set to “False” then Noah Client will not send the FDV to the Business System, and it is simply deleted. The property is meant for users that does not wish to use FDV and thereby do not wish to populate the database.
NHAX Import/Export
The NHAX format is prepared to include the FDVs so that these can be sent from one Business System to another.
Noah 4 installation - Summary of changes:
Version | Description |
4.0 | Initial release of Noah 4. |
4.1 | Added the optional BM property and the mandatory DBIF property. The bootstrapper setup.exe (Approx. 5MB in size) must be used instead of the main setup.exe (Approx. 20MB in size). |
4.2 | The DBIF property is now optional. Added the /w parameter and the mandatory EULAACCEPTED property. |
4.8 | The /w parameter has been changed to /clone_wait. |
Noah 4 installation:
When installing Noah 4 as part of your Business System installation - the setup.exe file (the bootstrapper which has a file size of approx. 5MB), located in the ‘CD’ folder below must be launched with a command line.
The following command line must be modified and used to launch the Noah 4 installation when performing an OAS installing. An OAS installation is a Business System other than Noah System:
Setup.exe /s /clone_wait /v "/qn /L*vx+ \"%temp%\Noah4_OAS_XXXXX.log\" OAS=1 EULAACCEPTED=YES BM=value DBIF=\"filepath\""
This Setup.exe file is actually a bootstrapper for the Setup.exe file located in the Installation folder which when launched unpacks and executes a noah4.msi file.
A Breakdown of the setup.exe command line follows:
1) The /s parameter is an Installshield command line parameter and means that the setup.exe file is launched in silent mode. No GUI and user interaction.
2) The /clone_wait parameter is an Installshield command line parameter. This parameter forces the installation to wait until the installation is complete before exiting.
3) The /v parameter is also an Installshield parameter which means that everything enclosed in double quotes is passed as a command line to the MSI Installer.
4) The /qn part tells the MSI Installer that the installation has no GUI and requires no user interaction.
5) The /L*vx+ part means that extended logging is performed during installation of Noah 4 (see help for MSIExec.exe for further details).
6) [Mandatory]: The path provided, ("%temp%\Noah4_OAS_XXXXX.log"), in the inner set of double quotes is the file path for the installation log. %temp% represents the computers temp folder – in the Noah4_OAS_XXXXX.log file name the XXXXX part must be replaced with a suitable name e.g. Noah4_OAS_ProductName.log.
7) [Optional]: See example 2 in Command Line examples: for required steps when NOT specifying this property. The DBIF="filepath" part lets the Noah 4 installer know that the Business System’s Database Interface assembly specified by the absolute file path "filepath" should be used by Noah 4. In the final phase of the Noah 4 installation a windows service named NoahServer will be started. This service will during start up load the assembly specified via the DBIF property. This means that the assembly must be available when installing Noah.
8) [Mandatory]: The OAS=1 part lets the Noah 4 installer know that this is a Business System installation in progress. The Installation for a Business System is different than the basic Noah 4 System installation – e.g. No shortcuts to the Noah 4 System will be created and a special registry key will be created that informs Noah that this is an OAS installation.
9) [Optional]: The BM=value part lets the Noah 4 installer know that the Basic Modules specified by ‘value’ should also be installed. See Table above : Basic Modules values. If the BM property isn’t specified then no Basic Modules will be installed.
10) [Mandatory]: The EULAACCEPTED property must be assigned the value ‘YES’ if the installation is passive. Passive installations are e.g. silent installations and installations without user interaction but with limited GUI that shows the installation progress.
Basic Module installation:
As an alternative to using the BM property it is also possible to install Basic Modules by launching the Basic Module installer located in the ‘CD\Installation\BasicModules’ folder. This installer requires the following command line to install the Basic Modules:
Setup.exe --Passive --Modules=value
The optional ‘Passive’ parameter instructs the Basic Module installer to perform the installation without user interaction.
The optional ‘Modules’ parameter along with the specified ‘value’ instructs the Basic Module installer to install the modules specified by ‘value’ – see Table: Basic Modules values below.
Noah 4 must be installed before you can install Basic Modules. To install the Journal module without user interaction you can use this command line:
Setup.exe --Passive --Modules=4
The setup.exe file is the one located in the ‘CD\Installation\BasicModules’ folder.
Table: Basic Modules values
value | Installed Basic Modules |
1 | Audiogram Module |
2 | Questionnaire Module |
3 | Audiogram Module + Questionnaire Module |
4 | Journal Module |
5 | Journal Module + Audiogram Module |
6 | Journal Module + Questionnaire Module |
7 | Audiogram Module + Questionnaire Module + Journal Module |
Database Interface registration:
As an alternative to using the DBIF property it is also possible to register the database interface assembly after you have installed Noah 4. See example 2 in Command Line examples:
Command Line examples:
Example 1:
Description: Install Noah 4 silently without user interaction. We wish to create a log file in the %temp% folder named ‘Noah4_OAS_SuperProduct.log’. In addition to the Noah 4 installation we also want to install the Journal module. The Business System’s database interface assembly is available from this location ‘C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll’.
Resulting Command Line: Setup.exe /s /clone_wait /v "/qn /L*vx+ \"%temp%\Noah4_OAS_ SuperProduct.log\" OAS=1 EULAACCEPTED=YES BM=4 DBIF=\"C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll\""
Additional Steps:
1) If required install a Noah license.
Example 2:
Description: Install Noah 4 silently. We which to create a log file in the %temp% folder named ‘Noah4_OAS_SuperProduct.log’. In addition to the Noah 4 installation we also want to install the Journal module.
In this example we do not want to install the Database interface assembly prior to the Noah 4 installation hence we do not specify the DBIF property.
In order to register the database interface with Noah when it has been installed e.g. by the Business System, we must call an executable file named NoahConfig.exe located in the Noah 4 installation folder.
Resulting Command Line: Setup.exe /s /clone_wait /v"/qn /L*vx+ \"%temp%\Noah4_OAS_SuperProduct.log\" OAS=1 BM=4 EULAACCEPTED=YES"
Additional Steps:
1) Register database interface:
The path to the Noah 4 installation folder is available via a registry key:
HKEY_LOCAL_MACHINE\Software\HIMSA\InstallationInfo\Noah\v4\InstallPath
We will assume that the database interface assembly is available from this location: ‘C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll’.
Assuming the Noah 4 installation path is: ‘C:\Program Files\Himsa\Noah4’ then we can call the NoahConfig.exe located in that folder. We need to specify a command line for the executable which will register the database interface and restart the Noah Server Service.
Command Line: "C:\Program Files\Himsa\Noah4\NoahConfig.exe" –dbifrss="C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll"
If registration of the database assembly is done by the use of NoahConfig a stop and start of Noah server service is necessary. (If you use the setup.exe option a restart of the system is forced upon the user) A start and stop of a service require elevated rights, which once in while is not obtainable. To solve this issue is the NoahConfig exe is enhanced by 2 arguments –NoahServerStop and –NoahServerStop, which can ask the NoahserverService to stop and start by the use of NoahClientService.
2) If required install a Noah license.
Prerequisites for Noah 4
Noah 4 has some prerequisites of its own. The following Microsoft prerequisites will be installed as part of the Noah 4 installation if required:
1) Windows Imaging component (WIC)
2) Microsoft .NET Framework 4.0 (Full)
3) Microsoft SQL CE 3.5 SP2
These prerequisites are located in the ‘CD\Installation\ISSetupPrerequisites’ folder.
IMPORTANT:
Please observe that Noah 4 has Microsoft .NET Framework 4.0 as a prerequisite. Installing on a system without Microsoft .NET Framework 4.0 may require several minutes to install.
IMPORTANT: Please Notice that Noah from pre 4.12 and again from 4.14 supports UTF-16 when importing. We strongly recommend the use of UTF-8. Please beware that UTF-16 is only supported when importing nhax / enhax; nowhere else is it supported in Noah, e.g., Public and Private blobs, etc.
In 4.12 and 4.13 UTF-16 data can be imported by first importing on a pre-4.12 Noah and then exporting from that version again. Then the data will be in UTF-8 and can be imported on any Noah version.
The Noah 4 Extended Native format (Nhax) is an extension of the older NOAH 3 Native format.
It is not a compatible format, but is based on the same base blob’s and elements (sections).
The SDK contains source code for a Nhax viewer, as well as an xsd file describing the XML of the patient xml data.
The XML sections must have enough information on the encoding to ensure portability.
Enhax is a variation of Nhax, with password protected compression. See description later in this document.
Data Storage
The Noah 4 Native format is a mix of binary data, and compressed XML data, each put into a BLOB section/record:
The following sections are defined.
internal enum NHAxFileSections {
ROOTSECTION = 0x0201,
PATIENTDIRECTORY,
USERSECTION,
MISCSECTION,
PATIENTSECTION
} ;
The root holds offsets to the other sections. The rootsection is the first section and is at file position 0.
The patient directory holds Patient demographic data as well an offset to the patientsection, for all the exported patients.
The Patient sections each contain the Patient information in XML (These sections are compressed)
The User section contains User information in XML for all the users used in the exported patients.
The Misc section is not used yet. (Future expansion)
ROOT_SECTION
The ROOT_SECTION begins at File offset 0, and is the entry point to get information.
[StructLayout(LayoutKind.Sequential, Size = (8 + 8 + 8 + 8)), Serializable]
internal struct RootxSection {
[MarshalAsAttribute(UnmanagedType.I8)] internal long MagicNumber; // A magic number for better
identification
[MarshalAsAttribute(UnmanagedType.I8)] internal long PatientDirectoryOffset; // File offset to the
Patient directory
[MarshalAsAttribute(UnmanagedType.I8)] internal long UserOffset; // File offset to the User section
[MarshalAsAttribute(UnmanagedType.I8)] internal long MiscOffset; // File offset to the misc section
}
MagicNumber = 0x00AABBCCDD009988;
PATIENTDIRECTORY
The PatientDirectory contains patient information on each patient in the file. The PatientRecordOffset is the file offset to where the PATIENTSECTION resides for the patient. The XML for the patient is the same as for PATIENTSECTION, except that the PatientRecordOffset attribute must be applied and that it only contains that patient’s demographic data. Other sections of the xml (Sessions, PatientModuleSetupData, PatientComments, PatientIdentification ) can/should be omitted.
<?xml version="1.0" encoding="utf-16"?>
<Patients>
<Patient PatientNo="0000001" PatientGUID="132f2fa8-94a6-4a2d-a6e9-f207599ba41b" CreateDate="2011-02-01T08:17:39" UserInitials="ABC" FirstName="John" LastName="Smith" Gender="0" PatientRecordOffset="40" />
<Patient PatientNo="0000002" PatientGUID="81A77DDF-5827-467f-BBA8-778CB703EC8C " CreateDate="2011-02-01T09:27:29" UserInitials="ABC" FirstName="John" LastName="Jonson" Gender="0" PatientRecordOffset="1879" />
</Patients>
PATIENTSECTION
The PATIENTSECTION contains all the information on the patient in XML.
This section contains all the data related to the Patient (Demographic, Sessions, Comments, SetupData, and Identification)
See the NhaxFormat.xsd for further details.
USERSECTION
Please note that users imported into Noah ES are done so by creating an inactive user.
The USERSECTION contains all the UserInitials for the patients in XML.
<?xml version="1.0" encoding="utf-16"?>
<Users>
<User>
<Initials>ABC</Initials>
<Name>ABC</Name>
<UserName>ABC</UserName>
</User>
</Users>
MISCSECTION
Not used, but available for expansion.
Enhax Format
Enhax is supported in the SDK source code for the Nhax viewer.
Enhax is the same as Nhax, except that it uses password protected compression. It is implemented using SharpZipLib with AESKeySize set to 256, compression level set to 9 (range: 0-9) and compression type is 'Deflated'.
IMPORTANT: Noah Mobile will require Noah 4.9 after November 7th 2018 !
Microsoft has announced that for security reasons, it is retiring/migrating their Azure Access Control Service (ACS) by November 7th, 2018.Noah versions prior to Noah 4.9 are all set up with encryption keys of the ACS type. This means that from November 7th 2018, Noah Mobile apps will no longer be able to communicate with Noah System versions prior to Noah 4.9 or Noah compatible business systems based on Noah 4.8 and earlier. To avoid issues with your Noah Mobile app, please ensure that your customers upgrade to Noah 4.9.1 before this date to ensure continued communication. Business Systems which support Noah Mobile apps will also need to use Noah 4.9 and later. When your customer upgrades to Noah 4.9, the upgrade process will migrate the user to use SAS keys for data encryption.
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. This SDK documentation provides the necessary guidelines for adding Noah Mobile to your existing Business System.
IMPORTANT: It is a mandatory requirement for all business system member companies to add Noah Mobile support to their Noah-compatible Business System.
When this feature is enabled in your 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 Database and database interface must conform to the functions described in this section (and in the Namespace section of the BusinessAPI.chm file)
The Database implementation must be successfully tested with the Database tester tool
The Business System must have a user dialogue where the user can enable/disable Noah Mobile
Please note that Noah Mobile is turned off in Noah 4.5 by default
The End User License Agreement (EULA) is updated for Noah Mobile and should be accepted by the Noah user
For more information on Business System development, please refer to the Namespace section of the BusinessAPI.chm file and the Business API.
Noah Mobile - Cloud Environments
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.
When you develop a Business System you should take into consideration that HIMSA's sample apps will all point to the External Test environment, so if you wish to use them you can point your Business System Noah Mobile installation to use this environment during development. Alternatively you can change the sample apps to use the Production environment.
If you are using 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 environment.
public void MobileAppEditPatientsEnable(bool Enable)
Enable patient management if Enable is true, else disable (enable is false)
The Noah Mobile compatible app will get the following reply from Noah when asking:
public bool MobileAppEditPatientsEnabled()
Returns true if patient management is enabled, else false
If MobileAppEditPatientsEnabled is false the app should not show GUI that allows for Patient management
To reset during your installation, use the “NoahMobileReset.exe” utility provided on the Noah Mobile SDK page.
For detailed information, refer to the namespace in the BusinessAPI.chm file.
New/changed classes in the NoahDataObjects namespace
The following new classes are included in the NoahDataObjects namespace:
AppPermission
MobileApp
UserPrivilege
Changed classes
Patient: Added property: LastModifiedDate
New functions in the Database Interface
The following new functions are declared in the database interface
void PutMobileAppPermissions(int ModuleID, int[] PermissionIDs, object callContext)
int[] GetMobileAppPermissions(int ModuleID, object callContext)
void DelMobileAppPermissions(int ModuleID, int[] PermissionIDs, object callContext)
void PutAppPermissions(AppPermission[] appPermissions, object callContext)
AppPermission[] GetAppPermissions(object callContext)
void DelAppPermissions(AppPermission[] appPermissions, object callContext)
void RegisterMobileApp(MobileApp mobileApp, object callContext)
void UnregisterMobileApp(int ModuleID, object callContext)
MobileApp[] GetMobileApps(object callContext)
Patient PutPatient(Patient patient, object callContext)
User GetUser(string UserName, object callContext)
NoahDataObjects.Actions[] GetActions(int PatientID, ActionFilter ActionFilter, object callContext)
NoahDataObjects.Patient[] GetPatients(string searchText, int Page, int PageSize, ref int? QueryTotalNoOfPatients, object callContext)
bool ValidateLogin(string username, string password, out int userid, object callContext)
Patient[] GetUpdatedPatients(int Page, int PageSize, DateTime StartDateTime, DateTime? EndDateTime, object callContext);
ActionEx[] GetUpdatedActions(int Page, int PageSize, DateTime StartDateTime, DateTime? EndDateTime, int [] DataTypes, object callContext)
NoahDataObjects.Action[] ActionreferencedBy(int ActionID)
UserPrivilege GetUserPrivilege(int userUD, object callContext)
AppPermission Class
The AppPermission class describes the permissions that relates to the properties in the patient object e.g. if a property is required when creating/updating a patient object the required is set to true. A detailed description of the AppPermission class is found in the namespace in the BusinessAPI.chm file. The Noah Mobile Compatible apps will read the AppPermission Class and from there create data to be updated/inserted in the Business System If MobileAppEditPatientsEnable is set to true.
One important field in the AppPermission class is the ReadOnly field, when this field is true the administrator is not allowed to change the Default property. HIMSA requires that the ReadOnly field and default is set to true for the following properties: ID, FirstName, LastName, Gender, BirthDate. This is the minimum dataset that an App can request from the Business System.
When calling the GetAppPermissions function that must be implemented in the database interface the returned array must contain a row describing the following names that correspond to a property in the Patient class defined in NoahDataObjects. This is the only row that the function must return.
The following is the HIMSA default in Noah System:
Default
The fields where default set to true is the default fields that any app will have access to read when it is registers
Note that different apps can have access to different data depending on the App permissions for the app.
ReadOnly
Fields with ReadOnly means that the system MUST, as a minimum, always have these fields set to the Default
Required
Required fields are the fields that the Business system requires to add a patient
The App will know this and should ask that the user fills in these data to create a patient
They must be set, but if the MobileAppEditPatientsEnable is set to false it will not matter
All business systems must initialize the AppPermission table. The table initialized must have the same number of rows as the table shown below, but the business system may change a few values. In rows where the ReadOnly field is true all the other column values must be the same as in the table shown below. In rows where the ReadOnly column is false, the business system is free to choose the initialization values for the Default and Required column (the values must be true or false). The other values must be same as in the table shown below.
Besides these fields there will also be properties like ID, PatientGUID, CreatedBy, LastModified, etc. that always will be returned and cannot be changed by the Business System.
IMPORTANT: Due to the GDPR implementation in Noah 4.9, HIMSA has discovered additional dependencies that must be included in order to implement the Noah Mobile Configuration window that resides inside NoahExternalComponents.dll. It is necessary to extract the following three dlls from the %ProgramFiles(x86)%\Himsa\Noah 4\ folder of the Noah installation and place them with your exe and NoahExternalComponents:
MouseKeyboardActivityMonitor.dll 3.0.1.21726
MoonPdfLib.dll 0.3.0.0
libmupdf.dll 2.2.1.0
For examples on how the dialog can be implemented in your business system, please refer to the Sample Business System.
Developing your own user dialogue for enable/Disable Noah Mobile
You can also choose to implement your own Noah Mobile configuration dialog using the following new functions in the BusinessAPI:
/// PutMobileAppPermissions inserts/updates the permissions for a given app identified by a module ID.
public void PutMobileAppPermissions(int ModuleID, int[] PermissionIDs)
/// Retrieves the permissions for a given app identified by module ID
public int[] GetMobileAppPermissions(int ModuleID)
/// Deletes the given app permissions for a given modules id
public void DelMobileAppPermissions(int ModuleID, int[] PermissionIDs)
/// Convert an array of permission IDs to an array of AppPermision
public AppPermission[] ConvertPermissionIdsToAppPermissions(int[] permissionIDs)
/// Converts an array of AppPermission to an array of permission ids
public int[] ConvertAppPermissionsToPermissionIDs(AppPermission[] appPermissions)
/// PutAppPermissions inserts/updates permissions in the permission table. If PermissionID in the AppPermission class
/// is 0 a new permission is created else an existing permission is updated.
public void PutAppPermissions(AppPermission[] appPermissions)
/// Retrieves all the defined app permissions.
public AppPermission[] GetAppPermissions()
/// Deletes the permissions.
public void DelAppPermissions(AppPermission[] appPermissions)
/// Set the accept state for a number of Mobile Apps
public void PutAppAcceptStates(AppAcceptState[] appAcceptStates)
/// If true, the host name is available (not assigned to this, or any other host).
public bool IsHostNameAvailable(string hostName)
/// Assign the host name to this host. One host can have multiple host names.
public void AddNameToRemoteHost(string hostName)
/// Delete the host name for this host. One host can have multiple host names.
public void DeleteNameForRemoteHost(string hostName)
/// Get the all of the host names for this host. One host can have multiple host names.
public IEnumerable<string> GetNamesForRemoteHost()
/// Transfer the host name from the previous host (associated with the ownership key) the to the current host.
public IEnumerable<string> ClaimRemoteHostNames(string ownershipKey)
/// Change the email address.
public void ChangeEmail(string email)
/// NOT COMPATIBLE: This method is not compatible with this version of Noah it's pre Noah 4.9.
public void PutMobileCnf(MobileCnf Cnf)
/// Use this to setup Noah Mobile. Noah Mobile Configuration (MobileCnf) is moved to there. Alternative is to use NoahExternalComponents which contains a ready made Configuration
/// window. If you choose that solution remember to extract the following three dlls from the %ProgramFiles(x86)%\Himsa\Noah 4\ folder of the Noah installation and place them with
/// your exe and NoahExternalComponents. MouseKeyboardActivityMonitor.dll 3.0.1.21726, MoonPdfLib.dll 0.3.0.0, libmupdf.dll 2.2.1.0
public Provision ProvisionCreate()
/// This Class encapsulate the setup of Noah Mobile
/// To Provision do the following :
/// Get Property MobileCnf that returns a MobileCnf object.
/// Call GetDataProcessingAgreement ít retuns a object that contains a PDF document to be accepted by the user.
/// Title, Name, Company and Email must be filled in by the user before calling PutDataProcessingAgreement.
/// Put Property MobileCnf with the data filled in.
/// Then to save on the server call Submit.
public class Provision
/// <summary>
/// Get latest Data Processing Agreement for the user to accept, in the current Noah Language for the CountryLCID set in the parameter, in order to be able to use NoahMobile.
/// If the user doesn't accept it NoahMobile can't be enabled over the internet.
/// <param name="CountryLCID">The LCID of the country whos Data Processing Agreement is to be returned.</param>
/// </summary>
public DataProcessingAgreement GetAgreement(int CountryLCID)
/// <summary>
/// Accept the latest Data Processing Agreement, in the current Noah Language. This must be done in order to be able to use NoahMobile.
/// If the user doesn't accept it NoahMobile can't be enabled over the internet.
/// Usage: Call GetAgreement populate Email, Title, Company, and Name and Call PutAgreement.
/// <param name="agreement">The agreement that is accepted.</param>
/// </summary>
public void PutAgreement(DataProcessingAgreement agreement)
/// <summary>
/// This method stores the information on the server.
/// </summary>
public void Submit()
To understand the workings of the above methods, we recommend that you open the Sample Business System and then place breakpoints in each and every method in the “ConfigurationService” class (derived from INoahMobileConfigurationService) and the “NoahMobileConfigWindow” class (derived from Window). Please note when, why with and which parameters the methods call.
Above: Entries in the session list have been made for patient Amy Connor, by a Service App. The Dashboard icon (the “Globe”) has the number “4” on a red background, indicating that there are 4 unread alerts.
Above: Shows the alerts for the patients, and the corresponding (if any) entries in the session list. The Dashboard is in many ways like an inbox in an email app.
Service Apps
First, a few definitions:
Manufacturer. Generally refers to a hearing instrument manufacturer. It could also mean an audiological equipment manufacturer or any general HIMSA member company.
Manufacturer Backend. An application or system provided by a hearing instrument manufacturer. A Manufacturer Back End is used to facilitate hearing care services between Noah, Hearing Care Professionals (e.g. audiologists), Manufacturers, and patients. This system is generally understood to be a larger system controlled and maintained by the hearing instrument manufacturer. However, the Manufacturer Back End could also be a smaller system such as an MS Windows-based Noah compatible fitting module.
Service App. An application that uses the Noah Web Api to communicate with Noah. In most cases, the Service App is expected to be controlled by the Manufacturer Backend. In contrast to other types of apps using the Noah Web Api, a Service App can be permanently logged in, and thus does not need user interaction.
Notification. A message sent from the Manufacturer Backend to Noah via the Noah Web API. The Notification can contain an Alert (a short message that can be viewed on the Dashboard) and/or an entry in the patient’s journal (for example a Journal entry or an Audiogram).
How does a Service App differ from the typical Noah Mobile User Interactive App?
A Service App uses the same Noah Web Api, but differently:
A Service App must register as so. During registration, the Service App must specify (to the Noah installation it requests access to) which level of data access it requests. It is up to the administrator of the Noah installation to grant or deny this data access. The administrator can always revoke a grant/denial. See ‘level of data access’
Authentication does not take place with an interactive user rather is facilitated the the approval process (see previous point)
A Service App cannot use the Himsa AccessLayer.
A Service App can do most things a User Interactive App can, but is primarily intended to, in prioritized order:
Provide a way for the Manufacturer Backend to send Notifications to a Noah installation.
Make it possible for the Manufacturer Backend to monitor relevant events (for example addition of new patients or journal entries). See also ‘level of data access’.
Level of data access: Events regarding certain types of data (data types 129 Selection, 130 Selection, 131 Fitting, 132 Fitting, 133, 135, 136, 137, 258, 300, 301, 302 and 303 ) are only sent to the Manufacturer backend if they originated from a module from the same manufacturer. Meaning: One cannot “eavesdrop” on the amount of communication with other manufacturers' modules. Other events (e.g. from Audiograms and journal entries - data types 1 and 256) are always sent if requested.
When a Service App registers, it must specify which types of data the app should be able to interfere with, and if the Service App can read/write the type of data and if the Service App should receive events when data with the given datatype is manipulated.
Above: List of apps.
Above: Access rights for the ServiceAppSample app.
HIMSA provides a ServiceAppSample application (incl. program code) that demonstrates the workings of a Service App.
Dashboard
As mentioned above, the Dashboard adds an inbox-like functionality to Noah. Alerts can be sorted, read, and assigned to users. Alerts can be associated with sessions, which can be opened from within the Dashboard. Once an alert has been dealt with, it can be removed from the Dashboard.
Implementing GUI for Dashboard Alerts
Noah Alert Dashboard Alerts are generated outside Noah, received by Noah and then stored in the database, alongside other data objects (actions, patients, etc.).
By use of methods in the BusinessAPI, it is possible for a business system to read and manipulate the Dashboard Alerts.
The BusinessAPI can also, via its event framework, notify business systems when alert related events take place.
There is currently one approach to implementation of GUI for Dashboard Alerts:
Use the Dashboard control provided by Himsa.
Q: Can I create a custom Dashboard for my business system?
A: Currently, this approach is not supported. HIMSA may consider custom dashboards in the future if there are requests for it. Additionally, the Dashboard and Alerts are new to Noah and to hearing instrument manufacturers there is a good chance that features may need to be adjusted as we gain more experience.
Using the Dashboard control provided by Himsa
It is highly recommended looking at the code (especially the file ‘DashboardService.cs’) for the Sample Business System (provided with the Noah installation files).
This is the approach that is used in the Sample Business System. The control is in BusinessSystemExternalControlsLibrary.dll.
Embed the Dashboard control in your own window.
Make your own implementation of a DashboardService that complies with the IDashboardService interface.
For updating Dashboard Alert related information outside the Dashboard control, also look at OnBusinessAPIEvent in the BusinessAPI, and the event types AlertAdded, AlertUpdated and AlertArchived. These can be used to keep the GUI up to date when new alerts are received.
Session Browser: A GUI component that is responsible for showing the current patient’s sessions and actions.
Active Document Container: Hosts the NOAH 3 modules.
Module Installation Server: Used for registering modules NOAH 3 with Noah 4.
Module Install OCX: Used to register a module from inside Noah System. Takes an .ini file as input and registers the module using the Module Installation Server.
Noah Basic Object: Implements the basic objects (Action, Patient, LicenseInfo, Product, Session, UnBoundAction, User, etc.) and interfaces to interact with these.
Noah Server Lib: Remoting for Noah.
Noah Server Proxy: Com interface responsible for the client/server communication.
Module API: Is used by modules to access the Noah objects.
Noah Server Core: Core server functionality.
Noah Data Objects: Similar to the basic object except that it is located on the server.
Noah client: Contains the object hierarchy on the client and handles communication with the server.
GPDP: General Purpose Data Porter, the name of the data stream, which enables Business system to send arbitrary data to. The managed Database dll.
Manufacturer codes
Module Categories
DataTypes
Manufacturer codes
Each HIMSA licensee is assigned a unique manufacturer code. This code is used to tell Noah:
if the module is from a HIMSA licensee (modules without a valid manufacturer code will not be displayed)
if the licensee already has a module button displayed on the Module Bar
You need to contact Himsa to get a manufacturer code - contact information can be found at Himsa webpage -