MESH Client Reference Guide

Size: px

Start display at page:

Download "MESH Client Reference Guide"

Julius Todd
5 years ago
Views:

1 Document filename: MESH Client Reference Guide - v2.6.docx filename Project / Programme Operations and Assurance Services Project <insert> Document Reference <insert> Project Manager Andrew Meyer Status Issued Owner Ash Raines Version 2.6 Author Stuart Baskerville/ Paddy Yung Version issue date 07/08/2017 MESH Client Reference Guide Copyright 2016 Health and Social Care Information Centre Page 1 of 19

2 Document management Revision History Version Date Summary of Changes /08/2015 Initial version /09/2015 Updated following internal review /11/2015 Updated to reflect revised transition approach /11/2015 Updated following review /12/2015 Updated following review /12/2015 Updated following review /12/2015 Updated following review /02/2016 Updated following the MESH transition /03/2016 Updated following review from system engineer /03/2016 Updated following review from system engineer /03/2016 Changed wording on support for older versions /04/2016 Updated MESH/DTS differences, including the Auto Update facility and added Proxy connectivity instructions /04/2016 Updated following review /04/2016 Issued /05/2016 Added extra items to DTS/MESH differences /05/2016 Issued /07/2016 Updated to reflect new focus /07/2016 Updated to new template, document ProcessingDelay setting and review comments /09/2016 Updated following review /09/2016 Updated following review /09/2016 Issued /05/2017 Renamed to the MESH client reference guide /08/2017 Removed all DTS references Reviewers This document must be reviewed by the following people: Reviewer name Title / Responsibility Date Version Simon Richards MESH Service Owner Marta Raper Camilla Cross Spine2 Project Manager Senior Communications Officer Approved by Copyright 2016 Health and Social Care Information Centre. Page 2 of 19

3 This document must be approved by the following people: Name Signature Title Date Version Ash Raines Glossary of Terms Term / Abbreviation API cron EPR GZIP HSCIC JVM Keystore LZW MESH MOLES RA RATS RBAC RESTful UUID What it stands for Application Programming Interface Job scheduler associated with Unix/Linux operating systems EndPoint Registration Compressed file format (GNU zip) Health and Social Care Information Centre Java Virtual Machine Repository for security certificates Compressed file format (Lempel-Ziv-Welch) Messaging Exchange for Social Care and Heath MESH Online Enquiry Service Registration Authority Registration and Tracking Service Role-Based Access Control Uses the REpresentational State Transfer software architectural style Unique User Identifier Document Control: The controlled copy of this document is maintained in the NHS Digital corporate network. Any copies of this document held outside of that area, in whatever format (e.g. paper, attachment), are considered to have passed out of control and should be checked for currency and validity. Copyright 2016 Health and Social Care Information Centre. Page 3 of 19

4 Contents 1 Introduction Purpose of Document 5 2 MESH System Overview 6 3 MESH Client Overview Java and Operating System Requirements Installation Requirements Client Installation Client security and certificates Running the MESH client as a service MESH client auto update MESH configuration file settings (meshclient.cfg) Signal file (mexclient.sig) Log Level Settings (log4j.xml) Proxy Connectivity (proxy.ini) 14 5 MOLES and message tracking Overview Smartcard access 15 6 Contact NHS Digital 16 7 Appendix 1 MESH Client supported platforms 17 Copyright 2016 Health and Social Care Information Centre. Page 4 of 19

5 1 Introduction 1.1 Purpose of Document The Messaging Exchange for Social Care and Health (MESH) Client Reference Guide is intended for users of MESH who need to configure the system for their own needs. Included in this document is a description of the key settings of the MESH client with suggestions on what they should be set to. Copyright 2016 Health and Social Care Information Centre. Page 5 of 19

6 2 MESH System 2.1 Overview MESH is a centralised service, which supports the secure transfer of data between NHS organisations and affiliated organisations. The service supports both clinical and business data flows. It is made up of two elements, the MESH client software, which is predominately integrated into supplier provided applications installed at ends-sites, and the central MESH server, which is located within the Spine Core Messaging Service. The MESH client allows secure transfer of data between the end site application and the central MESH server. The MESH client transfers data, over an encrypted link to the central MESH server. The central MESH server then stores this data until the intended recipient site connects to the service and with its MESH client downloads the data addressed to it over an encrypted link. MESH has been developed using the Spine Services Core infrastructure. This will allow the service to benefit from the large scale reliability of the Spine Services including its disaster recovery capabilities and established service support. Copyright 2016 Health and Social Care Information Centre. Page 6 of 19

