Noah 4 Business System Developers Guide Full Document



Interfacing a Business System to Noah 4
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.


 

Business System Integration with Noah where the Business System owns Data
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. 

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

Preferred Applications
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.

The Database Interface
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.

Patient Table

Field

Type

Description

ID

Int32

Unique (within the database) Patient identifier

PatientGUID

Guid

Global unique patient identifier

ActivePatient

Short

1=true, 0 = false

PatientNo

String(20)

Dispenser’s Patient identification

CreateDate

DateTime

Date of record creation

FirstName

String(30)

Patient’s First Name

LastName

String(30)

Patient’s Last Name

MiddleName

String(30)

Patient’s Middle Name

Gender

Short (enum)

Patient’s Gender {0=Unknown,1=Male,2=Female}

BirthDate

DateTime

Patient’s Birth date

Salutation

String(30)

Salutation

Title

String(30)

Title

Address1

String(30)

Address line 1

Address2

String(30)

Address line 2

Address3

String(30)

Address line 3

Province

String(30)

Province or State

Zip

String(20)

Zip Code

City

String(30)

City

Country

String(30)

Country

 

 

 

HomePhone

String(30)

Home phone

WorkPhone

String(30)

Work phone

MobilePhone

String(30)

Mobile phone

EMail

String(50)

Email

SSNumber

String(20)

Social security number

Physician

String(30)

Main Physician

Referral

String(30)

Physician being referred to

Insurance1

String(30)

Insurance information

Insurance2

String(30)

Insurance information

Other1

String(30)

Other 1

Other2

String(30)

Other 2


NOTE :   The setup tables below, for both user and patient, store setup data as BLOB files. The setup data consist of user, or patient, preferences. For example, NOAHaud stores profile settings as User Setup data. Thus, if a user moves to a different workstation in a network, the user’s specific profile-settings are automatically transferred to that workstation.

Patient Setup Table

Field

Type

Description

PatientID

Int32

ID of associated patient (> patient table)

ModuleID

Int32

ID of module that added this setup

SetupData

BLOB

Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxSetupBlobSize


User Table

Field

Type

Description

UserID

Int32

Unique identifier for user

CreateDate

DateTime

Date of record creation

UserInitials

String(3)

Three letter initials used for logon

UserName

String(30)

Full user name


Action Table

Field Name

Type

Description

ID

Int32

Unique identifier for action

(NOTE: An Action object holds information about an action performed during a patient’s visit. In addition to the actual action data, an Action object contains information about what kind of action it is, what user created it, a description of the action and a reference to an Actions collection of referenced actions. A reference, which is of type long, holds an ActionID of the action it is referencing. ActionReferences link, for example, audiograms to selections/fittings.)

SessionID

Int32

ID of session in which the action belongs (> session)

UserID

Int32

ID of user who created the action (> user table)*

CreateDate

DateTime

Date of creation

LastModifiedDate

DateTime

Date of last modification

Description

String(64)

Description of the action

ModuleID

Int32

ID of module that created the action

DeviceType

Short

Module specific code for external equipment

DataTypeCode

Short

Code describing the action

DataFmtStd

Short

Code describing the format of the PublicData field

DataFmtExt

Short

Code describing the format of the private part of the PublicData field

Removed

BOOL

Action marked as removed

Hidden

BOOL

Action marked as hidden

PublicBlob

BLOB

Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxBigBlobSize

PrivateBlob

BLOB

Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxSmallBlobSize

ActionGroup

DateTime

Value used for Action grouping.


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


Session Table

Field Name

Type

Description

ID

Int32

Unique identifier for session

PatientID

Int32

ID of patient the session belongs to (> patient table)

CreateDate

DateTime

Date of creation (when first action was added)


FastView Table

Field Name

Type

Description

ActionID

Int32

The ID of the action this FastView is related to

LastModifiedDate

Int32

Date of last modification

CreateDate

DateTime

Date of creation

Data

BLOB

Maximum BLOB size can be retrieved through BusinessAPI, GetNoahProperties , MaxFastViewBlobSize

Format

Int32

Pdf = 1, Rtf = 2, Jpg = 3

Version

Int32

Version


Installing the database interface assembly
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.

Business API
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.

More Information_N4 Business System API
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.

Context Header Information
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).

General Purpose Data Porter
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; }

        }

 

     }

}


Edit Old Actions Allowed
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.

Required Programming Tasks
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.

public class Register

    {

        //Registration towards Noah

        private const string _companyName = "HIMSA";

        private const string _cmdLineArgs = ""; //"2";

        private static string _exePath = System.Reflection.Assembly.GetExecutingAssembly().Location;

        private static string _exeStartIn = Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().Location);

        private static string _appName = Path.GetFileNameWithoutExtension(_exePath);

        public static NoahAppType AppType = NoahAppType.BusinessSystem;

       

        public static void Install()

        {

            bool isPreferedApp = true;

            bool b = BusinessAPI.RegisterNoahApp(_companyName, _appName, AppType, _exePath, _exeStartIn, _cmdLineArgs,

isPreferedApp);

            Debug.WriteLine(string.Format("Application '{0}' {1}\r\n", _appName, (b ? "installed" : "not installed")));

        }


        /// <summary>

        /// Unregister or uninstall BusinessSystem APP from Noah.

        /// </summary>

        public static void Uninstall()

        {

            bool b = BusinessAPI.UnregisterNoahApp(_companyName, _appName);

            Debug.WriteLine(string.Format("Application '{0}' {1}\r\n", _appName, (b ? "uninstalled" : "not installed")));

        }


    }


The second step in order to use the Business API is to declare a variable of the type BusinessAPI and then initiate the object declared. The properties available are then initiated when the method Initialize();  on the Business API object is called. During this initialize a connection is made to the Noah Client service, by the use of .NET remoting.

The sample below shows the initialize sequence made for the sample business system.

public BusinessAPI businessApiObj = new BusinessApi();

public MainWindow()

        {

            InitializeComponent();          //Initializing visual components

            treeView1.Nodes.Clear();     // init Treeview used in component             

            loadTreeviewNodes();          // Load treeview nodes 

            try

            {

                businessApiObj.Initialize(“MyServer”, null, NoahAppType.BusinessSystem);  //Init The Business API

                InitializeBackgoundWorker();   // Setting up a bagground worker

                backgroundWorker1.RunWorkerAsync("StartUpClient");

                //Setting up the subscription for Noah events to be received from the Business API

     businessApiObj.BusinessApiEvent += businessApiObj_BusinessApiEvent;

               //Check if a patient already is set active in the running instance of the connected Noah Client   

                if (businessApiObj.CurrentPatient != null)

                {

toolStripStatusLabel1.Text = "Current Patient: " +

businessApiObj.CurrentPatient.FirstName + " " +                                                

businessApiObj.CurrentPatient.LastName;

                               toolStripStatusLabel1.Visible = true;

                }

                loadUserCtrl();

             }

            catch (Exception ex)

 {

     l.log.Debug("BusinessApi_TestApp.MainWindow::MainWindow: "+ex);

}

        }

