⚠Due to planned maintenance you will experience short (<30 min) downtime between 08:00 - 08:30 CET.
horizontaltabs-nav-group | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||
horizontal-nav-item
| POOL |
WMDA. The list from ICCBBA can be found in the part of "GRID ISSUING ORGANIZATIONS" in the web page: https://www.isbt128.org/p-databases-ref-tables | |||||
POOL | Yes | Physical location of the donors/CBUs of the inventory provided as ION | ionType: number between 1000 and 9999 | 4 | Physical location of the donors/CBUs of the inventory provided as ION. |
CONTENT_TYPE | Yes | Type of the inventory items, i.e. donor ("D") or CBU ("C") | contentTypeType | 1 | The content-type is also shown in the fileName. When CONTENT_TYPE is "D", the INVENTORY must contain <DONOR>-blocks. When CONTENT_TYPE is "C", the INVENTORY must contain <CBU>-blocks. |
UPDATE_MODE | Yes | Update mode of the inventory, i.e. FULL or DIFF | updateModeType | 4 |
Both UPDATE_MODE of "FULL |
" and "DIFF" are supported. For "FULL", the complete inventory should |
be sent without deleted inventory, for "DIFF", only the new, edited, deleted inventory need be sent. | |||||
SNAPSHOT_TIME | No | Timestamp of the 'data snapshot' (in UTC) | dateTime | minimal 20 | Without fractional seconds the length is 20, for example: 2016-08-23T13:16:48Z Additional notes: SNAPSHOT_TIME in the element <INVENTORY> is defined as "timestamp of the data snapshot in UTC" that means the timestamp of the creation of this part of the complete file. This can be the timestamp of the XML export and I guess that in most of the cases it will be identical to the CREATION_TIME. |
SCHEMA_VERSION | Yes | Version of the applied XML Schema Definition (XSD) | schemaVersionType |
3 | The schema version is very important as this determines the validation rules that should be applied during the processing of your file. |
2.2 ItemBaseType
fieldselements (for Donors and CBUs)
Expand | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
|
|
|
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
|
|
|
|
|
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
ATTR | No | Describing attribute of the donor/CBU according to house rules of the sending organization. | String | 3 | |
BIRTH_DATE | Yes | Date of birth of the donor/CBU | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
SEX | No | Biological gender of the donor/CBU | sexType | 1 | sexType: "F","M" F = Female M = Male NOTE: Mandatory for donors, optional for CBUs |
ABO | No | Blood group (ABO) of the donor/CBU | aboType | 2 | aboType: "A","B","O","AB" |
RHESUS | No | Rhesus (Rh) factor of the donor/CBU | rhesusType | 1 | rhesusType: "P","N"
P = Positive NOTE: "+" and "-" are not supported |
ETHN | No | Ethnic group of the donor/CBU | ethnType | 4 | ethnType: "AFNA","AFSS", "ASSW", "ASSO", "ASCE", "ASSE", "ASNE", "ASOC", "CAEU", |
NOTE: Mandatory for donors, optional for CBUs
ABONoBlood group (ABO) of the donor/CBUaboType2aboType: "A","B","O","AB"RHESUSNoRhesus (Rh) factor of the donor/CBUrhesusType1rhesusType: "P","N"
NOTE: "+" and "-" are not supported
ETHNNoEthnic group of the donor/CBUethnType4ethnType: "AFNA","AFSS", "ASSW", "ASSO", "ASCE", "ASSE", "ASNE", "ASOC", "CAEU","CAER", "CANA", "CAAU", "
HICA", "HISA", "AF", "AS", "CA", "HI", "MX", "OT","UK" |
The value comprises the EMDIS patient identification, where the patient search centre is an EMDIS member, otherwise the value is empty. For example: AU9654021, DE275342, US2277450.
NOTE: This field is not required for status "RS" and can be transmitted as empty if privacy concerns exist.
STATUSYesStatus of the donor/CBUstatusType2statusType: "AV","TU","RS" ("DE" is not supported yet, "RE" not valid for CBUs)STAT_END_DATENoDate until which the current status will be applicablebareDateType10Date without timezone information, example 1968-06-28, Date Delimiter = "-"
SP Horizontal nav item | ||
---|---|---|
| ||
XML example filesBelow you can find two XML example files: one for donors and 1 for CBUs. Both files contain only 2 records, but in those two records almost all possible elements contain a value. It can help you to check the order of the elements in your own XML file. Please be aware that values like GRID are fictive and do not follow the rules for the check character.
|
SP Horizontal nav item | ||
---|---|---|
| ||
|
SP Horizontal nav item | ||
---|---|---|
| ||
|
2.3 hlaType elementsHlaType fields can be divided in hlaSerFieldsType and hlaDnaFieldsType hlaSerFieldsType: HLA values obtained by serological typing methods hlaSerFieldsType = “<FIELD1>” string of max length 5 “</FIELD1>”, “<FIELD2>” string of max length 5 “</FIELD2>”; Example: <SER><FIELD1>1</FIELD1><FIELD2>5</FIELD2></SER> Serological typing results can be given for loci that are defined as hlaLocusSerDnaType. These loci include HLA-A, -B, -C, -DRB1, -DQB1. hlaDnaFieldsType: HLA values obtained by DNA based typing methods hlaDnaFieldsType = “<FIELD1>” string of max length 20 “</FIELD1>”, “<FIELD2>” string of max length 20 “</FIELD2>”; Example: <DNA><FIELD1>01:01</FIELD1><FIELD2>05:01</FIELD2></DNA> DNA typing results can be given for loci that are defined as hlaLocusSerDnaType and hlaLocusDnaOnlyType. These loci include HLA-A, -B, -C, -DRB1, -DQB1, -DRB3, -DRB4, -DRB5, -DQA1, -DPA1, -DPB1. Finally, previously the dot20 file format allowed to submit values like 01 in DNA fields. We can no longer accept this and you have to submit the equivalent of 01, so '01:XX' . hlaGlsFieldType: HLA GL String typing value or GL String like typing value. hlaGlsFieldType = "<GLS>"string of max length 255"</GLS>" Example: <GLS>008:01:01/008:01:02/008:03/008:04+018:01/018:02</GLS> DNA GL String like typing is now used for MICA and MICB. Full HLA example: <HLA> Minimal required elements Minimal typing values for Donor: A (either SER or DNA), B (either SER or DNA) Minimal typing values for CBU: A (either SER or DNA), B (either SER or DNA), DRB1 (either SER or DNA) Please note:
<HLA><A><SER><FIELD1>1</FIELD1><FIELD2 /></SER></A> or <MICA><GLS>008:01:01/008:01:02/008:03/008:04+018:01/018:02</GLS></MICA>
2.4 kirType elementsThe kirType Field Definitions consists of the type: kirLocusType. This is defined as a String with 3 characters: "POS" or "NEG". "POS" means "Presence of KIR gene", "NEG" means "Absence of KIR gene". The following elements are possible and in this specific order: <KIR2DL1>,<KIR2DL2>,<KIR2DL3>,<KIR2DL4>,<KIR2DL5A>,<KIR2DL5B>,<KIR2DS1>,<KIR2DS2>,<KIR2DS3>,<KIR2DS4>,<KIR2DS5>,<KIR2DP1>,<KIR3DL1>,<KIR3DL2>,<KIR3DL3>,<KIR3DS1>,<KIR3DP1>.
2.5 idmType elementsThere are many infectious disease markers (IDM) possible in the element IDM. Many IDM elements can have either the values idmValueType or idmValueExtType idmValueType includes the following values: "P","N" idemValueExtType include the following values: “P”,“G”,“M”,“B”,“H”,“O”,“N” Only when there is old version fields name, then will be in a separated collapse box:
2.6 donItemType elementsDonItemType elements contain elements that are specific for donors and not applicable for CBUs.
2.7 cbuItemType elementsCbuItemType elements contain elements that are specific for CBUs and not applicable for donors.
2.8 matType elementsThe matType elements are a sub-element from the element CBU.
|
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||
---|---|---|---|---|
| ||||
#Minimal required dataOrganisations providing donor or CBU data, should at least include the following elements with valid values. Without this data, the records will be rejected during the validation procedure. Note: For the generation of the value of GRID, check a WMDA "checksum" calculator example here. More detail of the introduction and "checksum" calculation rule, you can check the ISBT 128 Standard for GRID here.
|
Tab Pane | Vectors (Formerly: SP Tab pane) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
#XML example filesWe already provided you the XSD files, but these files do not show directly how an XML file with those definitions will look like. Therefore we created some example files: one for donors and one for CBUs. The XSD schema can be download here: Both files contain only 2 records, but in those two records almost all possible elements contain a value. It can help you to check the order of the elements in your own XML file. Please be aware that values like GRID are fictive and do not follow the rules for the check character. We suggestion you to always implement the latest version. Important to know for XML structure: Currently, the error handling can not handle the data structure as below if there is no records included for both FULL/DIFF upload mode.
If the upload is for DIFF and there is indeed no record, the format should be as below:
XSD 2.3 examples: Example donor file: ION-1234-D-XSD23.xml
Example CBU file: ION-1234-C-XSD23.xml
XSD 2.2 examples: (Planned Expiration in 2026) Example donor file: ION-1234-D-XSD22.xml
Example CBU file: ION-1234-C-XSD22.xml
XSD 2.1 examples: (Expire in 2025)
Validation of your XML filesAfter generating your XML files, you are advised to validate the generated XML file. You may use any XML tool that includes validation for that, for example the open source Qxmledit or XMLLINT. You can use xmllint by invoking the program giving the XML file and the Schema file, and it will generate a report.
Then first correct the xml error by run the xmllint as below without schema:
then the XML is even not an valid XML, then run to check the structure error with xmllint cmd as below
Viewing large filesXML files tend to be large. For quick visual inspection and search you may use Glogg (windows) Generate XML file from excel data sourceWMDA suggest two methods to generate the XML file manually for small dataset.
|
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||
---|---|---|---|---|
| ||||
#File namesRegistries with data on stem cell donors and cord blood units should separate these two data sets and provide two files: one for stem cell donors, and one for cord blood units. Data of stem cell donors and cord blood units should not be combined in one file. In the filename the distinction between donor data and cord blood unit data is made clear. The first part of the filename is "ION-" (without the quotes) followed by the ion number and either a "D-" for donors (without the quotes) or a "C-" (without the quotes) for cold blood units. This <ION> should be similar to the one provided in the field <POOL>. The extension of the file is ".XML". Using this naming convention the name of the Austrian cord blood registry is: ION-2614-C.XML and the name of the German donor registry is: ION-6939-D.XML After encryption, the file should follow almost the same name convention as for the xml file name, but then xml is replaced to pgp. So the first part of the GPG-filename is identical to the XML-filename. The GPG software will either add a second extension ".PGP", or replace the ".XML" extension of the data file with the ".PGP" extension. As an example, the file name of an encrypted Austrian cord blood file would then be: "ION-2614-C.PGP" (without the quotes). If you are listing organisation and are also sending data from other listing organisations (with ION), you can provide the inventory of different POOL IDs together in one file. However, you should not combine donor and CBU data together. For the file naming, please always use the ION from the organisation that is sending the data. |
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||
---|---|---|---|---|
| ||||
#How to compress your XML file with ZIP
When your file is larger then 200Mb, you have to compress your file by using ZIP. If your file is smaller, you are also encouraged to compress your file, because the time to upload your file will be reduced. Please find below some methods to compress your file with ZIP when you are using any of the operating systems Windows, OS, or Linux/unix. Please note: When you are using another method to compress your file, like tar, we cannot decompress your file during processing and we have to reject the file. Creating a compressed zip file in Windows
It is also possible to first create your ZIP folder and then drag the file to your zip folder. Creating a compressed zip file in OS X
Creating a compressed zip file in Linux
|
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
#How to encrypt your XML fileWMDA will only accept pgp encrypted XML files for data upload. We will now describe how you can encrypt your xml file. If you have a very large file, you should first compress your file with ZIP before you encrypt your file. Please see the picture below for a schematic representation of the encryption en decryption process.
Encryption is performed by the organisation who is sending data to WMDA; decryption is performed by WMDA to be able to process and validate the data in your file. For this encryption, you should use the WMDA public key. This is the new public key: public key (download the file in this link) You may also fetch the key from the link or the https://keys.openpgp.org/vks/v1/by-fingerprint/B83744C5CE38C10265E36120C44E0E7A736E374E
Please note: This key is different from the key that you used to encrypt your DOT20 file. STEP 1: Encryption programThe DOT20 file also needed to be encrypted. The procedure is actually the same, but you now have to use the new public key. Currently, there are several different software packages that you can use to encrypt and decrypt your files. It depends of course also of your operating system which programs you can use. Here are some examples: Windows: Kleopatra (download here), PGP Tool OS (MAC): GPG Suite Linux/unix: GnuPG GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP ). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG , is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG is Free Software (meaning that it respects your freedom). It can be freely used, modified and distributed under the terms of the GNU General Public License . For installation on your Linux/Unix machine, please visit the following page for HowTos: https://www.gnupg.org/documentation/howtos.html STEP 2: Import the public keyAfter installing your preferred program, you have to import the public key.
For Linux/Unix, importing of the key in your gpg keyring can be done by using the following command:
Alternatively, instead of saving this file and importing the key, you may look it up at a keyserver. For example, if you use Kleopatra, use CTRL-SHIFT-I and search for 0xC44E0E7A736E374E Getting the key : https://keyserver.ubuntu.com/pks/lookup?search=0xC44E0E7A736E374E&fingerprint=on&op=index If you use gpg from the commandline, use STEP 3: Encrypt XML or ZIP file with the public keyNext step is to use the public key that you just imported into your encryption program to encrypt your XML or zipped XML file.
For Linux/Unix, encryption of your file can be done by using the following command:
where ID is replaced with that key's ID The short version of the above command is:
Please note: Do not sign your file. This will result in rejection of your file during processing. User guide for Kleopatra(Windows):
|
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||
#Explanation of Errors and Warnings in your processing report
After submitting a file you will receive a processing report in your data upload service account. This document describes explanations of warnings or errors as you may find them in the processing report. In the explanations below you find references to various fields from the file format for data delivery. For details on these field names and the file format look in the tabs 'XML file' and 'File name' of this page. The ID of the donor or CBU will be displayed as well. This helps you find the problem line in the file you have sent, and hopefully helps you correct the problem. Business validation rules appliedWMDA has additional business validation rules in place to ensure that even though the data supplied on a field level might be correct they need to have passed the validation rules applied sometimes on multiple fields to ensure correct data is being added to the GCD database. As part of providing us the XML your organisation should also perform these checks to ensure the validity of the data you are providing. Business validation rules in excel file
File ErrorsFileError: Empty file or file without data. Explanation: When the size of the received file is zero bytes, or no data could be read from the received file, this error is returned. Record Errors
HLA/DNA Related ErrorsHLA/DNA-ERROR: Invalid allele value X found for DNA-"Allele". Example: <HLA><DRB4><DNA><FIELD1>01:01/</FIELD1><FIELD2>value</FIELD2></DNA></DRB4></HLA> Explanation: The value for DRB4 contains a slash (/) which is invalid. If such a problem is found the allele values are blanked and processing of the record continues. So, this is a warning, and not an error that requires the record to be rejected!Another examples might be an C*04:AVK (AVK is assigned bij the NMDP as 01/02/03/04/05/06) which is not valid since the C*04:02 is not assigned. HLA/DNA-ERROR: Invalid DNA string found: "some string" Example: For HLA A, the following value is given: 01:01/01:02/01:03/01:04. Explanation: The DNA string given A*01:01/01:02/01:03/01:04 is not valid since the A*01:04 does not exist. Another reported problem may be that a ambiguity in the format of A*01:01/02/03 is invalid. HLA/DNA-ERROR: Invalid HLA antigen "some value" found for field "field name". Example: Serological HLA A30/3 is given in the file. Explanation: The antigen or search determinant value "30/3" for HLA-A in this example is invalid. HLA/DNA-ERROR: Incomplete typing found: HLA-A and HLA-B are required. Explanation: At least one HLA-A and -B antigen or serological value should be available to be able to match the record. If no HLA-A or -B values (either on DNA level or on serological level) are available the record is rejected. HLA/DNA-ERROR: "DNA allele values" does not match "serology". Equivalents for DNA alleles are ... Example: HLA-B*15:02,15:26N does not match serological HLA-B76,62. Equivalents for the DNA-B alleles are: 75(15) Explanation: The serology and DNA values provided, are validated separately, but also matched. If there is no match between the provided serology and the provided DNA, the record is reported. HLA/DNA-ERROR: Number of alleles for DRB3/4/5 is more than 2; DRB3/4/5 blanked. Example: Values are given for DRB4 for FIELD 1 and FIELD 2 and also for DRB5 for FIELD 1 Explanation: Only two allele values are allowed for DRB3, DRB4 and DRB5 combined. HLA/DNA-ERROR: DRB3 (or DRB4 or DRB5) does not match HLA-DR "values". DRB3 (or DRB4 or DRB5) blanked. Example: Serology DR is 4 and 11; DRB5 is 01:XX Explanation: DRB5 is associated with DR2, DR15(2), DR16(2) or DR1(rare). Likewise, DRB3 is associated with DR3, DR5, DR6, DR11(5), DR12(5), DR13(6), DR14(6), DR1403, DR1404, DR17(3), DR18(3); and DRB4 with DR4, DR7, DR9. |
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||
---|---|---|---|---|
| ||||
Cord blood bank IDsIn the XML file format we also defined two fields that are referring to cord blood banks: BANK_MANUF_ID and BANK_DISTRIB_ID.
Please find in the table below the ID you have to use for your cord blood banks. The number always consist of 4 digits and is not the same as your ION number. We expect that the BANK_MANUF_ID and the BANK_DISTRIB_ID will be the same for many CBUs.
How to find your ID?
OR Contatc the WMDA Office at: support@wmda.info
PLEASE NOTE: EMDIS is using very similar fields, but here you need to use a different ID.
|
Tab Pane | Vectors (Formerly: SP Tab pane) | ||||
---|---|---|---|---|
| ||||
Why deprecated code?WMDA has developed HLA nomenclature guidelines, which have been published in 2007 and 2012. The HLA typing of your donors and cord blood units is validated based on these guidelines. If you list donors/cord blood units, it may happen that you receive the message that the HLA of your donor or cord blood unit is invalid. There are two forms of ‘deleted’ alleles:
What you see in the report?For data exchange between your organisation and WMDA, it is acceptable to use the older designation for renamed alleles for a period of one year after the renaming. During this grace period, you will receive the following message in your processing report (see below example messages): #Warning at locus B*: renamed HLA code B*47:01:01:01 is still in grace period, New: 47:01:01:03 And if the deprecated code already passed one year grace period time, you will receive the following message in your processing report: #Warning at locus B*: deprecated HLA code A*23:ABEBP is now invalid and passed its grace period hence blanked, New: 23:AFVGH 23:AZVXU What to do with the deprecated code warning?If you receive such warning messages, you have to update the HLA allele or MAC code within one year. WMDA will not mention the final date of the grace period in the processing report. You can find this information on: http://hla.alleles.org/alleles/deleted.html. WMDA will provide you advice on how to replace the code. It may be that there are several options possible to update the allele or MAC code. WMDA recommends to perform the replacement using rules as following:
For 2018 the following alleles were deleted: 2019 Update With the recent HLA Nomenclature Release 3.35.0, the allele HLA-C*03:99 has been renamed to HLA-C*01:169. While renaming of alleles usually does not affect the first two fields of an allele name, this does and as a consequence affects the HLA haplotype frequencies (HF). In fact, we use this allele for the HF sets of DE (1 haplotype) and East Asia (eas, 15 haplotypes). The affected haplotypes have a cumulated frequency of around 1 copy for each of the two HF sets. We have one abroad patient with that HLA-C*03:99 in the Search&Match database for whom a HLA-C mismatched donor was requested in 2017. Summary: In case you need any support, we recommend to contact the WMDA at: support@wmda.info. | ||||
SP Horizontal nav item | ||||
| ||||
|