7 3 MESH Client 3.1 Overview The MESH client is a Java based client that allows systems to send and receive messages. 3.2 Java and Operating System Requirements The MESH client is written in Java and requires a Java Virtual Machine 1.7 or later to be installed on the server running the client. This is a common pre-requisite for a number of applications and it is likely you will already have a JVM running on your server. The recommendation is that the latest version of the JVM is installed (currently version 8.x), it can be downloaded from Note: The requirement to use a JVM version 1.7 or later is a change from the previous version of this technical specification following issues found with JVM version 1.6. The MESH client can run on any operating system that supports a JVM of version 1.7 or later. See Appendix 1 for a full list of the supported platform configurations as there are some instances where the client can operate on earlier versions. 3.3 Installation Requirements The MESH client is contained in a Java Archive.jar file and requires approximately 10Mb of disk space. The system requirements of the MESH client are governed by the size of the files being transferred rather than the requirements of the application. We recommend that sites have a minimum of 100Mb of RAM for each mailbox the MESH client is supporting. For example, 100Mb of RAM is required to run the MESH client to support a single mailbox. If the MESH client is configured to process multiple mailboxes the memory requirement increases so the server needs to have sufficient memory to accommodate potential simultaneous upload or downloads in a multi-mailbox operation. For servers running an operating system that does not support a JVM of 1.7 or later or have limited memory, NHS Digital has developed a script-based client that is started using a schedule task or a UNIX cron job to send and receive messages. 3.4 Client Installation The MESH client can be installed in two ways: Wizard-based installation. Manual installation Wizard-based Installation The MESH client will be packaged into a wizard-based installation process. If performing a fresh MESH client installation, the installation wizard will create the folders required to send Copyright 2016 Health and Social Care Information Centre. Page 7 of 19

8 and receive messages. A skeleton meshclient.cfg file will be installed which will need to be set up with site specific configuration such as mailbox name and Authentication Keys. User documentation will be provided to assist in the configuration settings. 3.5 Client security and certificates Each site that uses MESH will require its own or number of client certificates to authenticate to the MESH server. The certificate needs to be installed in the Keystore created as part of the MESH client installation. The certificate and password are then configured as part of the meshclient.cfg file. MESH users will be able to reuse their existing EndPoint Registration (EPR) certificates or may request new MESH client certificates. A utility will be provided on the NHS Digital website to simplify the certificate request process. A more detailed certificate overview is currently available on the NHS Digital website. To simplify testing, a default certificate has been created for systems to test the MESH client in the NHS Digital Integration test environment. This is available for download, with the current version of the MESH test client, from the MESH website. This certificate will not work in the Live system. 3.6 Running the MESH client as a service It is possible to run the MESH client as a service on Windows. Users who wish to run the client in this way should use the Microsoft srvany.exe utility and run the MESH batch file included in the client installation. Where the Microsoft srvany.exe is not supported or can't be used, users may need to consider alternative methods of running the client as a service. This may include the use of Third Party Service Manager tools such as Apache Commons procrun Daemon for Windows. This would require additional components to be installed at end sites and so consideration should be taken locally on the impact of adopting such an approach. 3.7 MESH client auto update A new feature of the MESH client is the Auto Update functionality. This feature ensures that the MESH client being used is up-to-date by periodically checking with the MESH server whether there is a new version to install. The MESH client will check every two days that the version running is the latest. If a newer version is available, it will automatically download the new version and install it. It is recommended that this setting is enabled, however if suppliers wish to manage the update process manually, this can be disabled. If disabled, the MESH client will write to its logs that a new version is available to download and install. 3.8 MESH configuration file settings (meshclient.cfg) The majority of the configuration file settings will be created by the install wizard. Settings such as mailbox names and passwords may need to be entered manually and the meshclient.cfg file saved. Copyright 2016 Health and Social Care Information Centre. Page 8 of 19

