This section provides the business system developer with:

• 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.

 

This configuration is similar to the NOAH 3 data model in which the business systems are in complete control of the demographic and Noah data. This setup allows the business system developer to integrate session data so that the session data can be combined with Noah session data and other business data in the business system. The figure below outlines this setup. 

                               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. 

In order to develop a business system, a number of tasks need to be completed, including:

• 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, How to Use the Noah 4 Database Tester Tool.

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.

In Noah 4, the term Business System covers the system that handles users, patients and business logic. The business system can be one application that handles everything or divided into specialized applications that handle users  - User Manager, patients - Patient Manager and business logic - Business System. Be aware that Business System is both the term for the application handling the business logic, and the generic term covering User Manager, Patient Manager and Business System.

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.

This section supplies a list of the data fields a .NET database interface needs to support. For  for samples, please refer to the Noah 4 Business System Development page on himsa.com.

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.

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.

*Action records must not be deleted if the referenced user is deleted.

In order for Noah to use a third party developed database assembly a registration must be performed.  Noah includes a command line program, NoahConfig.exe, which must be used for this job. The program is located in the Noah installations folder. For further information see Installation of Noah and Basic Modules with a Business System.

A business system requiring the use of Noah must use the Business API interface i.e. an instance of the Business API object.

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.

For detailed information on the properties, methods and events for the Business API objects, please refer to BusinessAPI NameSpace in the BusinessAPI.chm file.

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 Business API offers the option of sending additional information to the managed database dll. Typical information would be a string indicating the user and/or PC, and may also include login information, password and user. This information is generated by the business system. Noah plays no part in its generation. Furthermore, this information does not need to have any relation to other Noah data.

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).

A new feature available in Noah 4 is the General Purpose Data Porter or, in short, GPDP. GPDP’s objective is to port data from the Business System though the Business API, Noah Client and right to the Noah Server, which will be able to hand the data to a managed database dll supplied by the 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; }

        }

 

     }

}

In NOAH 3 it was only possible to edit Actions within the same calendar day in which they were created. This has been changed in Noah 4.  By default, Noah will allow Actions to be edited beyond the calendar day in which the actions were created.  However this only applies to Noah 4 modules and there are two exceptions to this rule:

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.

This section describes the necessary programming tasks a business system supplier must complete in order to be able to create a business system which successfully embeds the Noah 4 Business API.

 

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.

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.

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:

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.

Noah 4 is required to run on both a 32 bit OS and a 64 bit OS and for that reason we have compiled all components inside the Noah 4 suite (including samples and SDK’s)  with the platform target set to (x86)

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.   

Noah system implements a number of events that a business system needs to handle. It is up to the business system developer to decide which events the business system will react to.

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.

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.

Noah 4 supports modules which are developed for NOAH 2 and 3. Therefore, a business system should be able to launch a NOAH 2/3 module. The Noah 4 system aids the business system in launching NOAH 2/3 modules by facilitating an Active single document container which hosts the NOAH 2/3 modules. For the business system it will be necessary to call the method LaunchWithAction on the module object which represents the module to be launched. The argument is an action object either gathered from the action collection available on the session currently active, or null, in which case the module will launch without any data. The Business API will keep track of the actual version of the module (Noah 2/3/4) and launch it accordingly. (For a more detailed description of the launch sequence, please refer to More Information_N4 Business System API.)

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.

The Business API can close or disconnect Noah 4 module in one of two ways: by asking if it is alright to close or disconnect and awaiting an OK before closing, or by simply closing or disconnecting directly.

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.

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:

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 Business API does not return any error codes. All error handling is done by exception. This implies that the business system developer should wrap all method calls and accessing properties. Besides the standard exception defined in .NET, the Business API also defines a number of exceptions. For a detailed description of exceptions please refer to the Himsa.Noah.Exceptions Namespace in the BusinessAPI.chm.

The following sample code shows how exception handling is implemented in the sample business system when using the remove method for unboundactions.

Below is a list of possible errors but several is obsolete.

 

Noah 4 modules are able to take advantage of the features and functions available for “Transparent Noah”.  The overall idea behind Transparent Noah is that the end user can start the module directly from the Desktop, without starting the Noah GUI (Noah System or the Business System). Noah is always running as a service but the user will not see or know this.

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:

1. The module is started from the desktop

2. The hearing instruments are connected via NOAHlink

3. The module reads datam e.g. serial number in the hearing instrument

4. The module connects to Noah

5. The module requests that a patient with certain data (serial number) is set active

6. 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.

bool Login(out int UserID);

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

PreInit should be performed by business systems that do not want to be connected at all time, but only upon request by NoahClient or itself when needed.

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.

TODO:

• Can IBSCallBack.Login() / SetPatientIDByInfo() be called before BusinessAPI.Initialize() returns?

Please observe that the installation steps required for a Business System may have been updated from the previous release of Noah.

Noah 4 installation - Summary of changes:

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

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: It is mandatory that a Noah 4 business system support export of Noah data in nhax format.

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 

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'.

Business API: Used by business systems to access Noah objects.

• 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.

In this appendix, the different Constants that are relevant for Module and Business System Developers will be described. Basically, they can be split into three categories:

• 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 - www.himsa.com.

Module Categories

There are three types of modules: measurement modules, fitting modules and other modules. Upon installation, a module must tell NOAH to which category it belongs.

DataTypes

When a module needs to store an action in the NOAH database, it must inform NOAH of the data type of the action to be stored. The currently defined types of data in the NOAH 3 system database are listed below.

Adding new constants

There are two situations where constants can be added to the System Database:

• When HIMSA adds a new constant: When a company becomes a HIMSA licensee, HIMSA assigns the company a Manufacturer code.

• When a HIMSA licensee submits a proposal for adding a constant in the System Database and the proposal is accepted: A licensee may wish to add a new data type constant that supports a new type of data format.

This section explains how to extract module icon that is displayed as module button on module bar.

 

There could be several ways of extracting icons from Noah 3 (.dll) for 4 (.exe) modules. Here is how Noah 4 GUI (Module Bar) extracts icon from Modules:

BusinessSystemExternalControlsLibrary.Converters defines a Converter class named as

ModuleImageConverter, which is used to extract the module icon of size 115 * 33.

Here is the usage example:

Xaml code:

<Image Name="imgLogoDLLPath" Width="115" Height="35"/>

C# code:

BitmapImage bi3 = new BitmapImage();

bi3.BeginInit();

bi3.UriSource = new Uri(firstModule.LogoDLLPath, UriKind.Relative);

bi3.EndInit();

ModuleImageConverter imageConverter = new ModuleImageConverter();

imgLogoDLLPath.Source = (ImageSource) imageConverter.Convert(firstModule.LogoDLLPath, null,

null, null);

You can also directly bind the converter in XAML, First define the declaration at the top of xaml file.

xmlns:converters="clr-namespace:BusinessSystemExternalControlsLibrary.Converters"

Than define the image tag with and remember to pass bindings.

<Image Source="{Binding Path=Module.LogoDLLPath, Converter={StaticResource

ModuleImageConverter}}"/>