The next step is to set the user of the Noah system and, perhaps, a patient. The user is set by calling the method SetCurrentUserID, where the argument is an integer with the id of the user.

The language id is set by writing a value to the property LangaugeID on the BusinessAPI object. If not set the language ID is taken from the installed culture of the operating system.

The code sample below shows how the user and the language can be set:

private void LogonUser_Click(object sender, EventArgs e)

{

            //Clear the text fields

            NameText.Clear();

            initialsText.Clear();

            // businessApiObj is the BusinessAPI object, SetCurrentID returns a bool::true in case of success

            bool logon = businessApiObj.SetCurrentUserID(Convert.ToInt32(UserIDText.Text,10));

           

            if (logon == true)

            {

                NameText.Text = businessApiObj.CurrentUser.Name;

                initialsText.Text = businessApiObj.CurrentUser.Initials;

                EventArgs arg = new EventArgs();

                //Send an event to the mainwindow to indicate that the logon of the user vent well

                if (HandlelanguageID != null)

                              HandlelanguageID(this, arg);

            }


 }

 private void Refresh_Click(object sender, EventArgs e)

 {

            businessApiObj.CurrentUser.Refresh();

 }

private void SetLangaugeId_Click(object sender, EventArgs e)

{

            // businessApiObj is the BusinessAPI object, LanguageID is a propertity on the businessApi

            businessApiObj.LanguageID =  Convert.ToInt32(languageID.Text,10);

            EventArgs arg = new EventArgs();

            if (HandlelanguageID != null)

                HandlelanguageID(this, arg);

}


The patient is set by calling the method SetCurrentPatientID. This method is located on the Business API object.

The patientId is an integer greater than 0. If the id is set to 0 or less, Noah Client will deactivate the current patient and no patient will be active in Noah. When the patient ID is set it will be possible to get the session data related to the given patient from the CurrentPatient property on the BusinessAPI object.

// businessApiObj is the BusinessAPI object, SetCurrentPatientID returns a bool::true in case of success

bool setPatient = businessApiObj.SetCurrentPatientID(Convert.ToInt32(textBox13.Text, 10),false);

           if (setPatient == true)

            {

                UpdateCtrl(bus.CurrentPatient);

                OnSetPatientHandle();

            }



Compiler Settings
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.   

Event Handling
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.

// businessApiObj is the BusinessAPI class initiatiated

businessApiObj.BusinessApiEvent += new  BusinessAPIEventDelegate(businessApiObj_BusinessApiEvent);

void businessApiObj_BusinessApiEvent(IBusinessApiEventArg arg)

        {

            string argEvent = arg.EventType.ToString();

            switch (arg)

               {

                case "ActionActivated":

                       break;

                case "ActionAdded":

                       break;

               case "ModuleFilterChanged":

                       break;

                default:

                    break;              

               }

       }



IMPORTANT: When handling events related to sessions and actions it is very important to test that the event is related to the current client as event related to a former current client may be received after the business system has changed client.

 

IMPORTANT: When using the Business API for Noah 4 the business system developer must be aware of a potential “Cross thread operation not valid exception” when trying to access a control by a thread other than the thread under which the control was created. This can be handled by either invoking any access to a control created by the event tread or implementing background work for the business system GUI when implementing in .NET. For further information, please refer to ‘Programming .NET components’, second edition, ISBEN-13: 978-0-596-10207-4 by Juval Lövel.

Introduction_N4 Business System API

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.


Launching and Connecting to Noah 2/3/4 Modules
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.

private void TreeView1_nodeMouseDoubleClick(object sender, TreeNodeMouseClickEventArgs e)

{

            string name = e.Node.Name;

            if (e.Button.ToString() == "Left")

            {

                switch (name)

                {

                    case "Actions":

                        {

Action action = (Action) e.Node.Tag;

Module module = (Module) action.Module;

module.LaunchWithAction(action);

break;

                        }

                    default:

                        break;

                }

            }

}



Disconnecting or Closing Noah 2/3 Modules
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.

void Ctrl_StopModule(object obj, ModuleEventArg arg)

        {

            Module module = arg.Module;

            RunningModule runningModule = arg.RunningModule;

            foreach (Module mod in businessApiObj.Modules)

            {

                if (mod.CompareTo(module) == 0)

                    mod.SafeToCloseEx(runningModule.ModuleID, runningModule.RunningModuleHandle);

     }    

   }


If Noah Client returns with ModuleCloseAccepted then the module is closed and the business system developer does not need to do anything.


If the Module declines the close request then the business system can force a close and/or disconnect. This is done by calling the method CloseModule on the module. The same method can be used if the business system needs to force the module to close. Refer to the sample code below:

void Ctrl_StopModule(object obj, ModuleEventArg arg)

        {

            Module module = arg.Module;

            RunningModule runningModule = arg.RunningModule;

            foreach (Module mod in businessApiObj.Modules)

            {

                if (mod.CompareTo(module) == 0)

                    mod.CloseModule(runningModule.ModuleID, runningModule.RunningModuleHandle);

     }    

  }           


NOTE: All objects in the Business API, which are defined as ‘information holders’ will implement a method called CompareTo. This is due to the base class IComparable which the information holder inherits from the Noah 4 implementation. 

Error Handling_N4 Business System API
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.

private void Remove_Click(object sender, EventArgs e)

        {

           int index = Convert.ToInt32(this.textBox2.Text, 10);

            try

            {

                if (m_actionType == "Actions")

                {

                    m_Session.Actions.Remove(index);

                }

                else

                {

                    m_businessApiObj.UnboundActions.Remove(index);

                }

               

            }

            catch(Noah_E_Action_Already_RemovedException Ex)

            {

                MessageBox.Show(ex.ToString(), "Exception", MessageBoxButtons.OK, MessageBoxIcon.Error);

            }

            catch(Exception ex)

            {

                MessageBox.Show(ex.ToString(), "Exception", MessageBoxButtons.OK, MessageBoxIcon.Error);

            }

   }


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