9 Note that the <Client> tags need to be present in the configuration file prior to running the MESH installation in order for the installation to migrate the settings to the MESH configuration file. Below is a description of the settings which can be tweaked to fine-tune the behaviour of the MESH client. Within the <MESHConfig> tag PrimaryURL LogPath KeyStorePath KeyStorePassword WorkPath ProxyPath SignalPath PollPeriod ServerRetry MaxMessages The location of where the MESH client will connect. e.g. <PrimaryURL> The location where the mesh.log files will be created e.g. <LogPath>C:\MESH-APP-HOME\log</LogPath> This location is for the MESH keystore file e.g. C:\MESH-APP-HOME\KEYSTORE\mesh.keystore This is the Keystore password supplied with the user account details. If the password used contains a sign, the meshclient.cfg file will need to be saved using UTF-8 encoding to enable the password to be used. The suggestion is that the password is limited to alphanumeric characters. This location is used by the client to install internal files, such as lock files, to enable it to function properly. e.g. <WorkPath>C:\MESH-APP-HOME\working</WorkPath> The path to the proxy.ini file. The existence of this path tells the client that proxy connectivity is required and the proxy.ini file will be read to determine the location and parameters associated with the proxy server. e.g. <ProxyPath> C:\MESH-APP-HOME\proxy</ProxyPath> The path to the signal file, mexclient.sig. e.g. < SignalPath>C:\MESH-APP-HOME\sig</ SignalPath> PollPeriod is defined in minutes and is the period of time the client waits between sending and receiving messages to and from the MESH Service. The default poll period is 10 minutes e.g. <PollPeriod>30</PollPeriod> The number of retries allowed for a message if the MESH server is unavailable (but not busy). If not specified, the default is 3. e.g. <ServerRetry>3</ServerRetry> The number of messages that can be uploaded/downloaded per poll. The minimum value is 20 and the maximum value is 10,000 with a default of 100. Copyright 2016 Health and Social Care Information Centre. Page 9 of 19

10 This will allow for controlled amounts of data to be transferred between client and server. The client will hold the connection and toggle between the upload and download tasks based on the value set until all messages have either been sent or collected. For example upload 100, download 100, upload 100, download 100 etc, until all activity is complete at which point the MESH client will close the connection to the central server and will not attempt to poll again until the time defined by PollPeriod has elapsed. e.g <MaxMessages>100</MaxMessages> MaxMessagesUp An individual MaxMessagesUp tag has been introduced to give the administrator more control over message flow to the MESH server. The value ranges from a minimum of 20 to a maximum of 10,000. If a value is specified outside of the range the default value of 100 will be used. Utilising the MaxMessagesUp tag will override both the default value of 100 and any MaxMessages value specified in the client configuration file. If there are still messages to be uploaded after the MaxMessages cycle has completed then the client will poll again until all messages have been sent. e.g. <MaxMessagesUp>100</MaxMessagesUp> MaxMessagesDown MaxConnections AutoUpgrade ProcessingDelay Similar to MaxMessagesUp but for message downloads, overriding both the default value of 100 and any MaxMessages value specified in the client configuration file. e.g. <MaxMessagesDown>200</MaxMessagesDown> This is the number of parallel processes that the MESH client can run. The default is 8 but if the number of CPU cores on the client hardware is lower than this, it will be equal to that number (if the value has been set higher). e.g. <MaxConnections>4</MaxConnections> This setting defaults to N. If it is set to Y, the MESH client will check for updates to the client software every two days and will automatically download and install them. e.g. <AutoUpgrade>N</AutoUpgrade> This setting defaults to 5 seconds. It specifies how long a file needs to reside in the Out folder before the MESH client will attempt to process it. The time used is when the CTL file has been successfully written to disk. This avoids the potential issue where a CTL file is copied into the Out folder before the DAT file and the MESH client moves the CTL into the Failed folder as a malformed message. e.g. <ProcessingDelay>5</ProcessingDelay> Within the <Client> sections Copyright 2016 Health and Social Care Information Centre. Page 10 of 19

