Introduction

The Demographic Data Server (aka DDS) is a tool which generates random demographic informations, and make them available to tools for testing purposes.

Gazelle DDS use cases

The Demographic Data Server tries to respond to the following use cases : 

  • Generate realistic data set to fill out a database with data for testing purpose. 
  • Request data on the demand through web services
  • Transfert data through HL7 V2 or HL7 V3 messages (using multibyte character encoding when necessary)
  • Support for different kind of character encoding. 
  • Support for many languages and countries
  • Usage through web interface (for humans) or web services (for machines)

Overview of the Demographic Data Server (DDS) project

When running a test we often need to inject demographic data. The aim of the tool is to generate the necessary data. Generated data are fictive (not real) but looks like real data. Demographic characteristics consist of

  • First name, last name, mother maiden name …
  • date of birth,
  • sex,
  • religion,
  • race,
  • address

The address consists of the street, town, state, zip code and country. Addresses are randomly generated. We use the geonames database and googlemaps geocoding webservices in order to generate random addresses or more specific research. Generated addresses contain zip code information, matching the city name. Demographics are available for a variety of countries, such as Belgium, the Netherlands, Switzerland, France, Italy, the United States of America, China, Japan… We are working on including data for more countries; do not hesitate to contact us if you think you can help for your country (we would need a list of last and first names more or less frenquently used in your country along with their frequencies in the current population). Demographic Data Server is taking into account information about the frequency of first name, last name, race and religion. The Demographic Data Server provides a Web User interface as well as a Web Service interface. 

The GUI offers the possibility to generate patient data, access all generated patient data and share patients data with other systems over HL7v2 or HL7v3 messages.

How to create a new patient

To create a new patient, go to the “Create Patient” menu. In the create patient page, you have the choice between two generation modes:

  1. Patient’s generation
  2. Advanced Patient’s generation 

Basic generation of patients

In the first tab, ”Patient’s generation”, you will be allow to create a patient by selecting only the country. Once the country has been selected, hit the “Generate Demographic Data” button.

The generated patient will have basic information (last name, first name, other firstname, mother maiden name, gender, data of birth, patient identifier assigned by “DDS” authority, National Patient Identifier and one address). In some case, the tool does not own enough data to populate all the fields.

At the bottom of the Patient Information panel, the  button can be used to send patient (within HL7v2 or HL7v3 messages) to your system.

Advanced generation of patients

In the second tab, “Advanced Patient’s generation”, you will be allow to ask the tool to generate a patient by selecting more criteria. Criteria are gathered in the “Generation Options” panel. You also have the possibility to use the preset options; in the first panel, select the characteristics you want for the patients and hit the “Apply Options” button, it will automatically set a number of criteria.

Additionally (or instead), you can set the criteria individually.

Once you are OK with your criteria, hit the “Generate Demographic Data” button at the bottom of the page.

How to consult existing patient data

To see all the patients generated by DDS, go to the ”Consult Existing Patients” menu. This page shows all patient generated by DDS. The “Search criteria” panel allows you to find a set of patients based on some demographic traits. The filters at top of columns can also be used for quick search.  

In the action column : 

  • The  button allows you to see the patient’s details. 
  • The   button allows you to add the selected patient to the list of patients selected for sharing.

Below the table which gathers the patients, the user could find all patients he/she has selected for sharing.

In the header of this panel:

  • The  button can be used to share all the selected patients at once (see next section for further instructions).
  • The  button can be used to empty the list of selected patients.

How to share patient data

The GUI allows the user to send the selected patients (see previous section) through an HL7v2 or HL7v3 message. Once you have selected the patients to send to your system, it is necessary to configure the sending option : 

  1. Select the HL7 message type (and version). Four options are available:
    • ADT^A01^ADT_A01 (HL7v2.3.1)
    • ADT^A04^ADT_A01 (HL7v2.3.1)
    • ADT^A28^ADT_A05 (HL7v2.5)
    • PRPA_IN201301UV02 (HL7v3)
  2. Then, choose the character set encoding to use (only available for the HL7 version 2). The list of character set encoding depends on the country of the patients to send.  

Then, you need to add one or several endpoints by filling out the “Targets selected” tab. An example is given below. Hit the “Add” button to add the current configuration to the list of configurations. Repeat the operation for each system. Be careful, your system must have an open port (no firewall rule blocking the access) and a public IP address. 

In the “List of configurations” table, you will retrieve all the endpoints which have been configured. When all of them are entered and ready to accept messages, hit the “Send Message” button.

A summary of the transactions will appear just below the configuration panel. For each message, you can hit the  ”more”  button to see the full content of the message

Web Service Interface