public enum NOAHErrorType
{
NoahError = -2147221504, // 0x80040000
NOAH_VARIANT_ERROR = -2147220992, // 0x80040200
NOAH_E_VARIANT_WRONG_VT = -2147220991, // 0x80040201
NOAH_E_VARIANT_TOO_MANY_DIMENSIONS = -2147220990, // 0x80040202
NOAH_E_VARIANT_UNABLE_TO_READ = -2147220989, // 0x80040203
NOAH_E_VARIANT_UNABLE_TO_WRITE = -2147220988, // 0x80040204
NOAH_E_VARIANT_SAFEARRAY_TOO_LONG = -2147220987, // 0x80040205
NOAH_E_VARIANT_SAFEARRAY_TOO_SHORT = -2147220986, // 0x80040206
NOAH_E_VARIANT_SAFEARRAY_LENGTH_MISMATCH = -2147220985, // 0x80040207
NOAH_E_VARIANT_SAFEARRAY_INVALID_DATA = -2147220984, // 0x80040208
NOAH_E_VARIANT_SAFEARRAY_INVALID = -2147220983, // 0x80040209
NOAH_E_VARIANT_SAFEARRAY_ILLEGAL_DIMENSIONS = -2147220982, // 0x8004020A
NOAH_DB_ERROR = -2147220960, // 0x80040220
NOAH_E_DB_UNKNOWN_PROPRIETARY_ERROR = -2147220959, // 0x80040221
NOAH_E_DB_BAD_OBJECT = -2147220958, // 0x80040222
NOAH_E_DB_UNABLE_TO_ACCESS_DB = -2147220957, // 0x80040223
NOAH_E_DB_CLIENT_NOT_FOUND = -2147220956, // 0x80040224
NOAH_E_DB_USER_NOT_FOUND = -2147220955, // 0x80040225
NOAH_E_DB_SETUP_NOT_FOUND = -2147220954, // 0x80040226
NOAH_E_DB_SESSION_NOT_FOUND = -2147220953, // 0x80040227
NOAH_E_DB_ACTION_NOT_FOUND = -2147220952, // 0x80040228
NOAH_E_DB_ACTIONREF_NOT_FOUND = -2147220951, // 0x80040229
NOAH_E_DB_PRODUCT_NOT_FOUND = -2147220950, // 0x8004022A
NOAH_E_DB_PRODUCTREF_NOT_FOUND = -2147220949, // 0x8004022B
NOAH_E_DB_PREFERENCE_NOT_FOUND = -2147220948, // 0x8004022C
NOAH_E_DB_PREFERENCE_ALLREADY_EXISTS = -2147220947, // 0x8004022D
NOAH_E_DB_UNBOUNDACTION_NOT_FOUND = -2147220946, // 0x8004022E
NOAH_E_DB_UNBOUNDACTIONREF_NOT_FOUND = -2147220945, // 0x8004022F
NOAH_E_DB_UNABLE_TO_READ_PREF_DB_GUID = -2147220944, // 0x80040230
NOAH_E_DB_OBJECT_NOT_FOUND = -2147220943, // 0x80040231
NOAH_E_DB_SCOPE_NULL = -2147220942, // 0x80040232
NOAH_SERVER_ERROR = -2147220912, // 0x80040250
NOAH_E_NS_REG_DATATYPE = -2147220911, // 0x80040251
NOAH_E_NS_REG_MODULECATEGORY = -2147220910, // 0x80040252
NOAH_E_NS_REG_MANUFACTURER = -2147220909, // 0x80040253
NOAH_E_NS_REG_PRODUCTCATEGORY = -2147220908, // 0x80040254
NOAH_E_NS_DB_NOT_AVAILABLE = -2147220907, // 0x80040255
NOAH_E_NS_MANUFACTURER_NOT_FOUND = -2147220906, // 0x80040256
NOAH_E_NS_COOKIE_NOT_FOUND = -2147220905, // 0x80040257
NOAH_E_NS_REG_LICENSE = -2147220904, // 0x80040258
NOAH_E_NS_UNABLE_TO_ACCESS_STGFILE = -2147220903, // 0x80040259
NOAH_E_NS_INVALID_LICENCE = -2147220902, // 0x8004025A
NOAH_E_NS_MAXUSERS_EXCEEDED = -2147220901, // 0x8004025B
NOAH_E_NS_STGTRANSFER_FAILED = -2147220900, // 0x8004025C
NOAH_E_NS_LICENCE_EXPIRED = -2147220899, // 0x8004025D
NOAH_E_NS_LICENCE_CLOCK_TURNED_BACK = -2147220898, // 0x8004025E
NOAH_E_NS_INVALID_LICENCE_FOR_NOAH_SYSTEM = -2147220897, // 0x8004025F
NOAH_E_NS_LICENCE_ONLY_VALID_FOR_NOAH_SYSTEM = -2147220896, // 0x80040260
NOAH_E_NS_LICENCE_WMISERVICE_NOT_STARTED = -2147220895, // 0x80040261
NOAH_E_NS_LICENCE_HARDWARE_CHANGED = -2147220894, // 0x80040262
NOAH_E_NS_LICENCE_BLACKLISTED = -2147220893, // 0x80040263
NOAHCLIENT_ERROR = -2147220480, // 0x80040400
NOAHCLIENT_E_CANT_BROWSE_REGISTRY = -2147220480, // 0x80040400
NOAHCLIENT_E_CANT_LAUNCH_NOAHSERVER = -2147220479, // 0x80040401
NOAHCLIENT_E_MODULE_ALREADY_INSTALLED = -2147220478, // 0x80040402
NOAHCLIENT_E_ORPHANOUTOFDATE = -2147220477, // 0x80040403
NOAHCLIENT_E_UNABLE_TO_INSTALL = -2147220476, // 0x80040404
NOAHCLIENT_E_NO_USER = -2147220475, // 0x80040405
NOAHCLIENT_E_NO_CLIENT = -2147220474, // 0x80040406
NOAHCLIENT_E_NO_MODULES = -2147220473, // 0x80040407
NOAHCLIENT_E_UNABLE_TO_NOTIFY = -2147220472, // 0x80040408
NOAHCLIENT_E_MODULE_NOT_RUNNING = -2147220471, // 0x80040409
NOAHCLIENT_E_NO_LATESTSESSION = -2147220470, // 0x8004040A
NOAHCLIENT_E_TO_MANY_MODULES = -2147220469, // 0x8004040B
NOAHCLIENT_E_UNABLE_TO_UNINSTALL = -2147220468, // 0x8004040C
NOAHCLIENT_E_CANT_RETRIEVE_SETTINGS = -2147220467, // 0x8004040D
NOAHCLIENT_E_TRANSACTION_STARTED = -2147220466, // 0x8004040E
NOAHCLIENT_E_COULDNT_REGISTER_MODULE = -2147220465, // 0x8004040F
NOAHCLIENT_E_MODULES_RUNNING = -2147220464, // 0x80040410
NOAHCLIENT_E_COULDNT_CREATE_ACTIONCOLL = -2147220463, // 0x80040411
NOAHCLIENT_E_COULDNT_LAUNCH_MODULE = -2147220462, // 0x80040412
NOAHCLIENT_E_UNABLE_TO_INSTALL_ACTIONCONVERTER = -2147220461, // 0x80040413
NOAHCLIENT_E_UNABLE_TO_UNINSTALL_ACTIONCONVERTER = -2147220460, // 0x80040414
NOAHCLIENT_E_ACTIONCONVERTER_NOT_FOUND = -2147220459, // 0x80040415
NOAHCLIENT_E_INSTALL_ACTIONCONVERTER_UPDATE = -2147220458, // 0x80040416
NOAHCLIENT_E_STGTRANSFER_FAILED = -2147220457, // 0x80040417
NOAHCLIENT_E_COULDNT_QUERY_CLIENT = -2147220456, // 0x80040418
NOAHCLIENT_E_NOAHSERVER_NOT_RUNNING = -2147220455, // 0x80040419
NOAHCLIENT_E_SERVER_NOT_CONNECTED = -2147220454, // 0x8004041A
NOAH_DISPATCH_ERROR = -2147220224, // 0x80040500
NOAH_E_OBJECT_REMOVED = -2147220224, // 0x80040500
NOAH_E_OBJECT_READONLY = -2147220223, // 0x80040501
NOAH_E_OBJECT_NOT_FOUND = -2147220222, // 0x80040502
NOAH_E_OBJECT_COULD_NOT_READ_PROPERTY = -2147220221, // 0x80040503
NOAH_E_OBJECT_COULD_NOT_WRITE_PROPERTY = -2147220220, // 0x80040504
NOAH_E_SESSION_NOT_CURRENT = -2147220219, // 0x80040505
NOAH_E_ACTION_ALREADY_REMOVED = -2147220218, // 0x80040506
NOAH_E_ACTION_NOT_REMOVED = -2147220217, // 0x80040507
NOAH_E_PRODUCT_ALREADY_REMOVED = -2147220216, // 0x80040508
NOAH_E_PRODUCT_NOT_REMOVED = -2147220215, // 0x80040509
NOAH_E_NOT_INITIALIZED = -2147220214, // 0x8004050A
NOAH_E_ALREADY_INITIALIZED = -2147220213, // 0x8004050B
NOAH_E_NO_CURRENT_USER = -2147220212, // 0x8004050C
NOAH_E_NO_CURRENT_CLIENT = -2147220211, // 0x8004050D
NOAH_E_INTERNAL_ERROR = -2147220210, // 0x8004050E
NOAH_E_MODULE_NOT_SAME = -2147220209, // 0x8004050F
NOAH_E_ACTION_DESCRIPTION_EMPTY = -2147220208, // 0x80040510
NOAH_E_BAD_IMCSERVER = -2147220207, // 0x80040511
NOAH_E_NO_PRINTHANDLER = -2147220206, // 0x80040512
NOAH_E_ILLEGAL_IMODULEPRINT = -2147220205, // 0x80040513
NOAH_E_ERROR_LOADING_LEGACYPRINTHANDLER = -2147220204, // 0x80040514
NOAH_E_CAN_NOT_CREATE_PRINTER_DC = -2147220203, // 0x80040515
NOAH_E_INVALID_DATATYPE = -2147220202, // 0x80040516
NOAH_E_DATATYPE_READONLY = -2147220201, // 0x80040517
NOAH_E_MODULE_NOT_INSTALLED = -2147220200, // 0x80040518
NOAH_E_ILLEGAL_CATEGORY = -2147220199, // 0x80040519
NOAH_E_NOSPACE = -2147220198, // 0x8004051A
NOAH_E_NOCONVERTER = -2147220197, // 0x8004051B
NOAH_E_NOTLEGAL = -2147220196, // 0x8004051C
NOAH_E_NOTSUPPORTED = -2147220195, // 0x8004051D
NOAH_E_UNABLE_TO_LAUNCH_IMCSERVER = -2147220194, // 0x8004051E
NOAH_E_CREATE_CLIENT = -2147220193, // 0x8004051F
NOAH_E_STGTRANSFER_FAILED = -2147220192, // 0x80040520
NOAH_E_UNABLE_TO_CREATE_DC = -2147220191, // 0x80040521
NOAH_E_ACTIONCOLL_NOT_AVAILABLE = -2147220190, // 0x80040522
NOAH_E_REPORTGENERATOR_NOT_INSTALLED = -2147220189, // 0x80040523
NOAH_E_ACTION_NOT_FOUND_IN_DB = -2147220188, // 0x80040524
NOAH_E_MAX_SETUPBLOBSIZE_EXCEEDED = -2147220187, // 0x80040525
NOAH_E_MAX_PUBLICBLOBSIZE_EXCEEDED = -2147220186, // 0x80040526
NOAH_E_MAX_PRIVATEBLOBSIZE_EXCEEDED = -2147220185, // 0x80040527
NOAH_E_NO_PARENT = -2147220184, // 0x80040528
NOAH_E_NO_OFFICESERVER_RUNNING = -2147220183, // 0x80040529
NOAH_E_UNBOUNDACTION_ALREADY_REMOVED = -2147220182, // 0x8004052A
NOAH_E_UNBOUNDACTION_NOT_REMOVED = -2147220181, // 0x8004052B
NOAH_E_MAX_MANUFACTURERBLOBSIZE_EXCEEDED = -2147220180, // 0x8004052C
NOAH_E_MAX_FASTVIEWBLOBSIZE_EXCEEDED = -2147220179, // 0x8004052D
}

 


