Message Exchange for Social Care and Health: client installation guidance

This guidance explains the installation and configuration of the default MESH client on Windows. There is an additional MESH client advanced and other settings page which offers further information on specific settings and technical requirements, including the installation process for LINUX, that may be applicable for some, but not all, installations. There are links throughout this guidance indicating where these additional options may be applicable for you.

For user guidance on how you use MESH client once installed, including how to send and receive messages, please refer to our MESH client user guide.

MESH is a centralised service managed by NHS Digital. It supports clinical and business processes requiring the secure transfer of data between NHS and affiliated organisations.

MESH consists of a:

1. MESH client - usually integrated into supplier provided applications installed at end-sites (individual organisations).
2. Central MESH server - located within the Spine Core Messaging Service.

MESH client allows secure transfer of data via an encrypted link between the end-site application (your organisation) and the central MESH server. The central MESH server stores data sent to it until the intended recipient site connects to the service and, with its MESH client, collects the data addressed to it over an encrypted link.

Please ensure you have met all the following requirements before beginning the MESH client installation.

The following sections describe the steps for installing the MESH client on a Windows server.

It's assumed that the user performing the installation has logged onto the server with administration rights and has checked that their systems meet the pre-requisites outlined above.

Step 2

Open this pack and click 'Extract to' before choosing the location you wish to extract these files to.

The installation .jar file is named: 'mesh-6.3.6_20220906'. To ensure this file will open and run, right click on the file, click 'Properties' and check that:

• the type of file = executable .JAR file
• it opens with Java ™ or Open JDK

Step 3

Open the .jar file by either double clicking on the icon in your folders, or right-click on the .jar file and click 'Open With', then select the appropriate Java Runtime. 

Alternatively, the .jar file can be opened by opening the Command Prompt (search via your Start button for 'cmd', open the Command Prompt). Rewrite the drive location manually if necessary to where the .jar file is saved.  After the file location in the Command Prompt copy in:

java -jar MESH-<version number>-installer-signed.jar

Write in the version number of the MESH client you are installing (found on the name of the .jar file itself) where the bold text is above. It should look something similar to:

java -jar mesh-6.3.6_20220906-installer-signed.jar

Press 'Enter' on your keyboard, and the installer should open on your screen.

Step 4

You'll now be presented with a screen stating: 'Welcome to the installation of the NHS Digital MESH Client 6.3.6_20220906!'. Click 'Next'.

Step 5

This screen will prompt you to select the installation path. You'll have a suggested path already in the box; this can be changed using the 'Browse' button if you wish to select a new installation path. Once you are happy with your installation pathway, click 'Next'.

Selecting 'Quit' will stop the installation process.

If the target directory exists, you'll be warned that the installer may overwrite files in this directory. Confirm as required, then click 'Next'.

If the target directory does not exist, you'll be warned that the installer will create it. Confirm as required, then click 'Next'.

Step 6

A default folder location for the install will be displayed. If you do not wish to install the client into this folder location, you have the option to change the location via the 'Browse' button.

Once you're satisfied that the appropriate folder location is specified, click 'Next'.

Step 7

You'll now be prompted to provide details of your MESH mailbox and the mailbox type. You'll have received this information when you completed the mailbox request form as part of your pre-requisite checks.

Type your mailbox name into the box indicating 'Mailbox ID'. The mailbox type is set to the default of 'MESH'; if you have a CPIS mailbox, select 'CP-IS - Child Protection Client' from the dropdown, before clicking 'Next'.

Step 8

The Allow Automatic Updates feature has been disabled for all versions of the MESH Client and will default to 'No'.

Click 'Next' to continue.

Step 9

The installer will now summarise the installation tasks it will perform on the 'Summary Configuration Data' page.

If you're happy with your installation, click 'Next'.

Step 10

The installer will now install the required packages.

Once the installation is complete, the screen will show:

• Pack installation programme: Finished
• Overall installation progress: 5/5

Click 'Next'.

Step 11

The installer will now show 'Perform External Processes' in the top right corner of the screen, with 'Processing' in the top centre. This is a summary of its actions. 

Click 'Next'.

Step 12

This screen has an option for you to 'Generate an automatic installation script', which will allow any similar changes to be undertaken for additional installs. If you do not wish to utilise this option to generate an installation script (if you do not wish to make similar future installs of MESH), click 'Done' to complete the installation and move on to Step 13 in this guide.

