We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
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:
- MESH client - usually integrated into supplier provided applications installed at end-sites (individual organisations).
- 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.
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.2.0_20180601”. 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 ™
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.2.0_20180601-installer-signed.jar
Press “Enter” on your keyboard, and the installer should open on your screen.
You'll now be presented with a screen stating: “Welcome to the installation of the NHS Digital MESH Client 6. 2. 0_20180601!”. Click “Next”.
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”.
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”.
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”. Ensure that the mailbox type is set to the default of “MESH” before clicking “Next”.
If you wish for your MESH client to automatically update when newer versions are available, click “Yes” on this screen. This means the MESH client will check automatically that the newest version is running and, if a newer version is available, download the new version and install it for you. This will cause MESH client to stop running and may involve a manual restart. The update of client will mean you need to restart locally on your systems; however, communications will be provided before the release of any new version, so users have prior warning and have the option to review their configuration. We recommend that this setting is enabled.
If you wish to manage the update process manually, or wish to use MESH as a service, please select “No”.
Click “Next” to continue.
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”.
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
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.
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:
<entry key="data.path" value="false"/>
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.
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:
<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.
log4j.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.
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.
One limitation of running the MESH client as a service is that it prevents the MESH client auto-update from refreshing the MESH client if a new version is available. Therefore, we recommend that this feature is disabled.
To disable the MESH auto-upgrade, edit the meshclient.cfg and disable this feature. It's turned off by having ‘N’ in the AutoUpgrade setting:
The MESH client will continue to check if a new version of the MESH client is available and will log when a new client is available but not attempt to automatically install it.
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.
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 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.
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).
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.
Once installed, you can Right-click on the SysTray to start/stop the service or double-click to access further settings.
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.
Install as if a fresh install
Undertake a completely fresh install as if no previous installation exists. The existing client and/or the associated service, if used, must be stopped. Install the new client as detailed above.
Once the installation process is complete the configuration and keystore can be copied from the original installation and any additional configuration changes to take advantage of any new functionality can be made. It's not necessary to apply for a new digital certificate. The configuration for the client is contained in the meshclient.cfg file within the \MESH-APP-HOME folder. The keystore is stored in \MESH-APP-HOME\Keystore.
Once the configuration file and keystore have been copied to the new installation the client and/or service should be restarted. The old client files should be removed or archived once the new client deployment has been assured and is fully operational.
Install over existing installation
- Download the installation pack from the website and unzip the contents. The latest version of MESH client can be found in the installation pack.
- Logon to the machine where the client installation resides.
- Stop the MESH client and/or service.
- Go to the \MESH-APP-HOME\ folder and rename the meshclient.jar meshclient.old.
- Copy the new MESH client file from the installation pack to \MESH-APP-HOME\.
- Rename the copied file meshclient.jar.
- Restart the MESH client and/or service.
- Review the log file to see that the new client is running as expected.
If changes are required to be made to the client configuration they can be made at this time. The client and or the service will need to be stopped. The attributes held in the \MESH-APP-HOME\meshclient.cfg file may be changed, and then the service restarted.