Overview of Transparent Noah
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.

IBSCallBack
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


User and PatientManager preinitializing
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.

public class NoahPreInitSample: IBSCallBack {

              public void Uninitialize() {

                     Himsa.Noah.BusinessAPI.NoahPreInit.PreUninit();

              }

              public void Initialize() {

                     try {

                           Himsa.Noah.BusinessAPI.NoahPreInit.PreInit(new

RequestBSConnectNC(ConnectRequestCallback));

                     }

                     catch (Exception ex) {

                           l.log.Error("PreInit()", ex);

                           throw;

                     }

              }

              private BusinessAPI _businessServer;

              private bool ConnectRequestCallback() {

                     if (_businessServer == null) {

                           _businessServer = new BusinessAPI();

                           try {

                                  _businessServer.Initialize(“MyServer”, null, this,

NoahAppType.PatientManger);

                           }

                            catch (Exception ex) {

                                  l.log.Error("Initialize() ", ex);

                           }

                     }

                     return true;

              }


              #region IBSCallBack Members


              public bool GetPatientIDsByInfo(object PatientInfo, out int[]

PatientID) {

                     throw new NotImplementedException();

              }

              public bool Login(out int UserID) {

                     // Simulate selecting user with id 8

                     UserID = 8;

                     return true;

              }

              public bool SetPatientIDByInfo(int[] PatientIDs, out int PatientID) {

                     // Simulating we selects patient with id 1

                     PatientID = 1;

                     return true;

              }

