Introduction

This document is written for IT staff / system engineers of data providers and therefore assumes technical knowledge. It acts as a guide through the on-boarding process of HD4DP v2 and covers installation of the server, user configuration, network configuration and remote access.

The order of steps in this document should be respected during execution.

If you need more informationor have any questions, feel free to contact us.

Overview

HD4DP v2 consists of a modular application stack, which allows Healthdata to seamlessly upgrade individual elements.

An HD4DP v2 deployment comprises of following components:

• Form.io component
• MongoDB
• PostgreSQL
• Nextgen Connect

As it is the case in HD4DP 1.0, an Encryption Module with a connection to the eHealthBox is still required for HD4DP v2 and must be provided by the data provider.

Network configuration

IP

The HD4DP server needs to be accessible via domain names in DNS, and must have a static IP in your private network.

DNS

The application stack of HD4DP v2 requires four domain names pointing to the IP of the locally installed HD4DP v2 server. Use the following names in your DNS:

• nextgenconnect.hd4dp.<yourdomain.be>
• hd4dp.<yourdomain.be>
• metabase.hd4dp.<yourdomain.be>
• admin.hd4dp.<yourdomain.be>

Firewall

The following connections should be possible in the firewall flow:

• To and from (a) machine(s) in your IT department on port 22 for initial configuration and local support.
• To and from the Encryption Module server. The protocol and ports depend on your local EM implementation. Contact your EM vendor if more information is necessary.
• Reachable by your staff who uses HD4DP, on ports 80 and 443 for HTTP(s) traffic.
• To and from the LDAP server (this is not mandatory if you are not using LDAP to authenticate) (port 389 by default)

The Healthdata proxy server is used as a gateway to the internet for the security of HD4DP servers. The configuration of this proxy server will be provided to you by Healthdata at a later date.

Server installation

To install the application stack of HD4DP v2, Healthdata requires a fresh installed operating system, specifically Ubuntu Server 22.04 LTS.

Please use these instructions even if you have previous experience with installing this operating system, as its configuration is specific for Healthdata.

These instructions assume that the network configuration described in the previous section is completed.

Instructions

HD4DP v2 requires a (virtual) machine running Ubuntu Server 22.04 LTS.

We assume knowledge of loading an .iso file onto a (virtual) machine. Healthdata can’t provide instructions for this, as the environment of your center is unknown. Should you have any trouble, however, please contact Healthdata support so that we can help out.

Please find the installation steps below.

Installation steps

1. Download the .iso file from the link below.
   Download Ubuntu Server 22.04 LTS
2. Create a new (virtual) machine with Linux Ubuntu 64 bit as the OS family
3. When prompted, select the .iso file downloaded in step 1.
4. After some time, you will be prompted to select a system language. Select English.
5. “Keyboard configuration”
   Select your preferred keyboard layout and press enter
6. “Network Connections”
   Highlight the network interface and press enter. Navigate as follows:
   Edit IPv4 -> Manual -> enter the network details -> save -> Done
7. Proxy IP -> Leave default/empty.
8. “Configure Ubuntu Archive Mirror” -> leave default
9. “File system Setup” -> Use An Entire Disk
10. Proceed until “Confirm destructive action” -> press continue. The installation process starts, this can take several minutes.
11. In the meantime, create the user for Healthdata.
    username = healthdata,
    Password = choose a secure password and communicate it to Healthdata.
12. Mark “Install OpenSSH server”. This will be used for remote access. “Import SSH Identity” -> no -> done
13. “Featured Server Snaps” -> Select nothing and press Done.
14. Wait until installation is finished.

Configuration steps

Connecting to the server

Log into the machine with the Healthdata user created in the previous section.

Instructions (from a Windows machine):

1. Install the tool Putty and open the application.
2. On the configuration screen, enter the following (replace cursive text with the appropriate values)
   • Host Name: healthdata@server_private_ip
   • Port: 22
   • Connection type: SSH
3. Click Open. Enter the Healthdata password (you will not see text as you type, you can paste into putty by right-clicking in the terminal).
4. You should now be logged in and see a prompt  “healthdata@server_name:~$”

Administrator account for internal use

An administrator account for internal use can be created on the HD4DP v2 server.

The configuration of remote access (described below) should not happen on this account, but on the Healthdata account.

The internal account can later be used to install and configure OS monitoring software and antivirus software by the internal IT team. For more information, see the section on Antivirus and Monitoring.

(Text with a gray background should be entered as a command in the terminal of the server)

Create the user:

            sudo adduser <username>

Add the user to the sudo group

            sudo usermod -aG sudo <username>

Installation and configuration of the software stack

Healthdata.be support will instruct you when to execute the next step, which is to enable remote access so that Healthdata can execute the software installation and configuration.

Backups

The configuration of the HD4DP v2 server is administered by Healthdata and does not require backups. This configuration will be based on the information shared on the infrastructure sheet. If no network drive information is shared with Healthdata, no backups of the databases will be foreseen.

HD4DP v2 regularly dumps its databases automatically to the /backup directory on the server. A network storage should be mounted at this location.

Please fill out the infrastructure sheet with the required credentials, domain name/url, protocol… to connect to the network drive. The connection will then be configured by Healthdata.

Patching and Updates

Healthdata configures HD4DP v2 servers to automatically receive recommended security updates. The choice for Ubuntu 22.04 is motivated by the long-term support for this version. Security flaws are rare in this distribution, and security updates are quick and often don’t require a system reboot.

If the IT department of your organization prefers to manage patches, this is possible but not encouraged. Please use the account for internal use created in Section Server installation for this purpose.