11 ClientIdentity ClientAuthentication InterfaceRoot CollectReport TransferReport PollReport SaveSent Site specific identity for the MESH client. Equivalent to the username. e.g. <ClientIdentity>MAILBOX1</ClientIdentity> Site specific authentication token for the MESH client. <ClientAuthentication>ClntAuth1</ClientAuthentication> The path to the root of the MESH client File Interface. e.g<interfaceroot>c:\mesh\mesh-data- HOME\MAILBOX1</InterfaceRoot> Parameter controlling the generation of reports by the MESH client, indicating that it has taken responsibility for an outbound message. Defaults to N e.g. <CollectReport>N</CollectReport> Parameter controlling the generation of reports indicating that the transfer of the messages to the MESH server has succeeded. Defaults to N. e.g. <TransferReport>N</TransferReport> Parameter controlling the generation of reports indicating if the poll to the MESH server to check for received transfers has succeeded or failed. Defaults to N. e.g. <PollReport>N</PollReport> Parameter controlling the copying of sent messages into the SENT folder on successful transfer to the MESH service. Defaults to N. <SaveSent>N</SaveSent> Copyright 2016 Health and Social Care Information Centre. Page 11 of 19

12 3.9 Signal file (mexclient.sig) If the signal is valid, the MESH client response will be to perform the requested action, log the event and update the signal file with NO ACTION. Valid signals for MESH client are: Signal Name Value Meaning NO ACTION 0 No action required or previous action complete. EXIT 1 Close client down at the next available opportunity. RESUME 2 Re-enable the poll timer and commence processing messages. PAUSE 3 Disable the poll timer until resume. POLL NOW 4 Start polling mailbox(es) now rather than after expiry of the poll timer. If there is a pending priority mailbox, do this one first. Resume if paused. LOAD CONFIG 5 Re-read the configuration file after processing the current mailbox. DISABLE MBX n 6 Disable the given mailbox. The signal must have an accompanying ClientIdentification string included otherwise this will have no effect. ENABLE MBX n 7 Enable the given mailbox if disabled. The signal must have an accompanying ClientIdentification string otherwise this will have no effect. POLL MBX n 8 Poll the next specified mailbox (In multi-mailbox mode). This forced the client to poll a mailbox of choice. The signal must have an accompanying ClientIdentification string otherwise this will have no effect. CHECK UPGRADE 9 Check if an upgrade to the MESH client is available and if so, download. The client will only install it if AutoUpgrade is set to Y. Copyright 2016 Health and Social Care Information Centre. Page 12 of 19

3.10 Log Level Settings (log4j.xml) Upon start up, the MESH client will read the settings contained within this file to produce the required level of logging.

13 3.10 Log Level Settings (log4j.xml) Upon start up, the MESH client will read the settings contained within this file to produce the required level of logging. The default value (under logger name, level value) is info but other values exist. These are (in order from least to most verbose) error, warn, info, debug, trace Copyright 2016 Health and Social Care Information Centre. Page 13 of 19

14 3.11 Proxy Connectivity (proxy.ini) The MESH client supports the ability to connect to the service via a proxy server using Basic Authentication or No Authentication levels only. It can be made to connect through the proxy server by creating the file proxy.ini (all lower case) and placing it in the folder location specified by the </ProxyPath> tag in meshclient.cfg. If </ProxyPath> is not present in the configuration file, or the proxy.ini file does not exist, or useproxy=0, the MESH client will assume that no proxy connection is required and will attempt to connect directly to the MESH service found at the </PrimaryURL> location. If proxy.ini exists in the location specified, the MESH client will check the path and file for read access and if successful, connectivity through the proxy server will be attempted using the settings contained within the file. Proxy File Format Parameter Description useproxy A flag to enable or disable proxy use (1 = ENABLE, 0 = DISABLE). ipaddress port user password The TCP/IP address of the proxy server through which a connection to the MESH service is required. The port on the proxy server used for the connection. Username used in basic authentication by the proxy server. Ignored if no authentication is used on the proxy server. Password used in basic authentication by the server. Ignored if no authentication is used on the proxy server. An example file is given below. Each parameter must reside on a separate line and be separated from its value by a single = sign. No spaces should be used. The order of the lines in the file is unimportant as is the case of the parameters. useproxy=1 ipaddress= port=8080 user=prxusr password=p455wrd Copyright 2016 Health and Social Care Information Centre. Page 14 of 19