              #endregion

       }


TODO:

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

Fast Data View for Business Systems

Fast Data View


With Noah 4.7 HIMSA has added the Fast Data Viewing feature, providing Professionals with immediate access to patient data without opening the Noah modules!

If the Noah module supports Fast Data Viewing, the Professional will see an eye icon next to the module action in the Sessions list.  Fast Data Viewing allows Noah modules to save a report with important patient information. The content and design of the report is set by the module developer.

Business API


The implementation of Fast Data view has resulted in an updated database interface. It is mandatory to comply with this database interface in order to certify for Noah 4.7 and onwards. The new functions are updated in the BusinessAPI namespace in the BusinessAPI.chm file and in the database tester.

Please note the “FastViewsEnabled Property” that can be set by the user of the Business System, if the Business System gives the user this option. If this property is set to “False” then Noah Client will not send the FDV to the Business System, and it is simply deleted. The property is meant for users that does not wish to use FDV and thereby do not wish to populate the database.

NHAX Import/Export

The NHAX format is prepared to include the FDVs so that these can be sent from one Business System to another.


Installation of Noah and Basic Modules with a Business System
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:

Version

Description

4.0

Initial release of Noah 4.

4.1

Added the optional BM property and the mandatory DBIF property. The bootstrapper setup.exe (Approx. 5MB in size) must be used instead of the main setup.exe (Approx. 20MB in size).

4.2

The DBIF property is now optional. Added the /w parameter and the mandatory EULAACCEPTED property.

4.8

The /w parameter has been changed to /clone_wait.

Noah 4 installation:

When installing Noah 4 as part of your Business System installation - the setup.exe file (the bootstrapper which has a file size of approx. 5MB), located in the ‘CD’ folder below must be launched with a command line.

The following command line must be modified and used to launch the Noah 4 installation when performing an OAS installing. An OAS installation is a Business System other than Noah System:

Setup.exe /s /clone_wait /v "/qn /L*vx+ \"%temp%\Noah4_OAS_XXXXX.log\" OAS=1 EULAACCEPTED=YES BM=value DBIF=\"filepath\""


This Setup.exe file is actually a bootstrapper for the Setup.exe file located in the Installation folder which when launched unpacks and executes a noah4.msi file.


A Breakdown of the setup.exe command line follows:

1)    The /s parameter is an Installshield command line parameter and means that the setup.exe file is launched in silent mode. No GUI and user interaction.

2)    The /clone_wait parameter is an Installshield command line parameter. This parameter forces the installation to wait until the installation is complete before exiting.

3)    The /v parameter is also an Installshield parameter which means that everything enclosed in double quotes is passed as a command line to the MSI Installer.

4)    The /qn part tells the MSI Installer that the installation has no GUI and requires no user interaction.

5)    The /L*vx+ part means that extended logging is performed during installation of Noah 4 (see help for MSIExec.exe for further details).

6)    [Mandatory]: The path provided, ("%temp%\Noah4_OAS_XXXXX.log"), in the inner set of double quotes is the file path for the installation log. %temp% represents the computers temp folder – in the Noah4_OAS_XXXXX.log file name the XXXXX part must be replaced with a suitable name e.g. Noah4_OAS_ProductName.log.

7)    [Optional]: See example 2 in Command Line examples: for required steps when NOT specifying this property. The DBIF="filepath" part lets the Noah 4 installer know that the Business System’s Database Interface assembly specified by the absolute file path "filepath" should be used by Noah 4. In the final phase of the Noah 4 installation a windows service named NoahServer will be started. This service will during start up load the assembly specified via the DBIF property. This means that the assembly must be available when installing Noah.  

8)    [Mandatory]: The OAS=1 part lets the Noah 4 installer know that this is a Business System installation in progress. The Installation for a Business System is different than the basic Noah 4 System installation – e.g. No shortcuts to the Noah 4 System will be created and a special registry key will be created that informs Noah that this is an OAS installation.

9)    [Optional]: The BM=value part lets the Noah 4 installer know that the Basic Modules specified by ‘value’ should also be installed. See Table above : Basic Modules values. If the BM property isn’t specified then no Basic Modules will be installed.

10)  [Mandatory]: The EULAACCEPTED property must be assigned the value ‘YES’ if the installation is passive. Passive installations are e.g. silent installations and installations without user interaction but with limited GUI that shows the installation progress.

Basic Module installation:

As an alternative to using the BM property it is also possible to install Basic Modules by launching the Basic Module installer located in the ‘CD\Installation\BasicModules’ folder. This installer requires the following command line to install the Basic Modules:

Setup.exe --Passive --Modules=value


The optional ‘Passive’ parameter instructs the Basic Module installer to perform the installation without user interaction.

The optional ‘Modules’ parameter along with the specified ‘value’ instructs the Basic Module installer to install the modules specified by ‘value’ – see Table: Basic Modules values below.


Noah 4 must be installed before you can install Basic Modules. To install the Journal module without user interaction you can use this command line:

Setup.exe --Passive --Modules=4

The setup.exe file is the one located in the ‘CD\Installation\BasicModules’ folder.

Table: Basic Modules values

value

Installed Basic Modules

1

Audiogram Module

2

Questionnaire Module

3

Audiogram Module + Questionnaire Module

4

Journal Module

5

Journal Module + Audiogram Module

6

Journal Module + Questionnaire Module

7

Audiogram Module + Questionnaire Module + Journal Module


Database Interface registration:

As an alternative to using the DBIF property it is also possible to register the database interface assembly after you have installed Noah 4. See example 2 in Command Line examples:

Command Line examples:

Example 1:

Description: Install Noah 4 silently without user interaction. We wish to create a log file in the %temp% folder named ‘Noah4_OAS_SuperProduct.log’. In addition to the Noah 4 installation we also want to install the Journal module. The Business System’s database interface assembly is available from this location ‘C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll’.


Resulting Command Line: Setup.exe /s /clone_wait /v "/qn /L*vx+ \"%temp%\Noah4_OAS_ SuperProduct.log\" OAS=1 EULAACCEPTED=YES BM=4 DBIF=\"C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll\""


Additional Steps:

1) If required install a Noah license.

Example 2:

Description: Install Noah 4 silently. We which to create a log file in the %temp% folder named ‘Noah4_OAS_SuperProduct.log’. In addition to the Noah 4 installation we also want to install the Journal module.

In this example we do not want to install the Database interface assembly prior to the Noah 4 installation hence we do not specify the DBIF property.

In order to register the database interface with Noah when it has been installed e.g. by the Business System, we must call an executable file named NoahConfig.exe located in the Noah 4 installation folder.


Resulting Command Line: Setup.exe /s /clone_wait /v"/qn /L*vx+ \"%temp%\Noah4_OAS_SuperProduct.log\" OAS=1 BM=4 EULAACCEPTED=YES"