If you wish to use this option, then select the button provided.

An xml file will be generated similar to the code below:

You'll be prompted to save the file for later use. Please select where you wish to store the file and click 'Save'. There is also an option to cancel if you no longer want to save the file.

Should you wish to use the automatic installation script in a future automatic install of the MESH Client, the command syntax is:
java -jar mesh-6.3.6_20220906-installer-signed.jar auto-install.xml

Step 13

The installation of the MESH client is now complete. A few further configuration steps must be undertaken before the MESH client is available for use.

The MESH client will have been installed in your chosen folder. Find this folder (if you did not adjust the install destination previously, it will be in 'MESH-APP-HOME'). You should have a series of folders, including 'log', 'proxy' and 'KEYSTORE'. The following configuration steps require access to the files beneath these folders on the list.

Open the meshclient.cfg file in a text editor (such as Notepad or Wordpad). There are three lines to edit in this document. Please edit the bold sections, shown below:

<KeyStorePassword>InsertYourKeyStorePasswordHere</KeyStorePassword>

<ClientIdentity>InsertYourMailboxIDHere</ClientIdentity>

<ClientAuthentication>InsertYourMailboxPasswordHere (it will currently say “ClntAuth1”)</ClientAuthentication>

Your mailbox ID and client authentication will have been confirmed when you applied for your mailbox during the pre-requisite checks. 'Client Authentication' is also known as your mailbox password. You will have made your Keystore password when applying for your endpoint certificate during pre-requisite checks.

The Keystore path refers to the location of your MESH Keystore file (C:\MESH-APP-HOME\KEYSTORE\MESH.keystore for example). You will have made your Keystore password when applying for your endpoint certificate during pre-requisite checks.

If using the MESH client on a non-Windows based server, the above process can be used and the MESH.keystore copied to the server and configured in the same way. 

If you'll be accessing the MESH client via the Internet, rather than using the default N3/HSCN network, the following parameters will need to be changed in the mesh.cfg file:

<PrimaryURL> - this needs to be set to: https://mesh-sync.spineservices.nhs.uk
<Keystore> - will need to be set to the name of your KeyStore

For API installation only, the configuration of your certificate will vary depending upon your current systems.

Further configuration changes are available from the default settings, if you wish. Our Advanced and other settings page details many changes that can be implemented, including:

meshclient.cfg file: the maximum and minimum number of messages that can be sent per poll.

Proxy: setting up your MESH client if you sit behind or use a proxy server.

log4j2.xml file: how detailed the logging levels of your MESH client will be. This refers to a log that MESH client produces of all actions, such as start-up, sending data, receiving data, and any message errors. The logs are helpful to refer to if your files fail to send correctly.

Step 14

Once all the configuration changes have been saved the client can be started by double clicking the runMeshClient.bat. If the client is running you will see the log file generated in the folder defined in the meshclient.cfg file. The default folder location for the log file is \MESH-APP-HOME\log for a new MESH installation.

Below are sections outlining the running of MESH client as a service (running the software automatically in the background) and how to configure your files. These are optional.

If you do not want to run the MESH client as a service, and would rather manually run the MESH client when logging on: To start MESH client, select the .bat file stated above to begin the client after logging on to your computer each time, which will open up a blank command window. To stop the MESH client, simply close the blank command window.

This section describes the installation of a utility to run the MESH Client as a Windows service. This is an optional part of the installation process - it will enable the MESH Client to automatically run when restarting your server and run in the background without the need for you to keep opening and closing the client manually for it to run. Without installing the MESH Client as a service, you'll need to ensure you always leave the blank command box open if you wish to run the software, and manually start the MESH Client after restarting the server.

The utility is a reconfigured version of the Apache Procrun utility. The installation of the MESH Client Windows service should be completed after the MESH Client has been installed and tested.

Please choose one of the three scenarios below and follow the instructions to install the MESH Client as a Windows service.

This is for users who are on MESH Client version 6.2.0 or earlier and wish to stay on that version.

Step 1

Once downloaded, right-click on meshclient_windows_service.zip and choose to 'Extract All'. Click 'Browse' to select the installation path of the MESH Client and the files will be installed into that location.

Step 2