An API (SOAP web service) is also available and provides features similar to the graphical user interface. It is widely used by Gazelle tools which requires patient demographics for their testing purposes.

Web service definition

The WSDL file describing the web service is available here. A soapUI sample project is available here.

Available methods

This API offers the methods gathered in the table below:

Method Name Description Parameter Name Possible Values
getListCountryCode Returns all available country code. No parameter.  
returnAddress Generates a specific address from country code. countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
returnAddressByCoordinates Looks for and returns the address for the given coordinates. countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
    lat : The lattitude of the place from which we extract the address. For example : 53.5459481506
    lng : the longitude of the place from which we extract the address. For example : 10.204494639
returnAddressByTown Generates a specific address inside the specified Town. townName : The name of the town. For example : Paris, London, Toronto, Roma, …
returnPerson  Returns a Person based on a few criteria countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
    lastNameOption : Specify if you want to generate the last name or not. true or false
    firstNameOption : Specify if you want to generate the first name or not. true or false
    motherMaidenNameOption : Specify if you want to generate the mother maiden name or not. true or false
    religionOption : Specify if you want to generate the religion of the person or not. true or false
    raceOption : Specify if you want to generate the race of the person or not. true or false
    birthDayOption : Specify if you want to generate the birth day of the person or not. true or false
    genderDescription : Specify the gender of the person. Male, Female, male, female, m, M, f, F or Random. For other value, the gender will be generate randomly.
    firstNameLike : Specify it if you want to get a first name approaching the specified first name.(Attention, you have to choose between the firstNameLike and the firstNameIs.) For example : Nico, Dav, …
    lastNameLike : Specify it if you want to get a last name approaching the specified last name. (Attention, you have to choose between the lastNameLike and the lastNameIs.) For example : Jam, lef, …
    firstNameIs : Specify it if you want to get a person with this exact first name. (Attention, you have to choose between the firstNameLike and the firstNameIs.) For example : Nicolas
    lastNameIs : Specify it if you want to get a person with this exact first name. (Attention, you have to choose between the lastNameLike and the lastNameIs.) For example : James
returnSimplePatient Returns a simple patient from a specific country. countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
returnPatient  Returns a Patient based on specified criteria countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
    lastNameOption : Specify if you want to generate the last name or not. true or false
    firstNameOption : Specify if you want to generate the first name or not. true or false
    motherMaidenNameOption : Specify if you want to generate the mother maiden name or not. true or false
    religionOption : Specify if you want to generate the religion of the person or not. true or false
    raceOption : Specify if you want to generate the race of the person or not. true or false
    birthDayOption : Specify if you want to generate the birth day of the person or not. true or false
    genderDescription : Specify the gender of the person. Male, Female, male, female, m, M, f, F or Random. For other value, the gender will be generate randomly.
    firstNameLike : Specify it if you want to get a first name approaching the specified first name.(Attention, you have to choose between the firstNameLike and the firstNameIs.) For example : Nico, Dav, …
    lastNameLike : Specify it if you want to get a last name approaching the specified last name. (Attention, you have to choose between the lastNameLike and the lastNameIs.) For example : Jam, lef, …
    firstNameIs : Specify it if you want to get a person with this exact first name. (Attention, you have to choose between the firstNameLike and the firstNameIs.) For example : Nicolas
    lastNameIs : Specify it if you want to get a person with this exact first name. (Attention, you have to choose between the lastNameLike and the lastNameIs.) For example : James
returnPatientWithAllOptions The most complete method to return a patient. A lot of parameters are available. countryCode : The code of the country used to generate the Patient.   For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
    lastNameOption : Specify if you want to generate the last name or not. true or false
    firstNameOption : Specify if you want to generate the first name or not. true or false
    motherMaidenNameOption : Specify if you want to generate the mother maiden name or not. true or false
    religionOption : Specify if you want to generate the religion of the person or not. true or false
    raceOption : Specify if you want to generate the race of the person or not. true or false
    birthDayOption : Specify if you want to generate the birth day of the person or not. true or false
    addressOption : Specify if you want to generate the address of the patient or not. true or false
    genderDescription : Specify the gender of the person. Male, Female, male, female, m, M, f, F or Random. For other value, the gender will be generate randomly.
    firstNameLike : Specify it if you want to get a first name approaching the specified first name.(Attention, you have to choose between the firstNameLike and the firstNameIs.) For example : Nico, Dav, …
    lastNameLike : Specify it if you want to get a last name approaching the specified last name. (Attention, you have to choose between the lastNameLike and the lastNameIs.) For example : Jam, lef, …
    firstNameIs : Specify it if you want to get a person with this exact first name. (Attention, you have to choose between the firstNameLike and the firstNameIs.) For example : Nicolas
    lastNameIs : Specify it if you want to get a person with this exact first name. (Attention, you have to choose between the lastNameLike and the lastNameIs.) For example : James
    maritalSatusOption : Specify the marital status of the patient. Possible values are : Married or M, Single or S, Divorced or D, Unknown or U, Random or R.
    deadPatientOption : Specify if you want to generate a dead patient or not. If yes, the date of patient death will be randomly find. true or false
    maidenNameOption : Specify if you want to generate a maiden name for the patient or not. Attention, the maiden name can’t be generate if the patient gender is not female. true or false
    aliasNameOption : Specify if you want to generate an alias name for the patient or not. true or false
    displayNameOption : Specify if you want to generate a display name for the patient or not. true or false
    newBornOption : Specify if you want to generate a new born patient or not. If yes, the patient will have a mother and the patient’s age will be between 1 and 2 days. If the new born option is true, the marital status must be set to ‘Unknown’ or ‘U’, because a new born can’t be married or divorced. true or false