Additional Steps:

1) Register database interface:

The path to the Noah 4 installation folder is available via a registry key:

HKEY_LOCAL_MACHINE\Software\HIMSA\InstallationInfo\Noah\v4\InstallPath


We will assume that the database interface assembly is available from this location: ‘C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll’.


Assuming the Noah 4 installation path is: ‘C:\Program Files\Himsa\Noah4’ then we can call the NoahConfig.exe located in that folder. We need to specify a command line for the executable which will register the database interface and restart the Noah Server Service.

Command Line: "C:\Program Files\Himsa\Noah4\NoahConfig.exe" –dbifrss="C:\Program Files\SuperProduct\SuperDatabaseAssembly.dll"

 

If registration of the database assembly is done by the use of NoahConfig a stop and start of Noah server service is necessary. (If you use the setup.exe option a restart of the system is forced upon the user) A start and stop of a service require elevated rights, which once in while is not obtainable. To solve this issue is the NoahConfig exe is enhanced by 2 arguments –NoahServerStop and –NoahServerStop, which can ask the NoahserverService to stop and start by the use of NoahClientService.   


2) If required install a Noah license.

Prerequisites for Noah 4

Noah 4 has some prerequisites of its own. The following Microsoft prerequisites will be installed as part of the Noah 4 installation if required:

1)    Windows Imaging component (WIC)

2)    Microsoft .NET Framework 4.0 (Full)

3)    Microsoft SQL CE 3.5 SP2


These prerequisites are located in the ‘CD\Installation\ISSetupPrerequisites’ folder.

IMPORTANT:

Please observe that Noah 4 has Microsoft .NET Framework 4.0 as a prerequisite.  Installing on a system without Microsoft .NET Framework 4.0 may require several minutes to install.



Noah 4 Extended Native Format (Nhax and Enhax)
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 

Please note that users imported into Noah ES are done so by creating an inactive user.

The USERSECTION contains all the UserInitials for the patients in XML.

<?xml version="1.0" encoding="utf-16"?>

<Users>

  <User>

    <Initials>ABC</Initials>

    <Name>ABC</Name>

    <UserName>ABC</UserName>

  </User>

</Users>

MISCSECTION 

Not used, but available for expansion.

Enhax Format

Enhax is supported in the SDK source code for the Nhax viewer.

Enhax is the same as Nhax, except that it uses password protected compression. It is implemented using SharpZipLib with AESKeySize set to 256, compression level set to 9 (range: 0-9) and compression type is 'Deflated'.

Noah Mobile SDK Business System Documentation
With the release of Noah 4.5, Noah Mobile services were made available to Noah users. 


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

Microsoft has announced that for security reasons, it is retiring/migrating their Azure Access Control Service (ACS) by November 7th, 2018.Noah versions prior to Noah 4.9 are all set up with encryption keys of the ACS type. This means that from November 7th 2018, Noah Mobile apps will no longer be able to communicate with Noah System versions prior to Noah 4.9 or Noah compatible business systems based on Noah 4.8 and earlier. To avoid issues with your Noah Mobile app, please ensure that your customers upgrade to Noah 4.9.1 before this date to ensure continued communication. Business Systems which support Noah Mobile apps will also need to use Noah 4.9 and later. When your customer upgrades to Noah 4.9, the upgrade process will migrate the user to use SAS keys for data encryption.


Noah Mobile is an extension of the Noah 4 Framework which allows apps e.g. on a mobile device to access Noah data from a Noah 4 Business System via the Noah Mobile REST API. This SDK documentation provides the necessary guidelines for adding Noah Mobile to your existing Business System.

IMPORTANT: It is a mandatory requirement for all business system member companies to add Noah Mobile support to their Noah-compatible Business System.

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


Guidelines for implementing Noah Mobile in your Business System
Business Systems that support Noah 4.5 must also support Noah Mobile. In order to do so, it is important to perform the following steps. 

  • The Database and database interface must conform to the functions described in this section (and in the Namespace section of the BusinessAPI.chm file)

  • The Database implementation must be successfully tested with the Database tester tool

  • The Business System must have a user dialogue where the user can enable/disable Noah Mobile

    • Please note that Noah Mobile is turned off in Noah 4.5 by default

  • The End User License Agreement (EULA) is updated for Noah Mobile and should be accepted by the Noah user


For more information on Business System development, please refer to the Namespace section of the BusinessAPI.chm file and the Business API.

Noah Mobile - Cloud Environments

Enable/Disable Patient management through Noah Mobile

Resetting Noah Mobile during the development process

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

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

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

When you develop a Business System you should take into consideration that HIMSA's sample apps will all point to the External Test environment, so if you wish to use them you can point your Business System Noah Mobile installation to use this environment during development. Alternatively you can change the sample apps to use the Production environment.

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

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

You can use the “NoahMobileEnvSelect” on the Noah 4 Mobile Development page to switch environment.

Enable/Disable Patient management through Noah Mobile
In the first version of Noah Mobile, a Business System can decide if it should be possible for app users to perform Patient Management through the Noah Mobile API. Patient management means that the app can have access to create patients or edit demographic data on the patient

  • public void MobileAppEditPatientsEnable(bool Enable)

    • Enable patient management if Enable is true, else disable (enable is false)

The Noah Mobile compatible app will get the following reply from Noah when asking:

  • public bool MobileAppEditPatientsEnabled()

    • Returns true if patient management is enabled, else false

    • If MobileAppEditPatientsEnabled is false the app should not show GUI that allows for Patient management

Resetting Noah Mobile during the development process
During the development process, you may need to switch your Noah installation back to a “pre-mobile” state, before you enabled Noah Mobile. This can be an advantage when you wish to test your development progress.

To reset during your installation, use the “NoahMobileReset.exe” utility provided on the Noah Mobile SDK page.

Changes to the Database and Database Interface
With the Noah 4.5 release, HIMSA added the following new classes and functions for use with Noah Mobile. 

For detailed information, refer to the namespace in the BusinessAPI.chm file.


New/changed classes in the NoahDataObjects namespace

The following new classes are included in the NoahDataObjects namespace: 

  • AppPermission

  • MobileApp

  • UserPrivilege

Changed classes

  • Patient: Added property: LastModifiedDate

New functions in the Database Interface