Before installing, check that the meshclient_service_install.bat and meshclient_service_uninstall.bat files reflect the version of Java that the client is running on.

Right-click on meshclient_service_install.bat and click 'Edit'. If you are using a 32 bit version of Java, change to @set ARCH=x86. If it is 64 bit, leave as the default. Then File, Save and Exit.

Repeat for the meshclient_service_uninstall.bat file.

Prior to the actual install, stop the MESH Client (for example, by sending a '1' to the mexclient.sig signal file) as the service cannot be started if it is already running.

Step 3

Double-click on mesh_service_install.bat to commence the service installation. Depending on security settings, you may be prompted with 'are you sure?' type questions. Select the appropriate response if you wish to install. After the 'Press Any Key to continue...' the service is installed (but not started).

Step 4

Press the Windows key on your keyboard, go to 'Run' and open services.msc. Highlight the MESH Client service and click Start. For convenience, a SysTray icon is provided to the bottom right of your screen. To install it, double-click mesh_service_systray.bat.

Step 5

Once installed, you can Right-click on the SysTray to start/stop the service or double-click to access further settings.

Step 6

You may wish to change the current configuration. To do this, right-click on the SysTray icon and click 'Configure'.

The 'General' tab allows the start-up settings to be changed.

The 'Log on' tab allows the log on user to be changed for this service.

The 'Logging' tab allows the logging level and log file location to be changed. The default location will be the MESH log directory and to log at 'info' level. The Apache wrapper creates its own log file as well as adding entries into the MESH mesh.log log file.

The 'Java' tab specifies the Java Virtual Machine to use and defines the Java classpath, which is the location of the Java command to be run as a service with the Java options to be used.

The 'Startup' and 'Shutdown' tabs specify the Java class to be run when the service is started or stopped. The settings on this tab should not need to be changed.

This is for users who are already running MESH Client version 6.2.0 or earlier as a Windows service and wish to update to a later version.  It explains how to uninstall the service so that the MESH Client can be upgraded.

Step 1

Press the Windows key on your keyboard, go to 'Run' and open services.msc. Highlight the MESH Client service and click Stop.

Step 2

In the MESH Client HOME folder (the default if unchanged is C:\MESH-APP-HOME), double-click on mesh_service_uninstall.bat and this will remove the service.

Step 3

Follow the instructions to install MESH Client version 6.3.6 or later and confirm it works by starting it manually by double-clicking runMeshClient.bat and checking the mesh.log file.

Step 4

Stop the MESH client (for example, by sending a '1' to the mexclient.sig signal file) as the service cannot be started if it is already running.

Step 5

Continue to the instructions in Scenario 3 below to install a MESH Client version 6.3.6 (or later) as a Windows service.

Step 1

In the service folder under the MESH Client HOME folder, double-click on InstallMeshService.bat to commence the service installation. Depending on security settings, you may be prompted with 'are you sure?' type questions. Select the appropriate response if you wish to install. After the 'Press Any Key to continue...' the service is installed (but not started). In the same folder, there is a StartServiceMonitor.bat which can be double-clicked on to install a SysTray icon. Right-clicking on Service Monitor SysTray icon will allow you to start the service without having to navigate to the Services app.

Step 2

You may wish to change the current configuration. To do this, right-click on the SysTray icon and click 'Configure'.

The 'General' tab allows the start-up settings to be changed.

The 'Log on' tab allows the log on user to be changed for this service.

The 'Logging' tab allows the logging level and log file location to be changed. The default location will be the MESH log directory and to log at 'info' level. The Apache wrapper creates its own log file as well as adding entries into the MESH mesh.log log file.

The 'Java' tab specifies the Java Virtual Machine to use and defines the Java classpath, which is the location of the Java command to be run as a service with the Java options to be used.

The 'Startup' and 'Shutdown' tabs specify the Java class to be run when the service is started or stopped. The settings on this tab should not need to be changed.

Now you have installed the MESH client, this section will cover the interface of the mailbox(es), and how these can be updated and configured to your needs.

The MESH client will transfer data to and from the host application via a simple file based interface. The MESH client will use the following default file system directory/folder structure to transfer data to and from the host application; 

<MESH-DATA-HOME> 
\FAILED 
\IN 
\OUT 
\SENT 
\TEMP 
\TEMP\RCV 