Antivirus and Monitoring

Most data providers will want to manage their own antivirus and OS monitoring on all machines in their network. Installation of such software on the HD4DP v2 server is allowed, but Healthdata should be informed about all extra software installed on the server. Additionally, Healthdata will not provide support for the installation of this software.

Contact information

https://support.healthdata.be

Email: support.healthdata@sciensano.be

Phone: +32 2 793 01 42 

The HD4DP v2 Infrastructure Sheet contains information that healthdata.be needs in order to start the installation of the HD4DP 2.0 Software at your organization.

Below you can find the description of the necessary information:

SERVER CONNECTION

Healthdata.be performs its installation and support tasks remotely (using VPN or remote port forwarding via SSH). Please provide the required credentials.

• Type of connection (VPN / Remote port forwarding via SSH)
• Link (IF VPN)
• Username, token, other (if VPN)
• Password (if VPN)³
• Public SSH Key (if remote port forwarding)

³ For security reasons, we advise to communicate passwords to us either by phone, or via a link using a secret-sharing service such as onetimesecret.com.

SERVER MACHINE

• Server Name
• Internal IP-Address
• Ram (in GB)
• CPU (number of CPU's and number of cores)
• Disk space (in GB)
• Username: Healthdata
• Password ³

³ For security reasons, we advise to communicate passwords to us either by phone, or via a link using a secret-sharing service such as onetimesecret.com.

ATTACHED DRIVE FOR BACKUPS

HD4DP 2.0 regularly performs data dumps for backup purposes. Please provide connection information to a network share volume.

• Link / IP address
• Path
• Username
• Password ³

³ For security reasons, we advise to communicate passwords to us either by phone, or via a link using a secret-sharing service such as onetimesecret.com.

USER MANAGEMENT

HD4DP can either connect to a LDAP server or use its own application database for performing user authentication and management. Please check the user management mechanism you want to use.

• LDAP user management : Yes / No
• Application user management : Yes / No

LDAP configuration (Optional)

If you chose ‘LDAP user management’ as user management mechanism, please provide the following information that allows us to connect to your LDAP system.

• Connection URL
• Username
• Password³

³ For security reasons, we advise to communicate passwords to us either by phone, or via a link using a secret-sharing service such as onetimesecret.com.

SOFTWARE CONFIGURATION

Encryption Module interface

HD4DP communicates with the Encryption Module (EM) either using the file system interface or by calling a REST web service. Please choose which interface HD4DP should use for its communication with the Encryption Module.

• REST web service
• File system

REST web service interface

If you chose to communicate with the Encryption Module using a REST interface, please provide the web service URLs that should be used by HD4DP for its communication with EM.

• "Outgoing flow URL: Example: http://host:8080/encryptionmodule/send"
• "Incoming flow URL : Example: http://host:8080/encryptionmodule/receive"

File system interface

• "Incoming directory: Directory where HD4DP checks for incoming files"
• "Incoming directory: Directory where HD4DP writes outgoing files"
• "Incoming directory: Directory to which HD4DP moves successfully processed files"
• "Incoming directory: Directory to which HD4DP moves unsuccessfully processed files"

This documentation details the necessary adaptations to be performed in order to allow the necessary technical accesses and smooth operation of the different healthdata.be platforms and interfaces.

The file is available for download below.

Note: the procedure for the Encryption module is the same for HD4DP v1 and v2.

While HD4DP is developed by healthdata.be, the EM module is not. It can be developed by data providers or third party vendors.

The architecture workgroup of the eHealth platform have strict rules concerning the encoding. Encryption and decryption from the HD4DP software are kept separate.

A new component, whose main functionality, is the encryption of the data before it leaves the organization. Since “data encryption” is the main purpose of this module, it will be referred to as Encryption Module (or EM).

Development by Data Providers

A cookbook containing detailed instructions onhow to implement the module are attached.

HD4DP needs to be configured for the encryption module (cf "How to configure HD4DP for an encryption module").

Finally, validation (cf. article "Encryption module validation scenario") the encryption module implementations is done by healthdata.

Development by Third Parties

The two main functionalities of the encryption module are:

•   Encryption and decryption data
•   Sending and receiving data

HD4DP needs to be configured for the encryption module (cf. article "How to configure HD4DP for an encryption module"​).
 

Encryption and decryption

Healthdata.be has validated (cf. Encryption module validation scenario) the encryption module implementations, developed by the following parties:

• ​Amaron (Amaron)
• HealthConnect (Hector/Unified Messaging)
• Hôpital Erasme (custom)  
• NexuzHealth (NexuzHealth)
• Réseau Santé Wallon (XConnect)

Sending and receiving data

In Belgium, different eHealthBox client softwareapplications are available.

An eHealthBox client application provides an interface to use the eHealthBox service. The eHealth-platform communicates medical files, lab results or other sensible information.

​The use of an eHealthBox client application is required for sending data to healthdata.

The main vendors are:

• ​Amaron (Amaron)
• HealthConnect (Hector/Unified Messaging)
• Hôpital Erasme (custom)  
• NexuzHealth (NexuzHealth)
• Réseau Santé Wallon (XConnect)

Note: The example files are only provided as a guideline and do not contain real life data.

Note: Below documentation contains generic example screens with the sole purpose to demonstrate how the process looks like regardless of the register.

3. Uploading the JSON file

• The IT department of the Data Provider implements a data transmission system (e.g. Postman) to send the API queries by means of a json file. The correct endpoints for uploading of the json file can be found here.

• The URL that needs to be entered after POST (selected method for uploading) should have a syntax similar to the one below:

POST {{baseURL}}/api/dcd/payload/submit?organization-id={organizationId}&dcd-id={dcdId}&dcd-version-id={dcdVersionId}&data-src-type={dataSrcType}

• Whereby:
  • {organizationId} needs to be replaced by the id of your organization; go here for more information
  • {dcdId} needs to be replaced by a register-specific numerical value; go here for more information
    
  • <optional> {dcdVersionId} needs to be replaced by the intended version number; if not provided, the latest version of the dcd specifications is assumed; go here for more information
  • <optional> {dataSrcType} needs to be replaced by the data source type. Permitted values are API or CSV; go here for more information
    
  • a GET method URL should not contain /submit/ in the endpoint or path
  • multiple query parameters need to be connected by an ampersand (&) (see example above)

• In the Authorization tab, select “Basic Auth” in the “Auth Type” drop-down list. Subsequently, fill out the API credentials in the username and password fields.

• In Body tab, select the “raw” option from the top line and paste the content of the JSON file in the box.

• Once the request settings are completed, press the Send button to submit the records.
• After succesful submission of the data, the “Status: 202 Accepted” code will appear below the box where the data was pasted. The bottom box should return a message about the records uploaded or an error message if any.

• A 401 Unauthorized message instead indicates missing or incorrect credentials. Request the correct credentials as described above in the Requirements at Data Provider's side.

• A 400 Bad request might refer to incorrect syntax of the API query. Check the query parameters and ensure to connect multiple parameters with the ampersand (&) character.

4. Validating the JSON Upload

4.1 Validation of the S2S API Upload via the response:

Verify in the same way the request was sent, that the returned response is containing a valid Business key.

If a valid Business key has been provided, the registration upload via System 2 System API was succesful.

4.2 Validation of the S2S API via HD4DP 2.0:

Step 1: Open the HD4DP 2.0 application.

Step 2: Select the organization in the dropdown list and click on Volgende (Next).

Step 3: Fill in the username and password, that has been provided by your IT Department or Healthdata team, and click on Log in to access the HD4DP v2.0 application.

Step 4: Navigate in the menu on the left-hand side panel to the desired study program:

Step 5: Check that the uploaded registration(s) is/are displayed in the overview table:

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!

Table of contents

1. API endpoint overview
2. Get organizations
3. Get the DCD menu structure
4. Get DCD field definitions
5. Get DCD payload example
6. Get DCD field definition list
7. Get DCD code list values
8. Get DCD menu translations
9. Get DCD field definition translations
10. Submit DCD registrations
11. Search for SADMI medical devices
12. User password
13. Additional fields

API endpoint overview

The baseURL to be used has the following built: https://<hd4dp_url>/proxy.

Go here for further details on the syntax of API queries to ensure correct uploading of the json file.

API endpoint	Respons	Notes
{{baseURL}}/api/organizations	List of organizations. Client must select the right organizationId	GET method Currently existing endpoint is: /api/installation/organizations We’ll create this new endpoint with a different signature re-routing the call to this existing one or we will refactor the existing one to this new signature.
{{baseURL}}/api/externalreference/sadmi?notificationCode={notificationCode} <optional> name={name} <optional> reference={reference} <optional> distributorName={distributorName} <optional> manufacturerName={manufacturerName} <optional> classificationCode={classificationCode}	List of Medical Device Types: - NotificationCode - Name - Reference URL - Distributor - Manufacturer - Classification - State Client must select the desired information.	GET method
{{baseURL}}/api/dcd/payload/submit?organization-id={organizationId} <optional> dcd-id={dcdId} <optional> dcd-version-id={dcdVersionId} <optional> data-src-type={dataSrcType}	Results info if succeed Error info if failed	POST method Some implementation tasks are needed here in order to return the result info (either succeed or failed).   Similar like the one in HDConnectProxyRestTemplate.postCsv method, and the CsvExecutionResult object build.   <optional parameter> dcd-version-id={dcdVersionId}: If this parameter is not provided, latest one is assumed.    <optional parameter> data-src-type={dataSrcType} :   permitted values:   - API  - CSV  If this parameter is not provided, default values is <HD4DP>.
{{baseURL}}/api/dcd/payload/example?dcd-id={dcdId} <optional> version={version}	Example of payload in JSON format	GET method Providing this API end-point in order to help the Client on the Payload build with an example   <optional parameter> version={version}: If this parameter is not provided, latest one is assumed
{{baseURL}}/api/dcd/payload/definition?dcd-id={dcdId} <optional> version={version} <optional> language-id={languageId}	List of all the fields of the form as well as their corresponding data-types that are allowed in the json data structure for the Payload	GET method This field names values are the key properties in the formIO json config form. When we implement this new api end-point, we need to parse the json content in order to get the key properties. Given these field keys, we’ll get each field definition from new API end-points helpers: /api/dcd/field?field-id={fieldId}  /api/dcd/codelist?codelist-id={codelistId}  These ones are described in the next table.  <optional parameter> version = {version}: If this parameter is not provided, latest one is assumed  <optional parameter> language-id = {languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values:  en: English  nl: Dutch  fr: French  Client must build this json object as the payload data to be sent based on this list of fields, on the last api call
{{baseURL}}/api/dcd/menu/structure?organization-id={organizationId}	List of projects of the given organization, dcds of each project, dcdVersions of each dcd in a JSON format Client can get dcdId and dcdVersionId (optional) which are needed on following API calls.	GET method
{{baseURL}}/api/dcd/field?dcd-id={dcdId} <optional> dcd-version-id={dcdVersionId} <optional> included-codelist-values={inclCodelistValues} <optional> field-name={fieldname} <optional> language-id={languageId}	List of DCD fields definition, even with codelist values if the field is CODE field type.	GET method <optional parameter> dcd-version-id={dcdVersionId}: If this parameter is not provided, latest one is assumed <optional parameter> included-codelist-values={inclCodelistValues}: permitted values: - true - false If this parameter is not provided, default value is <true> <optional parameter> field-name={fieldname}: A field name e.g: TX_AUTHOR_GR <optional parameter> language-id={languageId}: language id for the code_list example results If this parameter is not provided, default language will be English. Current permitted values: - en: English - nl: Dutch - fr: French
{{baseURL}}/api/dcd/field/translation?dcd-id={dcdId} <optional> dcd-version-id={dcdVersionId} <optional> language-id={languageId} <optional> field-name={fieldName}	List of fields translations for a  given dcdId in the specified languageId (English if it is not provided) in a JSON format. Optional fieldId parameter can be provided just for getting this info but only for this fieldId.	GET method <optional parameter> dcd-version-id={dcdVersionId}: If this parameter is not provided, lastest one is assumed <optional parameter>  language-id={languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: - en: English - nl: Dutch - fr: French <optional parameter> field-name={fieldName}: A field name e.g: TX_AUTHOR_GR
{{baseURL}}/api/dcd/codelist?code-list-id={codelistId} <optional> language={language}	List of values for the codelist of the given codelistId.(List<CodeListItem>)	GET method Checking and getting this info based on MDM -> CODE_LIST table and the relationed  tables (CODE, CODE_CONTENT etc.) See MDM – Field description – DB model diagram at the Attachment chapter for more details. <optional parameter> language={languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: - en: English - nl: Dutch - fr: French

return to table of contents

Get organizations

Request example  

GET {{baseURL}}/api/organizations

Request response 

return to table of contents

Get the DCD menu structure 

Request example

GET {{baseURL}}/api/dcd/menu/structure?organization-id={organizationId}

Request parameters

• {organizationId}: Id of the organization as provided by Healthdata.be and for which we want to list the menu structure
• {{baseURL}}: the value for this field is https://<hd4dp_url>/proxy

Request response

All the menu structure for that organization, including projects, dcds of each project and dcd versions of each dcd, in a JSON format.

return to table of contents

Get DCD field definitions 

Request example

GET {{baseURL}}/api/dcd/payload/definition?dcd-id={dcdId}&version={version}&language-id={languageId}

Request parameters 

• {dcdId}: Id of the dcd 
• <optional parameter> {version}: If this parameter is not provided, latest one is assumed
• <optional parameter> {languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: 
  • en: English
  • nl: Dutch
  • fr: French

Request response

return to table of contents

Get DCD payload example

Request example  

GET {{baseURL}}/api/dcd/payload/example?dcd-id={dcdId}&version={version}

Request parameters 

• {dcdId}: Id of the dcd 
• <optional parameter> {version}: If this parameter is not provided, latest one is assumed

Request response 

Given the previous Payload field definition example on previous chapter, we build a payload content example accordingly.

{ 

   "CD_SURGL_APPR_FEMO": 68224, 

   "D_IMPLANT": "2021-04-30T22:00:00", 

   "TX_TPE_INSTRU": "P-432", 

   "MS_PAT_HGHT": 180 

} 

return to table of contents

Get DCD field definition list

Request example  

GET {{baseURL}}/api/dcd/field?dcd-id={dcdId}&dcd-version-id={dcdVersionId}&included-codelist-values={inclCodelistValues}&field-name={fieldName}&language-id={languageId}

Request parameters 

• {dcdId}: Id of the menu dcd which we want to get all the translations. 
• <optional parameter> {dcdVersionId}: If this parameter is not provided, latest one is assumed. 
• <optional parameter> {includedCodelistValues}: boolean value (true or false). If this parameter is not provided, default value will be true. If true and for those fields with type equal to CODE, codelist values will be provided in the result. 

• <optional parameter> {fieldName}: A field name e.g: TX_AUTHOR_GR 
• <optional parameter> {languageId} : language id for the menu options example results. If this parameter is not provided, default language will be English. Current permitted values: 
  • en: English 
  • nl: Dutch 
  • fr: French

Request response 

with parameter includeCodelistValues equal to true (default value) 

{ 

  "TX_TPE_INSTRU": { 

    "field_type": "FREE TEXT", 

    "code_list": null 

  }, 

  "D_IMPLANT": { 

    "field_type": "DATE", 

    "code_list": null 

  }, 

  "MS_PAT_XXXX": { 

    "field_type": "UNKNOWN", 

    "code_list": null 

  }, 

  "MS_PAT_HGHT": { 

    "field_type": "CODE", 

    "code_list": [ 

      { 

            "ID": 68224, 

        "CODE_VALUE": "870646003", 

        "LABEL_EN": "Femoral (Hemi)" 

      }, 

      { 

        "ID": 68225, 

        "CODE_VALUE": "465954006", 

        "LABEL_EN": "Femoral + Cup" 

      } 

    ] 

  } 

} 

with parameter includeCodelistValues equal to false 

{ 

  "TX_TPE_INSTRU": { 

    "field_type": "FREE TEXT", 

    "code_list": null 

  }, 

  "D_IMPLANT": { 

    "field_type": "DATE", 

    "code_list": null 

  }, 

  "MS_PAT_XXXX": { 

    "field_type": "UNKNOWN", 

    "code_list": null 

  }, 

  "MS_PAT_HGHT": { 

    "field_type": "CODE", 

    "code_list": 23 

  } 

} 

return to table of contents

Get DCD code list values 

Request example  

GET {{baseURL}}/api/dcd/codelist?code-list-id={codelistId}&language={languageId} 

Request parameters 

• {code-list-Id} : Id of codelist which we want to get the permitted values 
• <optional parameter> {language} : language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: 
  • en: English 
  • nl: Dutch
  • fr: French

Request response 

{ 

   { 

       "ID": 68224, 

     "CODE_VALUE": "870646003", 

     "LABEL_EN": "Femoral (Hemi)" 

   }, 

   { 

     "ID": 68225, 

     "CODE_VALUE": "465954006", 

     "LABEL_EN": "Femoral + Cup" 

   } 

} 

return to table of contents

Get DCD menu translations

Request example  

GET {{baseURL}}/api/dcd/menu-translations?dcd-id={dcdId}&dcd-version-id={dcdVersionId}&language-id={languageId} 

Request parameters 

• {dcdId} : Id of the menu dcd which we want to get all the translations. 
• <optional parameter> {dcdVersionId} : If this parameter is not provided, lastest one is assumed. 
• <optional parameter> {languageId} : language id for the menu options example results. If this parameter is not provided, default language will be English. Current permitted values: 
  • en: English 
  • nl: Dutch
  • fr: French

Request response 

Example 1: languageId = “en” - English language menu translations 

{ 

  { 

    "zephyr_ortho_program": "QERMID - Orthopedics", 

    "zephyr_ortho_knee_project": "Orthopride knee", 

    "zephyr_ortho_knee_t1_dcd": "Primo-implantation" 

  }, 

  { 

    "zephyr_ortho_program": "QERMID - Orthopedics", 

    "zephyr_ortho_knee_project": "Orthopride knee", 

    "zephyr_ortho_knee_t2_dcd": "Revision" 

  } 

. . . . .  

} 

Example 2: languageId = “nl” - Dutch language menu translations 

{ 

  { 

    "zephyr_ortho_program": "QERMID - Orthopedie", 

    "zephyr_ortho_knee_project": "Orthopride knie", 

    "zephyr_ortho_knee_t1_dcd": "Primo-implantatie" 

  }, 

  { 

    "zephyr_ortho_program": "QERMID - Orthopedie", 

    "zephyr_ortho_knee_project": "Orthopride knie", 

    "zephyr_ortho_knee_t2_dcd": "Revisie" 

  }, 

. . . . .  

} 

Example 3: languageId = “fr” French language menu translations 

{ 

  { 

    "zephyr_ortho_program": "QERMID - Orthopédie", 

    "zephyr_ortho_knee_project": "Orthopride genou", 

    "zephyr_ortho_knee_t1_dcd": "Primo-implantation" 

  }, 

  { 

    "zephyr_ortho_program": "QERMID - Orthopédie", 

    "zephyr_ortho_knee_project": "Orthopride genou", 

    "zephyr_ortho_knee_t2_dcd": "Revision" 

  }, 

} 

return to table of contents

Get DCD field definition translations 

Request example  

GET {{baseURL}}/api/dcd/fields/translation?dcd-id={dcdId}&dcd-version-id={dcdVersionId}&language-id={languageId}&field-id={fieldId}

Request parameters 

• {dcdId} : Id of the menu dcd which we want to get all the translations. 
• <optional parameter> {dcdVersionId} : If this parameter is not provided, lastest one is assumed. 
• <optional parameter> {languageId} : language id for the menu options example results. If this parameter is not provided, default language will be English. Current permitted values: 
  • en: English
  • nl: Dutch
  • fr: French

• <optional parameter> {fieldName} : Id of field which we want to get the translation from 

Request response 

Example 1: languageId = "en" - English language fields translations 

{ 

    "author_group": "Authors group", 

    "CD_SLEEVE_LON": "Long sleeves", 

    "TX_TTL_UNT": "Unit", 

    "TX_CTNT_BEF_CONT_VEN_ARTER": "Before venous/arterial contact", 

    "CD_NAIL_DIRT": "Dirty nails", 

    "CD_PLSH": "Nail polish", 

    "TX_NHH": "No hand hygiene", 

    "CD_SITE": "Site number", 

    "CD_NAIL_EXT": "Nail extensions", 

    "TX_TTL_STDY": "Study design", 

    "CD_WATCH": "Wearing a watch", 

    "D_OBS": "Observation date", 

    "T_STP_OBS": "Time end observation period", 

    "CD_OPT_MDL": "Participation module optional", 

    "CD_SPLTY": "Specialty of the ward", 

    "CD_PROF": "Profession", 

    "TX_TTL_OBS": "Observations", 

    "CD_NAIL_LON": "Long nails", 

    "CD_RING": "Wearing a ring" 

} 

Example 2: languageId = "nl" - Dutch language fields translations 

{ 

    "author_group": "Auteursgroep", 

    "CD_SLEEVE_LON": "Lange mouwen", 

    "TX_TTL_UNT": "Eenheid", 

    "TX_CTNT_BEF_CONT_VEN_ARTER": "Voor contact met intravasculair stelsel", 

    "CD_NAIL_DIRT": "Vuile nagels", 

    "CD_PLSH": "Nagellak", 

    "TX_NHH": "Geen handhygiëne", 

    "CD_SITE": "Campus nummer", 

    "CD_NAIL_EXT": "Kunst-nagels", 

    "TX_TTL_STDY": "Study design", 

    "CD_WATCH": "Het dragen van polshorloge", 

    "D_OBS": "Observatiedatum", 

    "T_STP_OBS": "Tijdstip einde observatieperiode", 

    "CD_OPT_MDL": "Deelname optioneel module", 

    "CD_SPLTY": "Specialiteit van de dienst", 

    "CD_PROF": "Beroepsgroep", 

    "TX_TTL_OBS": "Observaties", 

    "CD_NAIL_LON": "Lange nagels", 

    "CD_RING": "Het dragen van ring" 

} 

Example 3: languageId = "fr" - French language fields translations 

{ 

    "author_group": "Groupe d’auteurs", 

    "CD_SLEEVE_LON": "Longues manches", 

    "TX_TTL_UNT": "Unité", 

    "TX_CTNT_BEF_CONT_VEN_ARTER": "Avant contact veineux/artériel", 

    "CD_NAIL_DIRT": "Ongles sales", 

    "CD_PLSH": "Ongles vernis", 

    "TX_NHH": "Pas d’hygiène des mains", 

    "CD_SITE": "Numéro du site", 

    "CD_NAIL_EXT": "Ongles artificiels", 

    "TX_TTL_STDY": "Study design", 

    "CD_WATCH": "Le port d’une montre", 

    "D_OBS": "Date de l’observation", 

    "T_STP_OBS": "Heure fin de la période d’observation", 

    "CD_OPT_MDL": "Participation module optionel", 

    "CD_SPLTY": "Spécialité du service", 

    "CD_PROF": "Profession", 

    "TX_TTL_OBS": "Observations", 

    "CD_NAIL_LON": "Ongles longs", 

    "CD_RING": "Le port d’une bague" 

} 

return to table of contents

Submit DCD registrations

Request example  

POST {{baseURL}}/api/dcd/payload/submit?organization-id={organizationId}&dcd-id={dcdId}&dcd-version-id={dcdVersionId}&data-src-type={dataSrcType} 

Header: 

   MediaType.APPLICATION_JSON 

Body: 

{ 

   { 

      "CD_SURGL_APPR_FEMO": 68224, 

      "D_IMPLANT": "2021-04-30T22:00:00", 

      "TX_TPE_INSTRU": "P-432", 

      "MS_PAT_HGHT": 180 

   }, 

   { 

      "CD_SURGL_APPR_FEMO": 68225, 

      "D_IMPLANT": "2021-04-14T22:00:00", 

      "TX_TPE_INSTRU": "P-545", 

      "MS_PAT_HGHT": 1209 

   }, 

   { 

      "CD_SURGL_APPR_FEMO": 68224, 

      "D_IMPLANT": "2021-05-01T22:00:00", 

      "TX_TPE_INSTRU": "T-678", 

      "MS_PAT_HGHT": 210 

   } 

} 

Request parameters 

• {organizationtId}: Id of the organization for which we want to submit the DCD registration.

• {dcdId}: Id of the DCD we want to submit.
• <optional parameter> {dcdVersionId}: Id of the DCD Version we want to submit. If this parameter is not provided, latest one is assumed.  
• <optional parameter> {dataSrcType}: The data source type e.g: API or CSV. 

Request payload 

• {Header}: MediaType.APPLICATION_JSON 
• {Body}: JSON object with an array of DCDs data to be submitted, following the specifications and examples provided by the described api end-points: 

• GET /api/dcd/payload/definition 
• GET /api/dcd/payload/example 

Request response 

Client get a response per each DCD line. If the DCD submission was successful, Client will get a TXT_BUSINESS_KEY value. If it was failed, Client will get an error detailed info: Http Status Code, Name and Exception details: 

{ 

   "TX_BUSINESS_KEY": "NISS 12.06.01-052.46 30/04/2021 67864", 

   { 

      "HTTP_STATUS_CODE": 405, 

      "HTTP_STATUS_NAME": "Method Not Allowed", 

      "HTTP_STATUS_EXCEPTION_DETAILS": "Exception details for Method Not Allowed example", 

   }, 

   "TX_BUSINESS_KEY": "NISS 12.06.01-071.48 01/05/2021 67864", 

}

return to table of contents

Search for SADMI medical devices 

Request example  

GET {{baseURL}}/api/externalreference/sadmi?notificationCode={notificationCode}&reference={reference}  

Request parameters 

• <optional parameter> {notificationCode} 
• <optional parameter> {name} 
• <optional parameter> {reference} 
• <optional parameter> {distributorName}
• <optional parameter> {manufacturerName} 
• <optional parameter> {classificationCode} 

Request response 

{ 

   { 

        "NotificationCode": "First Notification Code Example", 

        "Name": "First Name Example", 

        "Reference": "First Reference Example", 

        "URL": "http://first.url.example", 

        "Distributor": { 

        "NotificationNumber": "First Notification Number Example", 

        "Name": "First Distribuitor Name Example" 

      }, 

        "Manufacturer": { 

        "Name": "First Manufacturer Name Example", 

        "CountryCode": { 

            "value": "First Country Code Value Example", 

            "standard": "First Country Code Standard Example" 

        }, 

        "CountryName": { 

            "value": "First Country Name Value Example", 

            "lang": "First Country Name Lang Example" 

        } 

      }, 

        "Classification": { 

            "Code": "First Classification Code Example", 

            "Description": "First Classification Description Example" 

      }, 

        "State": { 

            "Name": "First State Name Example", 

            "ValidFrom": "First State ValidFrom Example", 

            "ValidTo": "First State ValidTo Example" 

      } 

   }, 

   { 

        "NotificationCode": "Second Notification Code Example", 

        "Name": "Second Name Example", 

        "Reference": "Second Reference Example", 

        "URL": http://second.url.example, 

. . . . .  

   }, 

. . . . .  

} 

return to table of contents

User / password

The username and password can be requested at our Servicedesk.

return to table of contents

Additional fields

In addition to this, more in depth information about the codes and the formats used for the Author group, NISS code, status, Postal Code, "Date" - "Date:Time", repeatable fields and multiple choice fields are available here.

return to table of contents

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create a support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!

The Swagger API is available on the local installation of HD4DP2.0. Go to https://<hd4dp2_url>/proxy/api-docs.html.

Some API calls are password protected (S2S api). If you want access to this API, you can request the user/password by creating a ticket in our servicedesk.

Attention: The baseURL to be used has to following built: https://<hd4dp_url>/proxy

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create a support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!

Postman collection HD4DP2.0 can be downloaded here.

Attention: The baseURL to be used has the following built: https://<hd4dp_url>/proxy

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create a support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!

Data submission procedure in Architecture 2 using CSV Upload

1. Preparing the csv file

• Extract the requested data from the electronic patient files and/or other local databases.
• Mapping of the data according to the fields and formats as described in the DCD specifications of this section and the general code lists.
• Go here for additional information on the codes and the formats used for the Author group, NISS code, Status, "Date" - "Date:Time", Repeatable fields and Multiple choice.
• Make sure the name of the csv test file(s) has the correct format (see Examples below):
  HD_DCD_submcsv_HDBPnumber_HDBPabbreviation_versionnumber_versionreleasedate
• An alternative method for migrated projects would be to export the csv file from Architecture 1 and to manually add the additional fields that are required in Architecture 2. (see Additional fields below, if applicable
• Please use UTF-8 encoding when uploading your CSV

Disclaimer: The example files are only provided as a guideline and do not contain real life data.

2. Uploading the csv file

Step 1: Open the sftp tool like WinSCP

Step 2: Get the credentials (Host name, Port number, User name and Password) from the IT department of the Data Provider, to log on to the sftp server located on the Data Provider side. In case the credenials are unavailable we advise you to request your credentials through our service portal at the Jira Service Management (JSM) Portal via the Request something tab and subsequently the Request for Information box.

Step 3: Fill in the credentials into the Login screen and click on Login to be able to access the different upload folders:

Note: a warning might be given, just click on Update

Now the CSV Upload folder structure is displayed on the right-hand side panel. You will notice draftcsv folders and submcsv folders for the diverse HD business projects. Historically, a directly submitted csv file would end up in the submitted folder, whereas a csv file featuring ‘draft’ in the status field would have ended up in the draft folder. At this stage there is no real distinction between both folders, so you can save the csv file in either of them.
Attention: If you wish to create a draft to work on at a later stage, don’t forget to add ‘draft’ in the status column of the csv file.

Below documentation contains generic example screens with the sole purpose to demonstrate how the process looks like. In the subsequent screens the desired register needs to be selected.

Step 4: Select the desired folder and open it by double-clicking on it:

Step 5: Now go to the folder on the left-hand side panel where the csv file to be uploaded is located:

Step 6: Drag the csv file to be uploaded from the left-hand side panel into the folder on the right-hand side panel:

Step 7: Wait until the polling system of the CSV Uploader has picked up the CSV file and has processed it.
Once the csv file has been processed it will disappear from the folder, when the page is manually refreshed!

3. Validating CSV Upload

Once the csv file has been processed, 3 folders will be created (if they haven't been created already) in the DCD folder:

• ARCHIVE (after a csv file has been processed, the original csv file will be saved in this folder)
• RESULT (when the csv file is placed in this folder, it means that the csv file has been processed, a file will be created (or appended, if the file already existed) with the result of the upload of the csv file).
  All the errors that are described in this file are business related, which means that they are technically correct, but in violation with the business rules or contain wrong values for that field.
• ERROR (when the csv file is placed in this folder, it means that a technical error has occurred like the csv file contained erroneous formatting. The csv file won't get processed and an error file will be created with the errors and reason why the csv file couldn't be processed)

3.1 Validation of the csv upload via sftp tool:

Step 1: Double-click on the ERROR folder to open it, click on the refresh button and verify that there is no error file present.

Step 2: Return to the DCD folder. Now double-click on the RESULT folder to open it, click on the refresh button and verify that the result file is present.

Step 3: Double-click on the result file to open it.

Step 4: If there are multiple records in the result file, scroll to the entry of the current csv upload by looking at the upload date (Started at dd/mm/yyyy hh:mm).
Verify the result file that the upload was successful by searching for the word SUCCESS and having a look at the Status. This Status must contain: Success;Success Count:1;Error Count:0

3.2 Validation of the csv upload via HD4DP 2.0:

Step 1: Open the HD4DP 2.0 web application.

Step 2: Select the organization in the dropdown list and click on Volgende (Next)

Step 3: Fill in the username and password, that has been provided by your IT Department or Healthdata team, and click on Log in to access the HD4DP v2.0 application.

Step 4: Navigate in the menu on the left-hand side panel to the desired study program:

Step 5: Check that the uploaded registration(s) is/are displayed in the overview table.

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!

This configuration is by default active in HD4DP v.2. The XML files can be downloaded with an SFTP client of your choice. The XML files you download can be sent with the MyCareNet component available in your organization. You can attach the XML files to the Web Service call to MyCareNet and sign the message with your eHealth P12 certificate. The XML files are ready for use, thus contain the required fields. There is no additional edit required.

SFTP Connection

The server name and the SFTP credentials can be requested via our Service Portal 

• Server: IP of HD4DP v.2 server  
• Port: 22  
• Username: (your SFTP credentials)  
• Password: (your SFTP credentials) 
• Path: /data/localsftp/upload/nippin (Upload is the home directory of the sftp user)

Deze documentatie wordt regelmatig bijgewerkt. We proberen de informatie zo correct, volledig en zo duidelijk mogelijk weer te geven. Als u desondanks iets in de documentatie ziet dat niet correct is, niet overeenkomt met uw ervaring, of verdere verduidelijking vereist, maak dan een support ticket via ons portaal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) of stuur ons een e-mail via support.healthdata@sciensano.be om dit documentatieprobleem te melden. Vergeet niet de URL of het webadres van de pagina met het documentatieprobleem te vermelden. Wij zullen de documentatie dan aanpassen. Bedankt!

Three major actions are required in order to setup MyCareNet in HD4DP v.2:

1. Whitelisting URLs
2. Upload eHealth certificate in HD4DP v.2
3. Provide eHealth password to make the interface work with NIC/CIN.

Whitelist URL

The following URLs must be whitelisted to communicate with MyCareNet and E-health. Without a direct connection from HD4DP v.2 server to these URLs, a registration to MyCareNet will not work.

https://prod.mycarenet.be:9443/*

https://services.ehealth.fgov.be/*

Create certificate with labels

This part requires your organization's eHealth certificate. Create a certificate that has the name ehealth_certificate.p12 using the open source GUI KeyStore Explorer. Download and install the tool from https://keystore-explorer.org/

1. Open KeyStore Explorer, and create a new KeyStore 

2. Select the type of the new KeyStore: PKCS#12

3. In the menu bar go to Tools -> Import Key Pair

4. Select the type of key pair import required:

5. Browse the Ehealth NIHII-HOSPITAL P12 certificate and fill in the Decryption Password

6. mport the PKCS #12 Key Pair and give it the NIHII number as alias, ex 71001129 

7. Click OK and give it a password that needs to be same for all imported certs in the P12 KeyStore

8. The Key Pair is imported successfully

9. Repeat step 3 to 8 to add more NIHII-HOSPITAL P12 certificates to this KeyStore

10. In the menu bar go to File -> Save All

11. Set the KeyStore Password and give it a password that needs to be same for all certs

12. Click OK and save the KeyStore as ehealth_certificate.p12

13. Click save and the P12 for HD4DP is created

Upload certificate

The filename of your P12 certificate must be ehealth_certificate.p12

The server name and the sftp credentials can be requested via our Service Portal. The password of your P12 certificate can be delivered to Healthdata either via a secure password sharing tool of your choice or via Belnet Filesender to hd-architecture-2@sciensano.be. You can request a Belnet Filesender voucher via our Service Portal as well.

Deze documentatie wordt regelmatig bijgewerkt. We proberen de informatie zo correct, volledig en zo duidelijk mogelijk weer te geven. Als u desondanks iets in de documentatie ziet dat niet correct is, niet overeenkomt met uw ervaring, of verdere verduidelijking vereist, maak dan een support ticket via ons portaal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) of stuur ons een e-mail via support.healthdata@sciensano.be om dit documentatieprobleem te melden. Vergeet niet de URL of het webadres van de pagina met het documentatieprobleem te vermelden. Wij zullen de documentatie dan aanpassen. Bedankt!

Scope

To support the Data Provider with the validation of the MyCarenet message, every night a CSV file is generated with the latest MyCareNet message information.

NexuzHealth hospitals are not able to validate this.

Requirements

The data provider needs access to the sftp folder of HD4DP2.0.

Request the credentials if you did not receive this in our support portal.

Server: IP of HD4DP v. 2 server

Username: (your SFTP credentials)

Password: (your SFTP credentials)

Path: /data/localsftp/upload (home directory of the user)

Output

Example output CSV file:

head -n2 output.csv
localdwh_id,localdwh_created_on,localdwh_registration_code,localdwh_register,nippin_message,nippin_interface_type,nippin_status,nippin_created_on,nippin_payload_after_validation,nippin_postresponse_tack_reference,result
16686,2024-06-18T06:38:01.449820+00:00,206.24.000214.88,OP_KNEE_PRIM_IMPLT,208f3aab-c97a-4ea0-aa70-6cba5e23ce72,REST,SENT,2024-06-18T06:38:01.938909+00:00,,11b7aeb0-4e41-496c-a9f0-8e506744b064,urn:nip:tack:result:major:success,valid

Interface type

Status

De inhoud van deze pagina is enkel beschikbaar in het Engels. Selecteer de EN knop in de rechterbovenhoek van het scherm om de pagina te openen.

De inhoud van deze pagina is enkel beschikbaar in het Engels. Selecteer de EN knop in de rechterbovenhoek van het scherm om de pagina te openen.

De inhoud van deze pagina is enkel beschikbaar in het Engels. Selecteer de EN knop in de rechterbovenhoek van het scherm om de pagina te openen.

De inhoud van deze pagina is enkel beschikbaar in het Engels. Selecteer de EN knop in de rechterbovenhoek van het scherm om de pagina te openen.

De inhoud van deze pagina is enkel beschikbaar in het Engels. Selecteer de EN knop in de rechterbovenhoek van het scherm om de pagina te openen.

De inhoud van deze pagina is enkel beschikbaar in het Engels. Selecteer de EN knop in de rechterbovenhoek van het scherm om de pagina te openen.