⚠Due to planned maintenance you will experience short (<30 min) downtime between 08:00 - 08:30 CET.
XML file format
1. Introduction
The overall scope of BMDW development phase two is to receive more data from our listing organisations and to make these data available through our Search & Match Service. However, the old format (DOT20) is not an appropriate format when you have many different fields/columns. Therefore, we had to move to another file format. The new file format is an XML (Extensible Markup Language) file, which is considered an industry standard that is extendable, robust and easy to use.
Several people from the community formed a working group to create the required XML Schema Definition (XSD) files. These files define the elements that are allowed in the XML file, the order of the elements and the values that will be accepted. The names of the elements are based upon EMDIS specifications and aligns with the EMDIS Data Dictionary when appropriate. Several elements are basic elements that should be included in all files, but there are also elements that are specific for only donors or only cord blood units (CBUs).
We will now explain the composition of the XML file and how you should use the XSD reference files.
2. XSD schema files
We provided two XSD schema files that define the structure of your XML file: basicTypes.xsd and Inventories.xsd.
The Inventories file describes the structure of the XML file and the order of the elements. Here you can also find if a certain field is mandatory or not (minOccurs="0"-> not mandatory). This file includes many "complexTypes" : an XML element that contains other elements and/or attributes. In the file you can see that the values of the elements can be defined here, like the elements GRID and ID, or that after the name of the field a "type" is defined. For example for the element with name BIRTH_DATE you see type="bareDateType". The definition of "bareDateType" is described in the basicTypes.xsd file.
We will now describe the global structure of the XML file and the elements.
2.1 InventoryType elements
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
CREATION_TIME | Yes | Creation time stamp of the inventories (in UTC) | dateTime | minimal 20 | Without fractional seconds the length is 20, for example: 2016-08-23T13:16:48Z. Additional notes: CREATION_TIME is defined as "Creation time stamp of the <INVENTORIES>" that means the time in UTC when the complete and valid file was finally created at the registry. This can be the same as SNAPSHOT_TIME. |
LISTING_ORGANIZATION | Yes | Organisation that lists the donor/cbu provided as ION | ionType: number between 1000 and 9999 | 4 | Issuing Organisation Number (ION) allocated by ICBBA. This can be different from the POOL when another organisation is sending the data to BMDW. |
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 | Only UPDATE_MODE "FULL" is currently supported. Always the complete inventory should be send. |
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 | 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 elements (for Donors and CBUs)
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
ID | Yes | Unique identifier of the donor/CBU | String | 17 | Unique identifier of the donor/CBU: The value comprises the EMDIS hub code + donor identification allocated by the associated donor registry, where the sending organisation is an EMDIS member, otherwise the two digit ISO country code of the associated donor registry + donor identification allocated by the associated donor registry. For example: AU600196166, DEGOE-35487, US087013165, SB45 |
GRID | No | Global registration identifier of the donor/CBU | String | 19 | |
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" 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" 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", |
CCR5 | No | CCR5 status of the donor/CBU | ccr5Type | 2 | ccr5Type: "DD","WW","DW" |
HLA | Yes | HLA of the donor/cbu | hlaType | Explained separately at hlaType 2.3 | |
KIR | No | KIR genotype of the donor/CBU | kirType | Explained separately at kirType 2.4 | |
IDM | No | Infectious disease markers (IDM) and other relevant tests of the donor/CBU | idmType | Explained separately at idmType 2.5 | |
RSV_PAT | No | Unique identifier of the patient the donor/CBU is reserved for (STATUS=RS). | String | 17 | 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. |
STATUS | Yes | Status of the donor/CBU | statusType | 2 | statusType: "AV","TU","RS" ("DE" is not supported yet, "RE" not valid for CBUs) |
STAT_END_DATE | No | Date until which the current status will be applicable | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
2.3 hlaType elements
HlaType 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 hlaLocusType. 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>”;
Exanple: <DNA><FIELD1>01:01</FIELD1><FIELD2>05:01</FIELD2></DNA>
DNA typing results can be given for loci that are defined as hlaLocusType and hlaLocusDnaOnlyType. These loci include HLA-A, -B, -C, -DRB1, -DQB1, -DRB3, -DRB4, -DRB5, -DQA1, -DPA1, -DPB1.
Finally, '01:XX' is equivalent to '01'. Both codes '01:XX' and '01' are allowed.
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)
NOTES:
- It is no longer possible to submit string HLA values; only single values are allowed.
- When a donor or CBU has homozygous alleles/values, please use the following notation:
<HLA><A><SER><FIELD1>1</FIELD1><FIELD2 /></SER></A> ...
or
<DQB1><DNA><FIELD1>05:02:01G</FIELD1><FIELD2 /></DNA></DQB1>
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
SER | depends on content type and DNA fields provided | HLA values obtained by serological typing methods | hlaSerFieldsType | 5 | Each SER element contains two other elements: FIELD1 and FIELD2 |
DNA | depends on content type and SER fields provided | HLA values obtained by DNA based typing methods | hlaDnaFieldsType | 20 | Each DNA element contains two other elements: FIELD1 and FIELD2 |
FIELD1 | HLA value of allele 1 | 5 or 20 | Element within the element SER and DNA | ||
FIELD2 | HLA value of allele 2 | 5 or 20 | Element within the element SER and DNA | ||
A | Yes | HLA-A values | hlaLocusType | Both SER and DNA possible; either SER or DNA values required | |
B | Yes | HLA-B values | hlaLocusType | Both SER and DNA possible; either SER or DNA values required | |
C | No | HLA-C values | hlaLocusType | Both SER and DNA possible | |
DRB1 | Yes (CBU) No (Donor) | HLA-DRB1 values | hlaLocusType | Both SER and DNA possible; either SER or DNA values required for CBU | |
DRB3 | No | HLA-DRB3 values | hlaLocusDnaOnlyType | Only DNA possible | |
DRB4 | No | HLA-DRB4 values | hlaLocusDnaOnlyType | Only DNA possible | |
DRB5 | No | HLA-DRB5 values | hlaLocusDnaOnlyType | Only DNA possible | |
DQA1 | No | HLA-DQA1 values | hlaLocusDnaOnlyType | Only DNA possible | |
DQB1 | No | HLA-DQB1 values | hlaLocusType | Both SER and DNA possible | |
DPA1 | No | HLA-DPA1 values | hlaLocusDnaOnlyType | Only DNA possible | |
DPB1 | No | HLA-DPB1 values | hlaLocusDnaOnlyType | Only DNA possible |
2.4 kirType elements
The 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>.
There is another field called <KIR_GL> (URI that refers to a GL-string registered with a GL-service or direct GL-string for absence / presence) this field is not used at the moment and must be empty.
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
KIR gene e.g. KIR2DL1 | No | KIR genotype e.g. KIR gene 2DL1 | kirLocusType | 3 | valid values: "POS" = presence of KIR gene; "NEG" = absence of KIR gene |
2.5 idmType elements
There 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”
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
CMV | No | CMV status | idmValueExtType | 1 | idmValueExtType: “P”,“G”,“M”,“B”,“H”,“O”,“N” EMDIS data dictionary also has a ‘Q’ (questionable / unclear) but that will not be applicable within the BMDW data submission file. |
CMV_NAT | No | CMV NAT status | idmValueType | 1 | idmValueType: "P","N" |
CMV_DATE | No | Date of CMV test | bareDateTyp | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
HBS_AG | No | Hepatitis B status (hepatitis B surface antigen) | idmValueType | 1 | idmValueType: "P","N" |
ANTI_HBC | No | Hepatitis B status (antibody to hepatitis B core antigen) | idmValueType | 1 | idmValueType: "P","N" |
ANTI_HBS | No | Hepatitis B status (antibody to hepatitis B surface antigen) | idmValueType | 1 | idmValueType: "P","N" |
ANTI_HCV | No | Hepatitis C status (antibody to hepatitis C virus) | idmValueType | 1 | idmValueType: "P","N" |
ANTI_HIV_12 | No | Anti-HIV 1/2 status | idmValueType | 1 | idmValueType: "P","N" |
HIV_1_NAT | No | HIV-1 NAT status | idmValueType | 1 | idmValueType: "P","N" |
HIV_P24 | No | HIV p24 status | idmValueType | 1 | idmValueType: "P","N" |
HCV_NAT | No | HCV NAT status | idmValueType | 1 | idmValueType: "P","N" |
ANTI_HTLV | No | Antibody to HTLV I/II | idmValueType | 1 | idmValueType: "P","N" |
SYPHILIS | No | Syphilis status | idmValueType | 1 | idmValueType: "P","N" |
WNV | No | WNV status | idmValueType | 1 | idmValueType: "P","N" |
CHAGAS | No | Chagas status | idmValueType | 1 | idmValueType: "P","N" |
EBV | No | EBV status | idmValueExtType | 1 | idmValueExtType: “P”,“G”,“M”,“B”,“H”,“O”,“N” EMDIS data dictionary also has a ‘Q’ (questionable / unclear) but that will not be applicable within the BMDW data submission file. Please leave blank for Q. |
TOXO | No | Toxoplasmosis status | idmValueExtType | 1 | idmValueExtType: “P”,“G”,“M”,“B”,“H”,“O”,“N” EMDIS data dictionary also has a ‘Q’ (questionable / unclear) but that will not be applicable within the BMDW data submission file. Please leave blank for Q. |
HBV_NAT | No | HBV NAT status | idmValueType | 1 | idmValueType: "P","N" |
PB19_NAT | No | ParvoB19 NAT status | idmValueType | 1 | idmValueType: "P","N" |
ALT | No | Alanine aminotransferase status in units per litre | Short | Number, no decimals, minimal value is 1 |
2.6 donItemType elements
DonItemType elements contain elements that are specific for donors and not applicable for CBUs.
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
STAT_REASON | No | Additional information relevant to the donor status | statReasonDonType | 2 | statReasonDonType: "DO", "DD","MR", "PR","TX", "MO", "UC", "TQ", "OT", "UK" |
CONTACT_DATE | No | Date of last confirmed contact - defined as the date of an active form of communication (e.g. a query about status, an address update, confirmation of their interest in donating) via any channel (e.g. email, mail, phone, website), post registration, from a donor to the registry. Any communication from the registry to the donor that does not lead to an activity of the donor suggesting his further interest in donation is explicitly excluded (e.g. annual mailing without reaction). | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
CHECKUP_DATE | No | Date of the last medical checkup - defined as the date of a donor health assessment that indicates whether a donor is minimally suitable to be considered for donation, regardless if eligible for only one donation type, and includes questions about current medication and health issues (e.g. completion of a health screening questionnaire at Extended Typing or Verification Typing). The donor health assessment can be completed by any means (e.g. paper-based, online, phone). This does not require any physical examination of a donor. | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
WEIGHT | No | Weight in kg | Short | Number between 1 and 999, no decimals | |
HEIGHT | No | Height in cm | Short | Number between 1 and 999, no decimals | |
NMBR_TRANS | No | Number of blood transfusions | Short | Number: zero or greater, no decimals | |
NMBR_PREG | No | Number of pregnancies | Short | Number: zero or greater, no decimals | |
NMBR_MARR | No | Number of marrow donations | Short | Number: zero or greater, no decimals | |
NMBR_PBSC | No | Number of PBSC donations | Short | Number: zero or greater, no decimals | |
COLL_TYPE | No | Collection type, i.e. the willingness of the donor to donate in a specific manner | String | 1 | collTypeType: "M", "P","B" |
2.7 cbuItemType elements
CbuItemType elements contain elements that are specific for CBUs and not applicable for donors.
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
STAT_REASON | No | Additional information relevant to the CBU status | statReasonCbuType | 2 | statReasonCbuType: "QR","AD","CD","DS","XP","MR","MO","OT","UK" |
LOCAL_ID | No | Identification of CBU locally at the associated CBB | String | 17 | |
BAG_ID | No | Identification as it appears on the bag. If more than one bag is available then this data attribute is not populated | String | 17 | |
BANK_MANUF_ID | No | Unique identifier of the CBB that manufactured the CBU: The value comprises the EMDIS hub code + id allocated by the associated EMDIS hub, where the cord registry is an EMDIS member, otherwise the two digit ISO country code of the associated cord registry + id identification allocated by the associated cord registry. For example: AUCBB1, SB890 | String | 10 | PLEASE NOTE: For the upload to BMDW the fields BANK_MANUF_ID and BANK_DISTRIB_ID should be fulfilled with a new ID for the corresponding cord blood banks. These new IDs will be generated by BMDW and sent out to the registries so that they are able to fulfill the two ID fields or at least the BANK_MANUF_ID field.
These IDs are important to allow BMDW to identify if the CBU is from an accredited bank which will be displayed within a search report. |
BANK_DISTRIB_ID | No | Unique identifier of the CBB distributing the CBU: The value comprises the EMDIS hub code + id allocated by the associated EMDIS hub, where the cord registry is an EMDIS member, otherwise the two digit ISO country code of the associated cord registry + id identification allocated by the associated cord registry. For example: AUCBB1, SB890 | String | 10 | Please see note above |
COLL_DATE | No | Date that the CBU was collected | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
PROC_DATE | No | Date that the processing started | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
PROC_METH | No | Processing method used | procMethType | 3 | procMethType: "HES","DGS","CEN","FIL","FIC","PER","OTH" NOTE: Values "NOT" and "UNK" are not supported "NOT" can now be found in CB_PROD_MOD = "NOT", "UNK" has to be transmitted as empty (CB_PROD_MOD = "") |
PROC_METH_TYPE | No | Processing method type used | procMethTypeType | 3 | procMethTypeType: "MAN","SPX","OTP","AXP","OTH" |
FREEZE_DATE | No | Date that the CBU was frozen | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
FREEZE_METH | No | Freezing method used | freezeMethType | 1 | freezeMethType: "C","M" |
PROD_MOD | No | Product modifications made | prodModType | 3 | prodModType: "BCE","DNE","PLR","PRR","RBR","NOT","OTH" |
BAG_TYPE | No | Type of bag used (bag fractions / split unit) | bbagTypeType | 5 | bagTypeType: "80/20","50/50","40/60","NS" |
BAGS | No | Number of bags for CBU sub units | Short | Number between 1 and 99, no decimals | |
BACT_CULT | No | Bacterial culture | cultValueType | 1 | cultValueType: "P","N","D" |
FUNG_CULT | No | Fungal culture | cultValueType | 1 | cultValueType: "P","N","D" |
HEMO_STATUS | No | Hemoglobinopathy screening status | hemoStatusType | 2 | hemoStatusType: "DN","DU","NS","CD","NC","DT","DD" |
VOL | No | Collected volume before processing (without additives) in ml | Short | Number between 1 and 9999 | |
VOL_FRZN | No | Total volume frozen (post processing, prior to cryopreservation) in ml | Short | Number between 1 and 9999 | |
TNC | No | Total number of nucleated cells (before processing) | Float | Number with decimals | |
TNC_FRZN | No | Total number of nucleated cells (post processing, prior to cryopreservation) | Float | Number with decimals | |
RED_BC_FRZN | No | Total number of nucleated red blood cells (post processing, prior to cryopreservation) | Float | Number with decimals: minimum is 0.0E0, maximum is 999.9E7 | |
MNC_FRZN | No | Total Number of mononucleated cells (post processing, prior to cryopreservation) | Float | Number with decimals | |
CD34PC | No | Total number of CD34+ cells (before processing) | Float | Number with decimals | |
CD34PC_FRZN | No | Total number of CD34+ cells (post processing, prior to cryopreservation) | Float | Number with decimals | |
CFU_FRZN | No | Total count of colony forming units (post processing, prior to cryopreservation) | Float | Number with decimals | |
VIABILITY | No | Viability as percentage value | Short | Number between 0 and 100, no decimals | |
VIABILITY_DATE | No | Date that viability was tested | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
VIABILITY_CELLS | No | Type of cells tested for viability | viabilityCellsType | 6 | viabilityCellsType: "TNC","CD34PC","CD45PC" NOTE: VIABILITY_CELLS = "CD34PC" corresponds to CB_VIABILITY_CELLS = "CD34" in EMDIScord. VIABILITY_CELLS = "CD45PC" corresponds to CB_VIABILITY_CELLS = "CD45" in EMDIScord. |
VIABILITY_METHOD | No | Method used to calculate the viability | viabilityMethodType | 2 | viabilityMethodType: "7A","PI","TB","OT" |
ATT_SEG | No | Number of attached segments available | Short | Number between 0 and 99, no decimals | |
DNA_SMPL | No | DNA samples available? | Boolean | true,false | |
OTH_SMPL | No | Samples other than DNA available? | Boolean | true,false | |
CT_COMPLETE_DATE | No | Date of completion of confirmatory typing (CT) | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
CT_SMPL_TYPE | No | Confirmatory typing (CT) sample type | ctSmplTypeType | 2 | ctSmplTypeType: "AS","WB","RC","FP","ED" |
AL_RED_BC | No | Number of red cell fraction aliquots | Short | Number between 0 and 99, no decimals | |
AL_SER | No | Number of serum aliquots available | Short | Number between 0 and 99, no decimals | |
SER_QUANT | No | Total quantity of serum available in ml | Float | Number between 0.0 and 99.9, one decimal | |
AL_PLA | No | Number of plasma aliquots available | Short | Number between 0 and 99, no decimals | |
PLA_QUANT | No | Total quantity of plasma available in ml | Float | Number between 0.0 and 99.9, one decimal | |
MAT | No | Data of the mother of the infant associated with the CBU | matType | see further on this webpage matType |
2.8 matType elements
The matType elements are a sub-element from the element CBU.
Field Identifier | Required | Description | Type | Length | Comment |
---|---|---|---|---|---|
ID | No | Identification used to identify the maternal donor as assigned by the registry | String | 15 | |
ID_BANK | No | Identification used by associated CBU manufacturer to identify maternal detail | String | 15 | |
HLA | No | HLA of the mother of the infant associated with the CBU | hlaType | see above in section 2.3 hlaType | |
IDM | No | Infectious disease markers (IDM) and other relevant tests of the mother of the CBU | idmType | see above in section 2.5 idmType | |
AL_SER | No | Number of serum aliquots available | short | Number between 0 and 99, no decimals | |
SER_QUANT | No | Total quantity of serum available in ml | Float | Number between 0.0 and 99.9, one decimal | |
AL_PLA | No | Number of plasma aliquots available | Short | Number between 0 and 99, no decimals | |
PLA_QUANT | No | Total quantity of plasma available in ml | Float | Number between 0.0 and 99.9, one decimal |
Minimal required data
Organisations 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.
A DONOR record should include:
- ID
- BIRTH_DATE
- SEX
- HLA (including at least HLA-A (SER or DNA) and HLA-B (SER or DNA))
- STATUS
A CBU record should include:
- ID
- BIRTH_DATE
- HLA (including at least HLA-A (SER or DNA), HLA-B (SER or DNA) and HLA-DRB1 (SER or DNA))
- STATUS
XML example files
We 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.
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. These two examples are based on the XSD files version 2.1.
Example donor file: ION-1234-D.xml
Example CBU file: ION-1234-C.xml
File names
Registries 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.
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
- Click to highlight the file that you need to zip. Please note: BMDW can only accept your file when the zip file contains 1 file.
- Right-click the file and select Send to > Compressed (zipped) Folder.
- Windows will create the zip file and will position the cursor where you can choose a unique name for the file.
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
- Open a new Finder window and navigate to the file.
- Click to highlight the file that you need to zip.
- Select File > Compress from the pull-down menu. Sometimes you can also click with your right mouse button on the file and use the quick menu.
- Finder will compress the selected file and will create the zip file with the same same as your file but with the extension .zip.
Creating a compressed zip file in Linux
- Open a terminal session and navigate to the location of your file
- To view a listing of directory contents, enter the following command: ls
- Note the files to be zipped.
- Create the zip file by entering the command: zip {.zip-filename} {filename-to-compress} (e.g. zip ION-1234-D.zip ION-1234-D.xml)
How to encrypt your XML file
BMDW 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 encrypted 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 BMDW; decryption is performed by BMDW to be able to process and validate the data in your file.
For this encryption, you should use the BMDW public key.
This is the new BMDW public key: BMDW public key
Please note: This key is different from the key that you used to encrypt your DOT20 file.
STEP 1: Encryption program
The DOT20 file you sent before to BMDW also needed to be encrypted. The procedure is actually the same, but you now have to use the new BMDW 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, 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 BMDW public key
After installing your preferred program, you have to import the BMDW public key.
- First download the key to your computer.
- Open your encryption program and look for something like import (PGP) key or import certificate. Click on this and then you have to upload the file with the BMDW public key and save the key.
For Linux/Unix, importing of the key in your gpg keyring can be done by using the following command:
$ gpg --import {public_key_file}
STEP 3: Encrypt XML or ZIP file with BMDW public key
Next step is to use the BMDW public key that you just imported into your encryption program to encrypt your XML or zipped XML file.
- In your encryption program, go to the function called encrypt or encrypt files.
- A windows with all your files will open. Look up the file you would like to encrypt.
- Following the steps in your program and make sure you choose the BMDW public key to encrypt your file
- Some programs work together with your file exploring program like Finder for Mac or Explorer for windows. If this is the case, go to your file look-up program and look for your file.
- Select your file and click on the right mouse button. A quick menu will become visible. Look for something with encryption or GPG or with a MAC it is probably under Services. This depends on the program you installed on your computer. Click on that and follow the instructions on your screen.
- Make sure you choose the BMDW public key to encrypt your file.
For Linux/Unix, encryption of your file can be done by using the following command:
$ gpg --encrypt --recipient ID {filename_to_be_encrypted}
where ID is replaced with that key's ID
The short version of the above command is:
$ gpg -e -r ID
{filename_to_be_encrypted}
In either case, a file is created with the same name, plus an additional .gpg file extension added to the end. Thus, if your file is ION-1234-D.xml, you will create an encrypted copy of the file named ION-1234-D.xml.gpg.
Please note: Do not sign your file. This will result in rejection of your file during processing.