The following new functions are declared in the database interface

  • void PutMobileAppPermissions(int ModuleID, int[] PermissionIDs, object callContext)

  • int[] GetMobileAppPermissions(int ModuleID, object callContext)

  • void DelMobileAppPermissions(int ModuleID, int[] PermissionIDs, object callContext)

  • void PutAppPermissions(AppPermission[] appPermissions, object callContext)

  • AppPermission[] GetAppPermissions(object callContext)

  • void DelAppPermissions(AppPermission[] appPermissions, object callContext)

  • void RegisterMobileApp(MobileApp mobileApp, object callContext)

  • void UnregisterMobileApp(int ModuleID, object callContext)

  • MobileApp[] GetMobileApps(object callContext)

  • Patient PutPatient(Patient patient, object callContext)

  • User GetUser(string UserName, object callContext)

  • NoahDataObjects.Actions[] GetActions(int PatientID, ActionFilter ActionFilter, object callContext)

  • NoahDataObjects.Patient[] GetPatients(string searchText, int Page, int PageSize, ref int? QueryTotalNoOfPatients, object callContext)

  • bool ValidateLogin(string username, string password, out int userid, object callContext)

  • Patient[] GetUpdatedPatients(int Page, int PageSize, DateTime StartDateTime, DateTime? EndDateTime, object callContext);

  • ActionEx[] GetUpdatedActions(int Page, int PageSize, DateTime StartDateTime, DateTime? EndDateTime, int [] DataTypes, object callContext)

  • NoahDataObjects.Action[] ActionreferencedBy(int ActionID)

  • UserPrivilege GetUserPrivilege(int userUD, object callContext)


AppPermission Class

The AppPermission class describes the permissions that relates to the properties in the patient object e.g. if a property is required when creating/updating a patient object the required is set to true. A detailed description of the AppPermission class is found in the namespace in the BusinessAPI.chm file. The Noah Mobile Compatible apps will read the AppPermission Class and from there create data to be updated/inserted in the Business System If MobileAppEditPatientsEnable is set to true.

One important field in the AppPermission class is the ReadOnly field, when this field is true the administrator is not allowed to change the Default property. HIMSA requires that the ReadOnly field and default is set to true for the following properties: ID, FirstName, LastName, Gender, BirthDate. This is the minimum dataset that an App can request from the Business System. 

When calling the GetAppPermissions function that must be implemented in the database interface the returned array must contain a row describing the following names that correspond to a property in the Patient class defined in NoahDataObjects. This is the only row that the function must return.

The following is the HIMSA default in Noah System:

  • Default

    • The fields where default set to true is the default fields that any app will have access to read when it is registers

    • Note that different apps can have access to different data depending on the App permissions for the app. 

  • ReadOnly

    • Fields with ReadOnly means that the system MUST, as a minimum, always have these fields set to the Default

  • Required 

    • Required fields are the fields that the Business system requires to add a patient

    • The App will know this and should ask that the user fills in these data to create a patient

      • They must be set, but if the MobileAppEditPatientsEnable is set to false it will not matter


      All business systems must initialize the AppPermission table. The table initialized must have the same number of rows as the table shown below, but the business system may change a few values. In rows where the ReadOnly field is true all the other column values must be the same as in the table shown below. In rows where the ReadOnly column is false, the business system is free to choose the initialization values for the Default and Required column (the values must be true or false). The other values must be same as in the table shown below.

Besides these fields there will also be properties like ID, PatientGUID, CreatedBy, LastModified, etc. that always will be returned and cannot be changed by the Business System.

Implementing a Noah Mobile Configuration Dialog
HIMSA has created and shared the following dialog as an external component. You can use this dialog as is to provide your users with the ability to configure and enable/disable Noah Mobile. 


IMPORTANT: Due to the GDPR implementation in Noah 4.9, HIMSA has discovered additional dependencies that must be included in order to implement the Noah Mobile Configuration window that resides inside NoahExternalComponents.dll. It is necessary to extract the following three dlls from the %ProgramFiles(x86)%\Himsa\Noah 4\ folder of the Noah installation and place them with your exe and NoahExternalComponents:

  • MouseKeyboardActivityMonitor.dll 3.0.1.21726

  • MoonPdfLib.dll 0.3.0.0

  • libmupdf.dll 2.2.1.0

For examples on how the dialog can be implemented in your business system, please refer to the Sample Business System

Developing your own user dialogue for enable/Disable Noah Mobile

You can also choose to implement your own Noah Mobile configuration dialog using the following new functions in the BusinessAPI:

/// PutMobileAppPermissions inserts/updates the permissions for a given app identified by a module ID.
public void PutMobileAppPermissions(int ModuleID, int[] PermissionIDs)
/// Retrieves the permissions for a given app identified by module ID
public int[] GetMobileAppPermissions(int ModuleID)
/// Deletes the given app permissions for a given modules id
public void DelMobileAppPermissions(int ModuleID, int[] PermissionIDs)
/// Convert an array of permission IDs to an array of AppPermision
public AppPermission[] ConvertPermissionIdsToAppPermissions(int[] permissionIDs)
/// Converts an array of AppPermission to an array of permission ids
public int[] ConvertAppPermissionsToPermissionIDs(AppPermission[] appPermissions)
/// PutAppPermissions inserts/updates permissions in the permission table. If PermissionID in the AppPermission class
/// is 0 a new permission is created else an existing permission is updated.
public void PutAppPermissions(AppPermission[] appPermissions)
/// Retrieves all the defined app permissions.
public AppPermission[] GetAppPermissions()
/// Deletes the permissions.
public void DelAppPermissions(AppPermission[] appPermissions)
/// Set the accept state for a number of Mobile Apps
public void PutAppAcceptStates(AppAcceptState[] appAcceptStates)
/// If true, the host name is available (not assigned to this, or any other host).
public bool IsHostNameAvailable(string hostName)
/// Assign the host name to this host. One host can have multiple host names.
public void AddNameToRemoteHost(string hostName)
/// Delete the host name for this host. One host can have multiple host names.
public void DeleteNameForRemoteHost(string hostName)
/// Get the all of the host names for this host. One host can have multiple host names.
public IEnumerable<string> GetNamesForRemoteHost()
/// Transfer the host name from the previous host (associated with the ownership key) the to the current host.
public IEnumerable<string> ClaimRemoteHostNames(string ownershipKey)
/// Change the email address.
public void ChangeEmail(string email)

/// NOT COMPATIBLE: This method is not compatible with this version of Noah it's pre Noah 4.9.
public void PutMobileCnf(MobileCnf Cnf)

/// Use this to setup Noah Mobile. Noah Mobile Configuration (MobileCnf) is moved to there. Alternative is to use NoahExternalComponents which contains a ready made Configuration
/// window. If you choose that solution remember to extract the following three dlls from the %ProgramFiles(x86)%\Himsa\Noah 4\ folder of the Noah installation and place them with
/// your exe and NoahExternalComponents. MouseKeyboardActivityMonitor.dll 3.0.1.21726, MoonPdfLib.dll 0.3.0.0, libmupdf.dll 2.2.1.0

public Provision ProvisionCreate()