The <MESH-DATA-HOME> is the path to the MESH client interface top level directory/folder. The MESH client root path will be specified as a configuration item in the MESH client parameter file (meshclient.cfg). The MESH client will read this file when it starts up to configure site/implementation specific parameters.

The FAILED directory will be used by the MESH client to hold malformed or syntactically incorrect control files along with their respective data files.

The IN directory will be used by the MESH client to deposit data and status information to be received by the host application. 

The OUT directory will be used by the HOST application to copy data to be sent by the MESH client. 

The SENT directory will be used by the MESH client to copy sent data for use by the host application. 

The TEMP directory will be used by the MESH client for any intermediate files during its processing of outgoing data transfers. 

The TEMP/RCV directory will be used by the MESH client for any intermediate files during its processing of incoming data transfers. 

Send and receive data

Where data is to be transferred (such as sending or receiving data) the file interface will contain two files;

Data file – <message_id>.dat

The data file will contain the data (payload) to be transferred. This may be in any form and will be treated by the MESH client and server as an arbitrary data file. The maximum size the file can be is 20GB. The only operation that the MESH client may perform on the data file is to compress it if the option within the associated control file is selected.

Control file - <message_id>.ctl

The control file will contain the information required to identify, transmit and audit the data file. The control file content may change, depending upon the transaction, however it must always be formatted as the following:

<DTSControl>
<Version>1.0</Version>
<AddressType>DTS</AddressType>
<MessageType>Data</MessageType>            
<WorkflowId>WorkflowID</WorkflowId>
<To_DTS>Recipient mailbox</To_DTS>
<From_DTS>Your mailbox</From_DTS> 
<Subject>XXXSubjectHeaderXXX</Subject>
 <LocalId>EXAMPLEXXXX-03102019-0001</LocalId> 
<Compress>Y</Compress>
<AllowChunking>Y</AllowChunking>
<Encrypted>N</Encrypted>
</DTSControl>

In bold are the commonly altered aspects of the control file. A full breakdown of the control file data structure is:

Mandatory elements must be supplied.
Optional elements may be ignored or specified with no data.

The MESH client will run independently from the System Supplier application in the processing of the data files. There is a potential for the MESH client or Supplier application to access the data transfer files before they are completed. To mitigate this risk:

1. The data and control files should be created in a temporary directory area and then ‘moved’ to the destination directory.
2. The data file should be placed in the destination directory before the control file.
3. The receiving application should look for the control file before starting to handle the data transfer.

Where only status information is to be transferred, such as delivery status information or error indication, the transaction will be a single control file. This will only be sent from the MESH client to the host application.

Report file - <mailbox_id>_report_type<message_id>.ctl with report type being a C, P or a T to signify Collect, Poll or Transfer respectively.

You can use multiple mailboxes with one installation of the MESH client software. We recommend using a different mailbox for each type of service you will be using it for. For example, you may have one mailbox to send National Data Opt Out data, and another mailbox to send admissions, discharges and withdrawals data.

If you wish to use the MESH client with multiple mailboxes, you'll need to first request a new mailbox using our mailbox request form before completing the following steps to configure your MESH client to support multiple mailboxes.

If you decide to use a new mailbox with an existing client, you need to edit the MESH configuration file, meshclient.cfg, which will be in the directory and folder where the MESH client has been installed.

Add a new client section by including the following code in the configuration file:

<Client>
<ClientIdentity>mailbox ID</ClientIdentity>
<ClientAuthentication>authentication key</ClientAuthentication>
<MailboxType>MESH</MailboxType>
<InterfaceRoot>C:\MESH-DATA-HOME\Mailbox2</InterfaceRoot>
<CollectReport>Y</CollectReport>
<TransferReport>Y</TransferReport>
<PollReport>N</PollReport>
<SaveSent>Y</SaveSent>
</Client>
HTML

Enter the mailbox name and authentication key you were sent when your MESH mailbox was set up. The authentication key is also known as the mailbox password. Make sure the location in the InterfaceRoot field matches the directory location where the new MESH Mailbox is to be accessed, and ensure a corresponding folder and subfolders are created in the directory location. 

If Client has been installed as a service please stop and restart the service to ensure that changes are picked up.

See an example of a multi-mailbox configuration file.

If you have further questions related to MESH please contact the National Service Desk.