15 4 5 MOLES and message tracking 5.1 Overview The MESH Online Enquiry Service (MOLES) enables the administration of MESH mailboxes, user administration and message tracking/reporting. 5.2 Smartcard access Access to the MOLES service is via the Spine portal or using: It uses a Role Based Access Controls (RBAC) to determine access to the MOLES menus. A Spine smartcard is needed to access to MOLES. No additional roles or business codes will need to be added to their profile in order to log onto MOLES. However, the Unique User Identifier (UUID) of the user s smartcard will need to be entered into MOLES alongside their user account to enable the user to log-on. If MOLES users do not have a Smartcard they will need to apply for a Smartcard through their local Registration Authority (RA). Please advise the local RA that the access is given to the System Support Access Role code R8015. Users will also need to order a Smartcard reader through their local RA. The reader and the card will be issued with no charge. Copyright 2016 Health and Social Care Information Centre. Page 15 of 19

16 6 Contact NHS Digital For further information visit the NHS Digital website at: If users have specific question related to MESH please contact the National Service Desk. Copyright 2016 Health and Social Care Information Centre. Page 16 of 19

17 7 Appendix 1 MESH Client supported platforms Operating System/Java Version Non-Java Java 6 1 Java 7 2 Java 8 3 Microsoft Client Windows 2000 (SP3/SP4) Not supported MESH Client 6.x Not supported Not supported Windows Vista (SP1,SP2) x86/x64 Not supported MESH Client 6.x MESH Client 6.x MESH Client 6.x Windows 7 (SP1) x86/x64 Not supported MESH Client 6.x MESH Client 6.x MESH Client 6.x Windows 8.x x86/x64 Not supported MESH Client 6.x MESH Client 6.x MESH Client 6.x Windows 10 x86/x64 Not supported Not supported MESH Client 6.x MESH Client 6.x Microsoft Server Windows Server 2003 SP1/SP2 Not supported MESH Client 6.x Not supported Not supported Windows Server 2008 (SP1, SP2) x64 Not supported MESH Client 6.x MESH Client 6.x MESH Client 6.x Windows 2012 x64 Not supported MESH Client 6.x MESH Client 6.x MESH Client 6.x UNIX Sco Unix MESH Perl Client Not supported Not supported Not supported HP-UX 11i v1 (11.11) - HP PA-RISC 4 MESH Perl Client MESH Client 6.x Not supported Not supported HP-UX 11i v2 (11.23) - HP PA-RISC 4 MESH Perl Client MESH Client 6.x Not supported Not supported HP-UX 11i v3 (11.31) - HP PA-RISC 4 MESH Perl Client MESH Client 6.x Not supported Not supported HP-UX 11i v2 (11.23) - HP Itanium 4 MESH Perl Client MESH Client 6.x MESH Client 6.x Not supported HP-UX 11i v3 (11.31) - HP Itanium 4 MESH Perl Client MESH Client 6.x MESH Client 6.x MESH Client 6.x Linux MESH Perl Client MESH Client 6.x MESH Client 6.x MESH Client 6.x IBM AIX MESH Perl Client MESH Client 6.x Not supported Not supported Copyright 2016 Health and Social Care Information Centre. Page 17 of 19

18 Operating System/Java Version Non-Java Java 6 1 Java 7 2 Java 8 3 IBM AIX 6/AIX 7.0/AIX 7.1/AIX 8 5 MESH Perl Client Not supported MESH Client 6.x MESH Client 6.x Solaris 8/9/10 32 and 64 bit MESH Perl Client MESH Client 6.x MESH Client 6.x MESH Client 6.x 1 Oracle Java Certified System Configurations for Java 6: 2 Oracle Java Certified System Configurations for Java 7: 3 Oracle Java Certified System Configurations for Java 8: 4 HP-UX Java support information IBM AIX Java support information - Copyright 2016 Health and Social Care Information Centre. Page 18 of 19

Copyright 2009 Aladdin Knowledge Systems Ltd. All rights reserved. All trade and service marks, logos and trade names(collectively, the "Marks")

Copyright 2009 Aladdin Knowledge Systems Ltd. All rights reserved. All trade and service marks, logos and trade names(collectively, the "Marks") mentioned herein, whether registered or no, are proprietary