[Deprecated] DDS - Demographic Data Server
Warning: This documentation is out-dated, newest version of the documentation is available at https://gazelle.ihe.net/gazelle-documentation
Click to here to enter the Demographic Data Server
The demographic Data Server is a tool that generates random demographic informations, and make them available for tools to use for testing purpose.
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)
For more details about the various functionnalities of the DDS Tool, visit the following links.
- Log in to post comments
[Deprecated] DDS - User Manual for user interface
Warning: This documentation is out-dated, newest version of the documentation is available at https://gazelle.ihe.net/gazelle-documentation
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 fictious (not real) but looks like real data. Demographic characteristics consist of
-
a name, last name, mother maiden name ...
-
date of birth,
-
sex,
-
religion,
-
race,
-
address
- etc ...
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 contains zip code information, matching the city name. Currently generated demographic information can be generated for the United-States, France, Germany and Japan. We are working on including data for more countries. Demographic Dataserver is taking into account information about the frequency of firstname, lastname, race and religion. The Demographic Data Server provides a Web User interface as well as a Web Service interface.
The java documentation of this project is available here.
DDS Web User interface
User can access to DDS using the DDS web page. The GUI offers the possibility to generate patient data, see all generated patient data and shre this patient data with other systems in HL7 v2 or v3.
How to create a new patient data ?
To create a new patient, go to the 
menu. In the create patient page, user will have the choice between to tabs : "Patient's generation" and "Advances Patient's generation".
- In the first tab, "Patient's generation", the user will be allow to create patient information by selecting 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 in DDS, National Patient Identifier and one address). It is possible that some of this information are missing. At the bottom of the Patient Information panel, the 
button can be used to send patient (with HL7 v2 or v3 messages) to the user system. Go to the next part below to send a patient with DDS. See below, one example of a generated patient :
- In the second tab, "Advances Patient's generation", the user will be allow to create advanced patient information by using a lot of criteria. Criteria are all in the "Generation Options" panel. Once the user has set option, just hit the
button to generate patient information. DDS offers to the user to Preset the generation option according to the selected patient preset(s). For that, select the preset in the left panel, and hit the 
button. Once you have selected all desire presets (selected preset are in the right panel), hit the 
button to preset the option according to the selected preset(s). Then, hit the button. (You can select more than one preset at the same time). For example, if user choose the "Dead Patient" preset, the "Dead Patient" option will be set to "Yes". This functionnality allows the user to quickly set the generation option. See below the result of a generated patient information.
How to consult existing patient data ?
To see all patient data generated by DDS, go to the 
menu. This page show to the use, in a table, all patient data generated by DDS. User can use the FirstName and the LastName filters to search a specific patient. It is also possible to sort the patient data by Id (Id in DDS), FirstName, LastName, Gender, Race, Religion ... by hiting the 
button.
In the action column :
- The
button allows user to see the patient data in a pop-up. - The
button allows user to add the selected patient in the selected patient list. This list can be used to share patient. User can add to this list many patients as he wants.
Finally, just below the patient data table, the user could find all patients of the selected patient list :
- The
button can be used to share all patient data of the selected patient list. - The
button can be used to reset the selected patient list.
The 
button (over the patient table) can be used to refresh the patients list of the patient data table.
How to share patient data ?
The GUI allows the user to send the selected patients through an HL7 V2 or V3 messages. Once user has selected the patients to send to his system (see the section over), it is necessary to configure the sending option :
- User must select the HL7 message type and version. Four options are available, see the screenshot below.
- Once the message typas has been seleted, the user must 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, the user must fill the Targets Selected fields. This information are relative to the user system which will receive the patient data. It is possible to send the patient data to several system at the same time. See the example below, for HL7 v2. Hit the Add button to add the configuration to the list of configuration. Be careful, your target must have a port open on the internet. Before sending messages to your system, ensure that your firewall options give to DDS the access to your system.
- Finally, hit the
button to send all selected patient data to the configuration(s). A summury of exchanges will appear just below the configuration panel. For each message, you can hit the 
button to see the full sent message content or the full acknowlegdment message content. See the example below.
Web Services Interface
The WSDL file describing the web service is here. You can also download an example of a project soapUI that use these methods from here.
Functionalities
Functionalities of DDS can be used by web services methods. In fact, DDS implement 7 methods on web service :
- returnAddress : generate random address from the country code
- returnAddressByCoordinates : generate a specific address from country code and coordinates
- returnAddressBtTown : generate a specific address from a town
- returnHL7Message : generate HL7 message on format XML from a country code
- returnPatient : generate a patient from a country code. We can restrict generation on same persons by specifying attributes like the gender, or on specifying a nearby name or a part of the name
- returnPatientWithAllOptions : generate a patient from a country code. All options to generate a patient are available here.
- returnPerson : generate a person without address, using the same attributes of generation of a patient
- sendHL7Message : generate and send a HL7 message to a target host and port.
The documentation of classes on this jar is there.
Web Services Limitation
We do not have limited ressources to offer for this service. Thus the access to the webservice is limited to a "reasonnable" number of request per days/minute. We'd like to avoid DoS on the gazelle tools because someone is requesting fake patients every second.
Thus our limitation 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'd like to generate large random data, please get in contact with Eric Poiseau and we will try to help you and generate data to fill your needs.
[Deprecated] DDS - User Manual for Web Services
Web Services Interface
The WSDL file describing the web service is here. You can also download an example of a project soapUI that use these methods from here.
Functionalities
Functionalities of DDS can be used by web services methods. In fact, DDS implement 12 methods on web service. See the table below to have further information :
|
Method Name |
Description |
Parameter Name |
Possible Values |
|
getListCountryCode |
Return all available country code. |
No parameter. | |
|
returnAddress |
Generate 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 |
Generate a specific address from country code and 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 |
Generate a specific address from a Town. |
townName : The name of the town. |
For example : Paris, London, Toronto, Roma, ... |
|
returnPerson |
Return a Person from some parameters. |
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 |
Return a simpl 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 |
Return a Patient from some parameters. |
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 |
Return HL7 v2 Message containing description of a 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.) |
||
|
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 |
Send HL7 v2 Message containing description of a patient from a specific country to a target host and port. This method return the message response.
|
||
|
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 |
Return HL7 v3 Message containing description of a patient from a specific country. |
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 |
Send HL7 v3 Message containing description of a patient from a specific country to URL. |
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. |
Static WS Client for DDS
We have implemented a Static WSClient for DDS. This related jar is easy to use. You have only to add the jar file to the project, and use it. The jar file is downloadable here (on the Gazelle Maven repository).
Web Services Limitation
We do not have limited ressources to offer for this service. Thus the access to the webservice is limited to a "reasonnable" number of request per days/minute. We'd like to avoid DoS on the gazelle tools because someone is requesting fake patients every second.
Thus our limitation 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'd like to generate large random data, please get in contact with Eric Poiseau and we will try to help you and generate data to fill your needs.
You can allow specific IPs to do not have limited ressources.
To do this you need to update database with this kind of request :
UPDATE dds_user_request_historic SET unlimited=true WHERE ip_address='62.212.122.29';