Noah 4 intro
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 – The Noah 4 architecture
Noah 4 is a client server system, with a central database connected to a component called NoahServer.
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: The Noah Database interface and the Noah Database in the figure can be supplied by the business system developer. The NoahServer component handles the transfer of data to and from the database. The NoahServer also provides access to a System Database, which defines a variety of constant values that are used by modules during normal operation.
The NoahServer communicates with one or more NoahClient components each residing on different workstations (one NoahClient per workstation). The NoahServer handles the synchronization between all these workstations.
Each workstation has its own set of third-party fitting, measurement or other modules installed locally. Using the ModuleAPI component, the modules communicate with the local NoahClient component to exchange data via the NoahServer component.
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 Dll’s can then be referenced within your development environment.
The responsibilities of the NoahClient component are:
keeping track of registered modules on the workstation
Regulating the number of modules that are simultaneously connected to Noah on the same workstation
Providing access to data in Noah for the ModuleAPI and BusinessAPI
After installation, the ModuleAPI component is the primary interface for the module to access the Noah software.
Figure – The Noah 4 architecture including Noah 3 components
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. Noah Client will also provide access to Noah for Module APIs and Business APIs.
Noah Server
Noah Server has a number of tasks to perform;
Database access
License evaluation
Structured storage 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 API or Module APIs. Thus, Noah Server distributes events to attached Noah Clients. These events are broadcast to all attached Clients besides the Client originating the event.
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.
Prior to Noah 4.9 Noah would remember that a user was logged in, even if all modules and Business System have disconnected, but only for 2 minutes. With Noah 4.9 and newer this is not the case and the user will be automatically logged out. This change was made as the previous implementation was considered a security risk.
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” in order not to allow that a Patient is requested 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 Business API documentation.
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 data – 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 other 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, it 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.
Figure – The ModuleAPI Object Model
Most objects accessible via the ModuleAPI object hierarchy are only valid in the context of that hierarchy. A newly created object is initially detached from the object hierarchy, hence unknown to Noah. When e.g. an Action object is added to the Actions collection then the action object is also persisted via Noah and made available to other modules.
As shown in the diagram above, all of the Noah objects are organized into an object hierarchy, in which each object is indirectly accessible as a property of its parent. All objects are ultimately connected to the ModuleAPI object through a series of such parents. For example, a Module Filter is the child of a Module collection, which is the child of the ModuleAPI.
For the collection objects the naming convention is that they are prepended with the letter ‘s’, e.g. the Actions collection object is container for Action objects. For the Sessions collection and Modules collection, there are special “filter” objects that control which objects appear in their collections. For example, the ModuleFilter object controls which Module objects appear in the Modules collection according to criteria such as “module category” and “supported inter-module communication protocols”.
For instance, if an Action is externally created, it is initially detached from the hierarchy. When it is added to the Actions collection of the CurrentSession, a “copy” becomes the child of the Actions collection. Because the Actions collection is itself already part of the hierarchy, the newly-added Action copy is now attached to the hierarchy as well.
The following code sample illustrates how a new Action object is added to the Actions collection:
// myModuleAPI is the modules only instance of the Himsa.Noah.Modules.ModuleAPI class.
Action action = new Action
{
Description = "Test",
DataType = new DataType {Code = 5, Format = 100}, // When the Action objects DataType
// property is set it causes the DataType object to be validated – this requires that
// the myModuleAPI instance has been successfully connected to Noah).
DeviceType = 1
}; // Create an Action that is detached from hierarchy.
myModuleAPI.CurrentSession.Actions.Add(action); // Attach a copy of the action object to the Noah object hierarchy.
After an Action is added to the hierarchy, it can no longer be updated by changing the attributes of the original external object. A module can only change the attributes of an attached Action by using objects in the ModuleAPI hierarchy.
The User object
The Patient object
The Session object
The Action object
The UnBoundAction object
The Module object
The Manufacturer object
For a detailed description of all the objects in the ModuleAPI component, refer to Namespaces under the ModuleAPI Assembly in the ModuleAPI.chm file.
Each module will get its own Setup blob. This will not interfere with any other module’s Setup blob.
A module can read the initials and name of the user from the Initials and Name properties. Binary data associated with the user may be read or set from the Setup property.
The module has read access to the above properties that hold information about the patient’s name, gender and birth date, as well as more system specific information about the patient such as ID, date of creation and the user that created the patient. All properties are read-only and can be read into local variables.
The Session object holds two properties: CreateDate, which is the date when the session was created, and Actions, which is a reference to an Actions collection that holds the actions of the session.
Noah 4 introduces two new concepts called Archived Actions and NonCurrentAction – please refer to The Concept of Archived Actions and The Concept of NonCurrent Actions for a description.
After creating a new Action object – this Action object can be added to the object hierarchy of the active patient using the ModuleAPI in one of two ways:
1) The new Action can now be added to the current Session object’s actions collection of the active patient.
2) If the intent is to make the new Action object appear as if it was created at an earlier date, then this is possible by using the current Patient object by using the AddNonCurrentAction method.
Action Group
A module can use the ActionGroup property to group actions that were saved at the same time. These actions have a one-to-one relationship with each other. The ActionGroup property allows the module to store the same timestamp for each action saved at the same time. This, then, allows it to easily find related actions. For example, when Noah asks a module to open, and passes it an action, the module may want to display other associated actions. If these actions have already been saved with the same ActionGroup value, the module need only match this value to the other actions in the session.
The Noah Session Browser also makes use of the Action Group Property to condense the view of session activity.
Starting with Noah 4.12 Noah will now support a new optional property, Action GUID. The module developer may optionally populate this data with a GUID value for it's own purposes. It is very important that the module still make use of the Action Group property. If this is not done Noah's session browser and other Noah integration will most likely not work as expected.
The default behavior for Noah is that after you have attached an Action to the object hierarchy you can modify its properties whenever you like.
However it is possible to configure Noah such that an attached action object can only be removed or changed while in the current session. In this configuration an attempt to modify an action that does not belong to the current session will cause an exception.
Actions can only be modified by the module that added it.
A module can access information regarding actions through Action Objects. Examples of Action information is - the kind of action, the user that created the action, the module that created the action, and a description of the action.
The module can request another module to be launched, pre-loaded with an existing action to view or edit it.
For further details about the Action object, please refer to the ‘Namespaces,' under 'ModuleAPI Assembly' in the Noah 4 'ModuleAPI.chm' file.
HIMSA requests that developers ensure their modules do not attempt to modify any UnBoundAction created by another module.
In Noah 4, version 4.7, the concept of ‘Fast Data View’ has been added. A Fast Data View is a resume (generated by the module) of the action, and suitable for quick previewing without the time-consuming process of opening the relevant module. Currently supported data formats are Rtf, Jpg and Pdf.
There can only be one Fast Data View for each Action Group. When adding a Fast Data View for an action, the Fast Data Views for the other actions in the Action Group (if any) will be deleted.
Noah 4 introduces two new concepts called Archived Actions this also applies to the UnBoundActions. Please refer to section The Concept of Archived Actions for a description.
After creating a new UnBoundAction object, this UnBoundAction object can be added to the object hierarchy using the ModuleAPI to add the UnBoundAction to the UnBoundActions collection.
The default behavior for Noah is that after you have attached an UnBoundAction to the object hierarchy you can modify its properties whenever you like.
However it is possible to configure Noah such that an attached UnBoundAction object can only be removed or changed within the calendar day it was created. In this configuration an attempt to modify an UnBoundAction will cause an exception.
UnBoundActions can only be modified by the module that added it.
A module can access information regarding actions through UnBoundAction Objects. Examples of UnBoundAction information are the kind of UnBoundAction, the user that created the UnBoundAction, the module that created the UnBoundAction, and a description of the UnBoundAction.
The module can request another module to be launched, pre-loaded with an existing UnBoundAction to view or edit it.
For further details about the UnBoundAction object, please refer to the ‘Namespaces,' under 'ModuleAPI Assembly' in the Noah 4 'ModuleAPI.chm' file.
HIMSA requests that developers ensure their modules do not attempt to modify any UnBoundAction created by another module.
For example, a measurement module that can only read Real Ear Measurement (REM) format 200 may need to read an action in REM format 100. Using an ActionConverter, the REM format 100 data can be converted to REM format 200, allowing the data to be read by the module.
1. This feature can be disabled by the Business System. If this feature is disabled then the ‘EditOldActionsAllowed’ property of the ModuleAPI returns false.
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.
How is an ‘Archived Action’ accessed?
Archived Actions should be seen as children of an edited Action, the Parent Action. Noah 4 has made two new methods available via the Action object in the ModuleAPI. These are the ‘GetArchivedActionsCount’ method which will return the number of Archived actions an Action has and the ‘GetArchivedActions’ method which will return a read only collection containing the Archived Actions an Action has.
How will I be able to access Archived Actions when the parent Action is removed from the database?
You won’t, all Archived Actions are removed when the parent Action is removed.
Code samples for working with Archived Actions
Example 1) Get archived actions
In this example we assume that we have an instantiated ModuleAPI object named myModuleAPI that is connected to Noah.
The code in this sample will iterate over all actions for the selected patient and retrieve available archived actions.
public void GetArchivedActions()
{
// myModuleAPI is the modules only instance of the Himsa.Noah.Modules.ModuleAPI
// class. Does the ModuleAPI object have a selected patient?
if (myModuleAPI == null || myModuleAPI.CurrentPatient == null) return;
foreach (Himsa.Noah.Modules.Session session in myModuleAPI.CurrentPatient.Sessions)
{
// Does this session object have any action objects?
if ((null == session.Actions) || (session.Actions.Count == 0)) continue;
Console.WriteLine("Session with Id='{0}', Date='{1}'", session.Id,
session.CreateDate.ToShortDateString());
foreach (Himsa.Noah.Modules.Action action in session.Actions)
{
// Does this action object have any archived actions?
if (action.GetArchivedActionsCount() > 0)
{ // Show the action
Console.WriteLine(string.Format("\tAction with Id='{0}',Description='{1}'
has archived actions", action.Id, action.Description));
// Show all archived actions of the current action object
foreach (Himsa.Noah.Modules.Action archivedAction in
action.GetArchivedActions())
{
Console.WriteLine("\t\tArchivedAction with Id='{0}',
Description='{1}'", archivedAction.Id, archivedAction.Description);
}
}
else
{
Console.WriteLine("\tAction with Id='{0}', Description='{1}' does not
have any archived actions", action.Id, action.Description);
}
}
}
}
Example 2) Update an action which result in an archived action
In this example we assume that we have an instantiated ModuleAPI object named myModuleAPI that is connected to Noah.
The code in this sample will iterate over all actions for the selected patient which belong to a Session that is different from today and modify the description for all actions.
public void ModifyOldAction()
{
// myModuleAPI is the modules only instance of the Himsa.Noah.Modules.ModuleAPI class.
// Does the ModuleAPI object have a selected patient?
if (myModuleAPI == null || myModuleAPI.CurrentPatient == null ||
myModuleAPI.EditOldActionsAllowed == false)
return;
foreach (Himsa.Noah.Modules.Session session in myModuleAPI.CurrentPatient.Sessions)
{
// Skip sessions from today.
if (session.CreateDate.Day == DateTime.Now.Day)
continue;
// Does this session object have any action objects?
if ((null == session.Actions) || (session.Actions.Count == 0))
continue;
// We are here because we have an Action object from a date that is different
//from today.
Console.WriteLine("Session with Id='{0}', Date='{1}'", session.Id,
session.CreateDate.ToShortDateString());
foreach (Himsa.Noah.Modules.Action action in session.Actions)
{
// Modifying an Action object that was created prior of today results in the
// creation of an archived action.
action.Description = string.Format("I have {0} archived actions",
action.GetArchivedActionsCount());
Console.WriteLine("\tAction with Id='{0}', Description='{1}'", action.Id,
action.Description);
}
}
}
This has changed in Noah 4. By default Noah will allow Actions to be created on non current calendar days. However this only applies to Noah 4 modules and there is one exception to this rule:
This feature can be disabled by the Business System.
This feature has been added to allow Noah 4 modules to create an Action that should not belong to the current calendar day. Using the ‘AddNonCurrentAction’ method of the Patient object in the ModuleAPI, the Noah 4 module can create e.g. a measurement Action with a date that reflects the date where the actual measurement took place.
Editing a NonCurrent Action will even though it was just created cause the Action to be archived.
Example 3) Create an action that will belong to a date that is different from today’s date.
In this example we assume that we have an instantiated ModuleAPI object named myModuleAPI that is connected to Noah.
The code in this sample will create an action object where the action object’s CreateDate property is set to a date that is different from today’s date. If there is no Session available for the chosen ‘CreateDate’ one will be created by Noah.
public void AddNonCurrentAction()
{
// myModuleAPI is the modules only instance of the Himsa.Noah.Modules.ModuleAPI
// class.
// Does the ModuleAPI object have a selected patient?
if (myModuleAPI == null || myModuleAPI.CurrentPatient == null ||
myModuleAPI.EditOldActionsAllowed == false)
return;
// Create a new Action object to be added as a NonCurrent Action.
Himsa.Noah.Modules.Action actionToAdd = new Himsa.Noah.Modules.Action
{
DataType = new Himsa.Noah.Modules.DataType
{ Code = 1, Format = 0, FormatExt = 0},Description = "The action's description"
};
// Add the action object - and back date it 3 days.
myModuleAPI.CurrentPatient.AddNonCurrentAction(DateTime.Now.AddDays(-3),actionToAdd);
}
For a detailed description of all ModuleAPI objects, refer to the ‘Namespaces,' under 'ModuleAPI Assembly' in the Noah 4 'ModuleAPI.chm' file.
Figure - The module development steps
Modules can be launched in different ways:
a. clicking on a module in the business system’s module bar
b. clicking on an action entry in the business system’s session list.
c. clicking on a module icon on the windows desktop or another location
d. by initiation from another module.
e. by another module that want to use your module as an IMCServer.
f. clicking in the Session list and select 'Print.' The module is then launched with a Print Action or Print Action Group command.
2. The module instantiates the ModuleAPI. Refer to the Instantiating the Module section.
3. The Module can determine why it was opened by reading LaunchInfo.
4. The module connects itself to Noah via the ModuleAPI.
5. If the module has been launched via 1a, 1c,or (1d) from above, it is recommended that the module show the most recent action of the type it supports.
If launch method 1b (1d) from above has been used, the action will be opened in the module in which it was created. In both cases, the module should open in either Edit or View mode, depending on the following circumstances:
ACTION CREATED BY | MODE |
The same module within the same session – i.e., the same calendar date | Edit Mode · The data is then edited |
A different module within the same session – i.e., the same calendar date | Edit Mode |
A different session – i.e., a previous calendar date | View Mode · Any attempt to edit data in the View mode should cause a window to appear; asking whether the user would like to create a new fitting/measurement based on the old data, or would prefer to cancel. · If the user chooses to create a new fitting/measurement, the module should shift to edit mode. IMPORTANT: See Save information in Step 7 below. The new action should be saved in today’s session. |
No action is available | Edit Mode · The user is allowed to create a new action |
NOTE: No matter which mode the module is opened in - the user should always have the option of creating a new action except as IMCServer.
6. The user has completed the session, the user closes the Module
7. The Module saves the Action data, if any has been created, by adding the action object to the current session. The module must save data as follows:
if a module reads or uses data created by another module on the same date, it must not attempt to alter or over-write the original data, but must save the data as its own new action
if a module reads or uses data already created on the same date, it should alter and over-write the original data.
if the user decides to create a new action based on a previous action from a previous session, the new action must be saved in the current day’s session.
8. The Module exits. Whenever the user attempts to close the module with unsaved data (for example, with the Close ‘x’ button in the upper-right corner of the window), the module should offer the option of saving this data before closing.
If the module requires a specific version of Noah e.g. Noah 4.0 or Noah 4.4 this can be retrieved by a registry key made available by Noah. The version string for the first release of Noah 4 is ‘4.0.13.1417’.
This key can be found here (on a 32 bit operating system):
HKEY_LOCAL_MACHINE\SOFTWARE\HIMSA\Installationinfo\Noah\v4\Version
This key can be found here (on a 64 bit operating system):
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\HIMSA\Installationinfo\Noah\v4\Version
Important information – please notice:
It is not acceptable for Modules to distribute HIMSA assemblies and/or files. The Noah installer will install the necessary files in the GAC, and the Module installer is not allowed to install own copies on the PC. Neither is it acceptable for Modules to install any files in the HIMSA/Noah folders.
There should not be a reason for a Module to distribute files made by HIMSA and distributed by Noah, so they should be removed from the Modules installer.
In order for any module to connect to Noah and or be launched by another module or business system, the module must register with Noah. This task is accomplished by using the ‘Himsa.Noah.Modules.Registration’ and ‘Himsa.Noah.Modules.RegistrationData’ classes.
The registration, if successful, is only required once after deployment. Please refer to The Registration Objects to see objects involved in the module registration.
Please consider the following when registering the module:
Does the available Noah framework have the correct version? If this is not the case, it might not make sense to register, or perhaps even deploy the module.
Which data types can the module show and/or create? It all needs to be included in the registration process so Noah will become aware of it.
Does the System Database, Globob.stg, need to be updated with a new manufacturer, new data types or etc.?
See Constant Definitions for information on how to update the System Database.Ensure proper handling of a failed registration attempt, by catching all exceptions, and react correctly to them (aborting registration, if something went wrong etc.)
It is important when developing your module setup program that it follows standard Windows installation procedures.
The module registration is NOT optional.
The implementation of these standard procedures is a requirement for receiving Noah certification.
Module Registration Information
This section provides an overview of:
the module information that must be registered with Noah
the major classes used for registering module information
two methods that module developers can use to register their module
The Module offers a complete range of objects, which enables a new module to specify all its capabilities. The following table describes some of this registration information.
NOTE: A module registers information using constants defined in the System Database. For more details refer to Constant Definitions.
Information Type | Description |
Manufacturer Code | A unique code assigned by HIMSA to each of its Licensees. Refer to Constant Definitions for details of this code. |
Local Module Identifier | A unique code that must be assigned to each module by its Manufacturer. This number is used by Noah to distinguish between two or more modules from the same manufacturer. A module number must be between 0 and 65,535. |
Module Category | Third party modules are divided into module categories, including fitting, measurement and other. A new module must identify the category to which it belongs. The Module Category allows limiting the number of concurrently running modules in Noah. Additionally the Module Category also allows for a logical grouping of available modules. Refer to Constant Definitions for more info. |
DataType | Modules exchange data with Noah by adding and retrieving data through the Session list. Data added by one module may be visualized by another Manufacturer’s module. To make this possible, data is characterized by a DataType object, which holds information about the nature of the data and the format used to represent the data. These standards are described in the Noah data standards documents on HIMSA’s website (www.himsa.com). |
IMC Protocol | Modules may exchange data directly with other modules through inter-module communication (IMC). HIMSA defines IMC protocols and assigns each protocol a unique protocol identifier. A module must inform Noah about the protocols and data formats supported using the Protocols collection, which is a collection of Protocol objects. |
The main objects used for the registration of module information are the Registration and RegistrationData objects.
The following illustration provides an overview of the Module Registration objects:
Modules must let Noah know which types of data they can work with. Using a collection of DataType objects, which hold information about the nature of the data and the format used to represent the data, a module can tell Noah which types of data it can generate and which types it can visualize. These standards are described in the Noah data standards documents on the HIMSA website (www.himsa.com).
The data types that a module can create are expressed through a collection of DataType objects identified by the ActionMake property of the object. The data types that a module can visualize are expressed through another collection of DataType objects identified by the ActionShow property.
Besides the protocols supported by a Server module, information regarding the data that can be exchanged is also needed. This information is supplied through a DataType collection attached to each Protocol object.
For more information on Inter-Module Communication, refer to the Inter-Module Communication (IMC) Documentation page.
Upon registering the module, it is possible to provide Manufacturer - and ModuleID of the modules, which actions the registering module is able to replace. Should the ModuleAlias be uninstalled, the registering module will take its place.
Do note, that a module alias will be able to replace the given module, which is different from Actionmake and ActionShow, which is indicating that the module in question can make and show actions of the given data type.
Code sample – Module Registration
using (var regData = new Himsa.Noah.Modules.RegistrationData
{
ModuleName = "Here goes the module name",
Version = "1.2.3.4", /* The version string of the module – this string is visible via
// the module button bar*/
ModuleCategory = 1, /* The value one is for a meassurement module */
ExePath = executablePath, /* This is the absolute path+filename of the modules
executable file */
ManufacturerId = _manufacturerId, /* The manufacturers ID */
ManufacturerModuleId = _manufacturerModuleId, /* The manufacturers module ID */
ButtonDLLPath = "", /* The absolute path+filename of the modules LOGO Dll */
HelpPath = "", /* The absolute path+filename of the modules Help file */
PrintHandler = "", /* The absolute path+filename of the modules printhandler
component */
Show = true, /* Is the module visible */
ActionMake = new List<Himsa.Noah.Modules.Registration.DataType>
{
new Himsa.Noah.Modules.Registration.DataType {DataTypeCode = 1, DataFmtStd = 100},
new Himsa.Noah.Modules.Registration.DataType {DataTypeCode = 1, DataFmtStd = 200}
},
ActionShow = new List<Himsa.Noah.Modules.Registration.DataType>
{
new Himsa.Noah.Modules.Registration.DataType {DataTypeCode = 1, DataFmtStd = 100},
new Himsa.Noah.Modules.Registration.DataType {DataTypeCode = 1, DataFmtStd = 200}
},
Protocols = null,
ModuleAlias = new List<Himsa.Noah.Modules.Registration.ModuleAlias>
{
new Himsa.Noah.Modules.Registration.ModuleAlias {ManufactureId = 1, ModuleId = 2}
},
IMCServer = "",
UninstallCmd = ""
})
{
using (var registration = new Himsa.Noah.Modules.Registration())
{
registration.RegisterModule(regData);
}
}
Implementing the Callback handler
To ensure proper interaction between the module and Noah – the module must implement the callback methods of the ‘Himsa.Noah.Modules.ICallbackHandler’ interface.
There are two situations the callback handler must address:
When a second module from an module category with the cardinality of 1, (this applies to measurement and fitting modules which can only have one connected module at any time), then the already connected Noah 4 module will receive a call to the ‘AcceptToDisconnect’ callback method.
If the connected Noah 4 module returns ‘true’ to indicate that the module accepts to be closed it will receive a ‘ModuleDisconnect’ event when it should disconnect. A module with unsaved data may choose to ask the end user for the action to take before disconnecting.
If the connected Noah 4 module returns ‘false’ to indicate that the module does not accept to be closed it will not receive a ‘ModuleDisconnect’ event.
If a patient switch is initiated by the user, then all connected Noah 4 modules are asked if it is OK to switch the patient. All modules will receive a call at the ‘CanSwitchPatient’ method. If all connected Noah 4 modules returns ‘true’ to indicate that the patient switch can take place – then Noah client will start the patient switch. In this case Noah Client iterates through the list of running modules and for each module notices if the module connected with ability to switch patient or if it has to use the old method of disconnecting and connecting again.
o True Noah 4 Modules that connected with the ability to switch patient will receive the “PatientChanged” event when the patient is changed and must then act properly (update patient information) (See more under “Connecting the Module”)
o Modules that the uses the old disconnect method will receive the “ModuleDisconnect” event and will have to disconnect and connect again to retrieve the new patient
o In both cases – if one module rejects to switch patient then all modules will receive the “CanSwitchPatientCanceled” and do not have to change patient or disconnect
o IMPORTANT NOTE! There is a time period between when the module has replied to the “CanSwitchPatient” request until the actual “PatientChanged” or “ModuleDisconnect” or “CanSwitchPatientCanceled” is received. In this time period the module must NOT let the user input data as Noah is in a Patient Switch state. The module does not know which patient the data will be saved to and worst case is that data can be saved on the wrong patient.
C# sample code for callback handler:
public class MyCallBackHandler : MarshalByRefObject, Himsa.Noah.Modules.ICallbackHandler
{
public bool CanSwitchPatient()
{
// Handle the callback here.
return // true or false.
}
public bool AcceptToDisconnect()
{
// Handle the callback here.
return // true or false.
}
}
Implementing the event handler
To ensure proper interaction between the module and Noah – the module must in addition to implementing the callback methods also subscribe to events from Noah. The module can receive multiple events from Noah, (defined by the ‘Himsa.Noah.Modules.NotificationType’ enum type).
The event handler is needed for the module to be able to react to certain events, like ‘ActionAdded’, ‘ActionUpdated’, ‘ActionRemoved’or ‘LanguageChanged’ etc. Modules must be prepared for unknown events (i.e. ignore them) in order to be forward compatible.
Which events the module should subscribe to are optional, except for one event – ‘ModuleDisconnect’.
If Noah requests a module to disconnect by raising the ‘ModuleDisconnect’ event, the module must disconnect (This is a requirement to be certified). All other events are considered informational for the module. See ‘
Table 2- Noah 4 ModuleAPI events’ for all events.
When the module's event handler receives an event from the ModuleAPI it will receive a class of type ‘Himsa.Noah.Modules.NotificationType’. See ‘Table 1- Properties of the NotificationType’.
Table 1- Properties of the NotificationType
Property Name | Description |
Notification | This property is of type ‘Himsa.Noah.Modules.NotificationType’ – see Table 2- Noah 4 ModuleAPI events. The Notification property describes the change to the system e.g. ‘ActionRemoved’ or ‘ActionAdded’. |
ActionId | This property is of type int and contains additional information for action related events e.g. when the module receives an ActionAdded Notification (event) – the ActionId property holds the action id of the added action. A zero value indicates that the ActionId is not relevant for this Notification (event). |
SessionId | This property is of type int and contains additional information for session related events e.g. when the module receives an SessionAdded Notification (event) – the SessionId property holds the session id of the added session. A zero value indicates that the SessionId is not relevant for this Notification (event). |
ModuleId | This property is not currently used. |
Table 2- Noah 4 ModuleAPI events
Event | Description | Handling | version |
None | Indicates no action should be taken. Not currently used. | Optional | 4.0 |
ActionAdded | Indicates an action was added. The accompanying NotifyEventArgs type contains the added ActionId. | Optional | 4.0 |
ActionsAdded | Indicates that one or more actions were added. | Optional | 4.0 |
ActionRemoved | Indicates an action was marked as removed (it hasn't been deleted and can be restored by a Business system that supports this feature). The accompanying NotifyEventArgs type contains the removed ActionId. | Optional | 4.0 |
ActionPurged | Indicates an action was purged from the database. The accompanying NotifyEventArgs type contains the purged ActionId. | Optional | 4.0 |
ActionRestored | Indicates a removed action was restored. The accompanying NotifyEventArgs type contains the restored ActionId. | Optional | 4.0 |
ActionUpdated | Indicates an existing action was updated. The accompanying NotifyEventArgs type contains the updated ActionId. | Optional | 4.0 |
| Optional | 4.0 | |
UnboundActionAdded | Indicates an unbound action was added. The accompanying NotifyEventArgs type contains the added ActionId. | Optional | 4.0 |
UnboundActionRemoved | Indicates an unbound action was removed. The accompanying NotifyEventArgs type contains the removed ActionId. | Optional | 4.0 |
UnboundActionRestored | Indicates a removed unbound action was restored. The accompanying NotifyEventArgs type contains the restored ActionId. | Optional | 4.0 |
UnboundActionUpdated | Indicates an existing unbound action was updated. The accompanying NotifyEventArgs type contains the updated ActionId. | Optional | 4.0 |
Optional | 4.0 | ||
SessionAdded | Indicates a session was added. The accompanying NotifyEventArgs type contains the added SessionId. | Optional | 4.0 |
SessionRemoved | Indicates an existing session was removed. The accompanying NotifyEventArgs type contains the removed SessionId. | Optional | 4.0 |
Optional | 4.0 | ||
PatientUpdated | Indicates that one or more properties of the current patient have changed. | Optional | 4.0 |
EnableeTONADeclined | OBSOLETE. Message from the OAS that a request to enable eTONA can’t be carried out. | N/A | 4.0 |
eTONADisabled | OBSOLETE. that eTONA functionality has been disabled. | N/A | 4.0 |
eTONAEnabled | OBSOLETE. that eTONA functionality has been enabled. | N/A | 4.0 |
LanguageChanged | Indicates the language was changed by the business system. | Optional | 4.0 |
PatientChanged | Indicates that the current patient was changed. | N/A | 4.0 |
SafeToClose | OBSOLETE. Request from the business system, if the module is safe to close. | N/A | 4.0 |
StatusUpdateAdded | OBSOLETE. Indicates a status update was added. | N/A | 4.0 |
StatusUpdateUpdated | OBSOLETE. Indicates an existing status update was updated. | N/A | 4.0 |
UserChanged | Indicates that the current user has been changed. | N/A | 4.0 |
UserUpdated | Indicates that one or more properties of the current user have changed. | Optional | 4.0 |
RegionChanged | Indicates that the region property has been changed. | Optional | 4.0 |
ModuleDisconnect | This Indicates that the module has been asked to disconnect by Noah. It is mandatory for modules to handle this notification. | Mandatory | 4.0 |
StateReestablished | This Indicates that Noah Client has reestablished the state i.e. all information cached in Noah Client are refreshed. The module must reread all information cached internally. This can occur when a computer wakes up after hibernation or the connection to the server has been reestablished. | Optional | 4.1 |
MustDisconnect | This Indicates that the module will be disconnected within 5 seconds. This may occur because Noah Server has a need for all Noah Client to disconnect. | Optional | 4.1 |
CanSwitchPatientCanceled | Indicates all modules that have previously accepted to switch patient will receive this event if another module has declined to switch patient. The current patient will not be changed. | Optional | 4.2 |
ResumeSuspendStartRecover | Indicates that the PC has been resumed after a standby or hibernation, this event is sent when Noah is starting to recover i.e. rebuild the internal state. This process will be transparent for modules except that they will receive relevant events about changes just as if the system changes had happened in a running system. Check the ‘ResumeSuspendEndRecover’ event for further information. | Optional | 4.2 |
ResumeSuspendEndRecover | Indicates that Noah has recovered after the PC has been resumed from a standby or hibernation, this event is sent when Noah has completed the recover process. Check the ‘ResumeSuspendStartRecover’ event for further information. | Optional | 4.2 |
C# sample code to set up the event handler
// Subscribe to ModuleAPI events.
myModuleAPI.EventPublisher.Notify += MyNoahEventHandler;
C# sample code for a very simple event handler:
// Handle ModuleAPI Events.
private void MyNoahEventHandler(object sender, EventArgs e)
{
Himsa.Noah.Modules.NotifyEventArgs eventArgs = e as Himsa.Noah.Modules.NotifyEventArgs;
if (eventArgs == null)
return;
switch (eventArgs.Notification)
{
case Himsa.Noah.Modules.NotificationType.ActionAdded:
// An action was added to the current patient.
// Perform required action.
break;
case Himsa.Noah.Modules.NotificationType.ActionUpdated:
// An action of the current patient was modified.
// Perform required action.
break;
case Himsa.Noah.Modules.NotificationType.ModuleDisconnect:
// The module is requested to disconnect.
// Perform required action.
break;
}
}
scenarios that occur when a module is accessed, used and closed in Noah
guideline for instantiating a module
guideline for connecting a module to Noah using the ModuleAPI
Please observe that you are only allowed to have a single instance of the ModuleAPI per module.The following is a simplified example of how to instantiate the ModuleAPI, and how to setup callback’s and event handling and connecting to Noah:
// Connect Module to Noah 4 and subscribe to the events.
// Use MyNoahEventHandler as event receiver
public void MyConnectToNoahMethod()
{
try
{
// myModuleAPI represents the modules only instance of the ModuleAPI.
if (myModuleAPI == null)
{
myModuleAPI = new Himsa.Noah.Modules.ModuleAPI();
/* Subscribe to ModuleAPI events. ‘MyNoahEventHandler’ represents a method that handles
the Noah events. A simple implementation has been shown in a previous sample.*/
myModuleAPI.EventPublisher.Notify += MyNoahEventHandler;
}
/* before the module connects to Noah it can read the ‘Print’ and ‘ActionGroup’ properties
via the GetLaunchInfo() method of the moduleAPI instance.
launchInfo.Print which indicates that the module is expected to perform a print job.
launchInfo.ActionGroup which indicates that if the module is launched to perform a print job
it must print action belonging to this action group.*/
LaunchInfo launchInfo = myModuleAPI.GetLaunchInfo();
/* moduleid represents the modules identifier and callback is an instance of a class that
implements the Himsa.Noah.Modules.ICallbackHandler Interface.
This is where the module connects to Noah.
if launchInfo.Print is true, the module connects as print handler. In this situation the
module must do the printing and immediately after
printing disconnect. */
ConnectRes res;
res = moduleAPI.Connect(moduleID, callback, launchInfo.Print, true);
if (res != ConnectRes.Ok) {
if (res == ConnectRes.ModuleNotRegistered) {
// Register module and connect again
}
}else {
// Report error and exist
}
}
/* when successfully connected to Noah the module can read various properties from the
moduleAPI instance.
e.g. myModuleAPI.EditOldActionsAllowed returns true then the business system allows actions
older than the current calendar day to be edited.
e.g. myModuleAPI.CurrentPatient returns a Patient object if a current patient has been
selected otherwise null.
e.g. myModuleAPI.CurrentUser returns a User object that represents the current user.
e.g. myModuleAPI.LanguageId returns a windows LCID representing the selected language of the
business system.
when successfully connected to Noah the module can read various properties via the
GetLaunchInfo() method of the moduleAPI instance.*/
launchInfo = myModuleAPI.GetLaunchInfo();
/* e.g. launchInfo.ModuleId represents the module id that is expected to launch.
e.g. launchInfo.IMCClient represents an IMC handle that the module is expected to connect
to.
e.g. launchInfo.Action represents an action object that the module is expected to launch
with.
e.g. launchInfo.UnboundAction represents an unbound action object that the module is
expected to launch with.
}
catch (Exception ex)
{
myModuleAPI.Dispose();
myModuleAPI = null;
}
}
NOTE: Based on requests from HIMSA’s licensees, only one fitting and one measurement module may be connected concurrently. This means that two fitting modules can be launched at the same time, but only one of them can be connected to Noah.
If a module connects as print handler the module is allowed to connect even if another module of the same kind is connected, but the module is only allowed to print, and must disconnect immediately when the printing is done.
When a patient is switched in Noah a true Noah 4 module does not have to disconnect and connect again to update the patient. The module can simply react to the “PatientChanged” event. Since this is a newer event the module will need to tell Noah that it can react to it (in order not to get the “ModuleDisconnect” event). The module will simply have to set the “switchPatientWithoutDisconnect” Boolean to true during the connection call. Please refer to the connect method in ‘Namespaces,' under 'ModuleAPI Assembly' in the Noah 4 'ModuleAPI.chm' file for more information.
Q: Does HIMSA have any visual requirements for a logo?
A: No but it does have other resource requirements, please see Adding a Logo, Patient Manager font and colors, and the module description to the Application.
Additional features and things to keep in mind
After this, it is just a matter of adding the features that you want the module to support. Furthermore, many things might be a good idea to keep in mind.
A few examples will be mentioned briefly here:
A print handler makes it possible for the module to deliver patient reports, generated by the module, onwards to Noah for the user to print. It is recommended that this feature is included in the modules
Inter Module Communication (IMC) makes it possible for two modules to communicate with each other
It is also best practice to make sure, that when the user uninstalls the module, the module will unregister itself from Noah.
The preceding chapters will describe the module development process in more detail.
a reference to example code that illustrates a minimum module application using ModuleAPI objects
guidelines for implementing Noah 4 printing requirements
guidelines for implementing inter-module communication
an overview of the Noah session list functionality
Sample Modules
With Noah 4, HIMSA provided a sample module. The module is intended to provide examples of how to access the basic functionality of Noah. They do not consider any audio logistic aspects of module programming. The sample includes a fair level of error handling, but does not take into account error handling, installation or any other aspects of the module regarded as being exemplary or adequate for module development or certification.
The sample modules are provided in C# using Visual Studio 2010. The modules require that the development environment be installed on the computer in order to debug them.
IMPORTANT: The sample code provided by HIMSA is provided as is, without further support, including but not limited to, the specifics of the development environments. HIMSA has no plans (nor knowledge) to develop sample modules for other development environments. HIMSA may change parts of the samples without notice. Furthermore, HIMSA makes no warranty of any kind with regard to this sample code, including, but not limited to, the implied suitability of the code for a particular purpose.
IMPORTANT: Do not copy the entire sample projects and use them in your own module development, as they contain unique information that, if re-used, could lead to unpredictable results. Instead, you will need to create your own projects and copy-paste the relevant code from the samples, if necessary.
Noah 4 Printing Requirements
In Noah 4, the modules can handle printing themselves. The actions can off course be launched with a Print parameter or Print Action Group parameter, if the user wishes to print any of these directly. In order to identify these, just look at the LaunchInfo properties. For further details of LaunchInfo, please refer to the ‘Namespaces,' under 'ModuleAPI Assembly' in the Noah 4 'ModuleAPI.chm' file.
Implementing Inter-Module Communication
Inter-module communication (IMC) was introduced in Noah 2.0 as Online Communication. Its purpose is to allow two modules to communicate directly with each other through a well-defined protocol, without using the services of the Noah framework.
This form of communication is mainly used by fitting modules to launch and control a Real Ear Measument module.
At the current time, three protocols have been defined:
Protocol Number | Name |
0 | View Data |
1 | Real Ear Measurement |
2 | IMC Protocol 2 |
However, HIMSA licensees will be able to define new protocols as necessary.
For more information on these protocols, refer to:
IMC (On-line) Protocol No. 0, View Data Specification
IMC (On-line) Protocol No. 1, Real Ear Measurement
IMC Protocol 2
The Noah IMC protocol 2 is used when a fitting module connects to a Real Ear Measurement module and wishes to receive REM data while fine-tuning a fitting. It is an application-level protocol, that used as an extension to the basic on-line communication facilities supported by the Noah Framework. This protocol was released in November 2015.
Available from Inter-Module Communication (IMC) Documentation when logged in as a member, members\development projects, or simply search for IMC.
Limitations
It’s Not possible to start a Noah 4 IMCServer from a Noah 2 module. All other combinations are supported.
IMC between Noah 3 and Noah 4 modules in any combination is fully supported from Noah version 4.4.0.2280
Implementing details
When implementing either an IMC Client or an IMC Server in Noah 4 it is important to do the following.
Implement either of the IMC interfaces declared in IMCInterfaces.dll, IIMCServerEx or IIMCClient.
Don’t implement the interface IIMCServer since the Command method can’t return data.
In the Class where you implement the one of the IMC Interfaces, IIMCServer or IIMCClient, the following must be done :
The Class must inherit from MarshalByRef.
The Class must override InitialLifeTimeServices and return null.
How IMC Works
In order for the developer’s module to participate in IMC, an IMC interface must be implemented.
The interfaces are in IMCInterfaces.dll
One of two types of interfaces can be chosen for implementation:
Himsa.Noah.IIMCClient – if the module is acting as an IMC Client
Himsa.Noah.IIMCServer – if the module is acting as an IMC Server
Precondition
The IMC server is registered in Noah as an IMC server with the supported protocols.
Starting IMC
The IMC Client and IMC Server will be connected the following way:
The module that implements the IIMCClient interface will find the Module it wants to launch by iterating through the ModuleAPI’s module collection. Once the IMC Server is found the Module calls Module.LaunchIMC.
The Noah Framework will now launch the IMC Server module.
Once the IMC Server gets launched it shall call ModuleAPI.Connect, and a direct reference to the IMC Client is given to the IMC Server module.
Remember the IMC Server must use the same ModuleID when calling ModuleAPI.Connect as when I originally registered itself to Noah.
The IMC Server now acknowledge the IMC connection by calling IIMCClient.ServerReady.
IMC Communication
The IMC Client controls the IMC Server by calling IIMCServer.CommandEx (IIMCServer.Command has a bug)
If the IMC Server has data for the IMC Client then the IMC Server can call IMCClient.DataReady.
IMC End communication
The IMC Client calls IIMCServer.Stop() to end the IMC Communication.
NOTE:
The Noah framework takes no part in the communication between the IMC Client and the IMC Server it is entirely up to the modules to conform to the defined protocols.
NOTE: The View Data Protocol was invented in Noah 2.0 as a method for a fitting module to visualize an audiogram while running. This was not possible otherwise, since Noah 2.0 allowed only one module to be shown on the screen at any one time. In Noah 4, an audiogram module can be shown alongside a fitting module, thus enabling the user to view both an audiogram and a fitting at the same time. Therefore HIMSA does not recommend usage of the View Data Protocol for viewing audiograms in Noah 4.
NOTE:
We strongly recommend that you look through the Noah4 IMC Sample modules, Inter-Module Communication (IMC) Documentation.
Session List Overview
When a module performs an action, such as a hearing aid fitting, this action is added to a session of the selected patient. The Session list is a list of the selected patient’s sessions and each session represents a calendar day. Each session consists of all the actions; fitting, measurement, journal entries, that have taken place during a patient’s visit.
It is assumed that a patient will only visit the hearing specialist’s clinic once on a particular day. Therefore, if an action is added to a patient’s session list within one calendar day of the time that the last session was opened, it will be added to that session. If more than one calendar day has passed since the last session was opened, Noah will open a new, “current session” and the new action will be added to it.
Action description
The name of an action can be divided into two parts:
·Information provided by the Noah system
·Information provided by the module which created the action.
 |
Figure: Action Names |
The first part of the name consists of The User who created the module and the name of the manufacturer. The second part is The Module Description, which is given when the module is registered.
Additional Action Information
It is possible to mouse over a fitting or hearing instrument selection action so that it supplies additional information provided by the module which created the action.