returnHl7Message Generates a patient and returns its demographic in a HL7v2 message. countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
    receivingApplication : The Application of your system. (MSH-5) See the IHE Technical Framework for more information about this field.
    receivingFacility : The Facility of your system. (MSH-6) See the IHE Technical Framework for more information about this field.
    characterSet : The character set encoding of the HL7 message. (MSH-18) Possible values : It depends of each country. For example, for France, all available characters set are : UTF-8 and ISO-8859-1. If you ask for a character set which is not supported by DDS, DDS will return a SOAPException with a message to show you all possible characters set.
    hl7Version : The HL7 version of the message. (MSH-12) Possible values : 2.3.1 or 2.5
    messageType : The message type of the HL7 message. (MSH-9) Possible values : ADT^A01^ADT_A01, ADT^A04^ADT_A01 or ADT^A28^ADT_A05. The ADT^A28^ADT_A05 is only available with the HL7 v2.5 version and the ADT^A01^ADT_A01 and ADT^A04^ADT_A01 with the HL7 v2.3.1 version.
sendHl7Message Generates a patient and sends the HL7v3 Message containing its demographics to the specified target. This method returns the acknowlegdment received by the tool. countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country get with the getListCountryCode method.)
    targetHost : The IP Address of your system, which will receive the HL7 message. Example : 137.114.220.XXX
    targetPort : The port on which your system will receive the HL7 message. Example : 1030
    receivingApplication : The Application of your system. (MSH-5) See the IHE Technical Framework for more information about this field.
    receivingFacility : The Facility of your system. (MSH-6) See the IHE Technical Framework for more information about this field.
    characterSet : The character set encoding of the HL7 message. (MSH-18) Possible values : It depends of each country. For example, for France, all available characters set are : UTF-8 and ISO-8859-1. If you ask for a character set which is not supported by DDS, DDS will return a SOAPException with a message to show you all possible characters set.
    hl7Version : The HL7 version of the message. (MSH-12) Possible values : 2.3.1 or 2.5
    messageType : The message type of the HL7 message. (MSH-9) Possible values : ADT^A01^ADT_A01, ADT^A04^ADT_A01 or ADT^A28^ADT_A05. The ADT^A28^ADT_A05 is only available with the HL7 v2.5 version and the ADT^A01^ADT_A01 and ADT^A04^ADT_A01 with the HL7 v2.3.1 version.
returnHl7v3Message Generates a patient and returns its demographics in a HL7v3 message. countryCode1 : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
sendHl7v3Message Generates a patient and sends the HL7v3 Message containing its demographics to the specified endpoint. countryCode : The code of the country used to generate the Patient. For example : JP, FR, DE, US, … (To know all possible values, see the ISO code of each country. Use the getListCountryCode method.)
    systemName : The name of your system. The name of your system.
    url : The URL of your system. The URL of your system.
    receivingApplication : The Application of your system. See the IHE Technical Framework for more information about this field.
    receivingFacility : The Facility of your system. See the IHE Technical Framework for more information about this field.

Web Service Limitations

We do have limited ressources to offer for this service. Thus the access to the webservice is limited to a “reasonnable” number of requests per days and per minutes. We would like to avoid DoS on the gazelle tools because someone is requesting fake patients every second. 

Thus our limitations are :

  • No more than 30 requests per IP address per minute
  • No more than 3000 requests per period of 24 hours per IP address

If you would like to generate larger amount of data, please get in contact with Eric Poiseau and we will try to help you and generate data to meet your needs. 

If you are administrator of your own instance of Demographic Data Server, you can allow a specific IP to bypass the limitation checks with the following SQL command:

UPDATE dds\_user\_request\_historic SET unlimited=true WHERE ip\_address='62.212.122.29';