/// This Class encapsulate the setup of Noah Mobile
/// To Provision do the following :
/// Get Property MobileCnf that returns a MobileCnf object.
/// Call GetDataProcessingAgreement ít retuns a object that contains a PDF document to be accepted by the user.
/// Title, Name, Company and Email must be filled in by the user before calling PutDataProcessingAgreement.
/// Put Property MobileCnf with the data filled in.
/// Then to save on the server call Submit.
public class Provision

/// <summary>
/// Get latest Data Processing Agreement for the user to accept, in the current Noah Language for the CountryLCID set in the parameter, in order to be able to use NoahMobile.
/// If the user doesn't accept it NoahMobile can't be enabled over the internet.
/// <param name="CountryLCID">The LCID of the country whos Data Processing Agreement is to be returned.</param>
/// </summary>
public DataProcessingAgreement GetAgreement(int CountryLCID)

/// <summary>
/// Accept the latest Data Processing Agreement, in the current Noah Language. This must be done in order to be able to use NoahMobile.
/// If the user doesn't accept it NoahMobile can't be enabled over the internet.
/// Usage: Call GetAgreement populate Email, Title, Company, and Name and Call PutAgreement.
/// <param name="agreement">The agreement that is accepted.</param>
/// </summary>
public void PutAgreement(DataProcessingAgreement agreement)
/// <summary>
/// This method stores the information on the server.
/// </summary>
public void Submit()



To understand the workings of the above methods, we recommend that you open the Sample Business System and then place breakpoints in each and every method in the “ConfigurationService” class (derived from INoahMobileConfigurationService) and the “NoahMobileConfigWindow” class (derived from Window).  Please note when, why with and  which parameters the methods call. 

Service Apps and the Dashboard
With Noah 4.12 HIMSA has added the ability for Service Apps to send alerts and notifications to Noah.  Business systems integrating with Noah 4.12 and newer are required to support service apps and the Noah Alert Dashboard.  HIMSA's certification policy statement does provide some flexibly on the timing of required implementation, please see section Business System Adoption of Newer Versions of Noah for more details.


 

Above: Entries in the session list have been made for patient Amy Connor, by a Service App. The Dashboard icon (the “Globe”) has the number “4” on a red background, indicating that there are 4 unread alerts.


 

Above: Shows the alerts for the patients, and the corresponding (if any) entries in the session list. The Dashboard is in many ways like an inbox in an email app.

 

Service Apps

First, a few definitions:

  • Manufacturer. Generally refers to a hearing instrument manufacturer. It could also mean an audiological equipment manufacturer or any general HIMSA member company.

  • Manufacturer Backend. An application or system provided by a hearing instrument manufacturer. A Manufacturer Back End is used to facilitate hearing care services between Noah, Hearing Care Professionals (e.g. audiologists), Manufacturers, and patients.  This system is generally understood to be a larger system controlled and maintained by the hearing instrument manufacturer.  However, the Manufacturer Back End could also be a smaller system such as an MS Windows-based Noah compatible fitting module.

  • Service App. An application that uses the Noah Web Api to communicate with Noah. In most cases, the Service App is expected to be controlled by the Manufacturer Backend. In contrast to other types of apps using the Noah Web Api, a Service App can be permanently logged in, and thus does not need user interaction.

  • Notification. A message sent from the Manufacturer Backend to Noah via the Noah Web API. The Notification can contain an Alert (a short message that can be viewed on the Dashboard) and/or an entry in the patient’s journal (for example a Journal entry or an Audiogram).

 

How does a Service App differ from the typical Noah Mobile User Interactive App?

  • A Service App uses the same Noah Web Api, but differently:

    • A Service App must register as so. During registration, the Service App must specify (to the Noah installation it requests access to) which level of data access it requests. It is up to the administrator of the Noah installation to grant or deny this data access. The administrator can always revoke a grant/denial. See ‘level of data access’

    • Authentication does not take place with an interactive user rather is facilitated the the approval process (see previous point)

    • A Service App cannot use the Himsa AccessLayer.

A Service App can do most things a User Interactive App can, but is primarily intended to, in prioritized order:

  • Provide a way for the Manufacturer Backend to send Notifications to a Noah installation.

  • Make it possible for the Manufacturer Backend to monitor relevant events (for example addition of new patients or journal entries). See also ‘level of data access’.

 

Level of data access: Events regarding certain types of data (data types 129 Selection, 130 Selection, 131 Fitting, 132 Fitting, 133, 135, 136, 137, 258, 300, 301, 302 and 303 ) are only sent to the Manufacturer backend if they originated from a module from the same manufacturer. Meaning: One cannot “eavesdrop” on the amount of communication with other manufacturers' modules. Other events (e.g. from Audiograms and journal entries - data types 1 and 256) are always sent if requested.

When a Service App registers, it must specify which types of data the app should be able to interfere with, and if the Service App can read/write the type of data and if the Service App should receive events when data with the given datatype is manipulated.

Above: List of apps.


 

Above: Access rights for the ServiceAppSample app.

 

HIMSA provides a ServiceAppSample application (incl. program code) that demonstrates the workings of a Service App.

Dashboard

As mentioned above, the Dashboard adds an inbox-like functionality to Noah. Alerts can be sorted, read, and assigned to users. Alerts can be associated with sessions, which can be opened from within the Dashboard. Once an alert has been dealt with, it can be removed from the Dashboard.


Implementing GUI for Dashboard Alerts

Noah Alert Dashboard Alerts are generated outside Noah, received by Noah and then stored in the database, alongside other data objects (actions, patients, etc.).

By use of methods in the BusinessAPI, it is possible for a business system to read and manipulate the Dashboard Alerts.

The BusinessAPI can also, via its event framework, notify business systems when alert related events take place.

 

There is currently one approach to implementation of GUI for Dashboard Alerts:

  1. Use the Dashboard control provided by Himsa.


Q: Can I create a custom Dashboard for my business system?

A: Currently, this approach is not supported. HIMSA may consider custom dashboards in the future if there are requests for it.  Additionally, the Dashboard and Alerts are new to Noah and to hearing instrument manufacturers there is a good chance that features may need to be adjusted as we gain more experience.

 

Using the Dashboard control provided by Himsa

It is highly recommended looking at the code (especially the file ‘DashboardService.cs’) for the Sample Business System (provided with the Noah installation files).


This is the approach that is used in the Sample Business System. The control is in BusinessSystemExternalControlsLibrary.dll.

  1. Embed the Dashboard control in your own window.

  2. Make your own implementation of a DashboardService that complies with the IDashboardService interface.

  3. For updating Dashboard Alert related information outside the Dashboard control, also look at OnBusinessAPIEvent in the BusinessAPI, and the event types AlertAdded, AlertUpdated and AlertArchived. These can be used to keep the GUI up to date when new alerts are received.

Appendix A
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.


Appendix B - Constant Definitions
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 -