You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

  • The Match-Connect specifications consist of the API documentation and the documents listed below. When developing a Match-Connect implementation all content of the following documents is relevant and needs to be considered:
    • The Semantics of Match-Connect Messages
    • Match-Connect Data Dictionary
  • Albert's note: API docs will provide exact content for each message, so I am making this whole bullet point italic. Each message must contain the two following fields (and therefore they are not mentioned in the message descriptions):
    • HUB_SND, Req 3 and HUB_RCV, Req 3
    • The special value HUB_RCV=”ALL” can be used for the communication with a proxy to exchange CBU_FULL/CBU_DIFF messages. In this case a CBU_FULL or CBU_DIFF message has only to be sent once to the proxy for forwarding it to the associated Match-Connect registries behind the proxy.
    • With the Match-Connect implementation package 12 two new optional fields were introduced:
      • REG_SND (Opt 4) and REG_RCV (Opt 4) which will contain the ION of the sending and receiving Match-Connect registry. These fields will become mandatory and replace in the long term HUB_SND and HUB_RCV.
  • The field attribute REQ means that the field is a required field, i.e. the parser will complain and stop processing if no value is present. The other field attribute is OPT for optional. The parser does not check the existence of values for such fields.
  • The fields for the cell counts will be in scientific notation (e.g. 1.3E6). The maximum field length is seven positions including an optional dot and the required exponent sign ”E”.
  • The reference code (REF_CODE) must be unique over all types of messages at the side of the requesting hub.
  • A DONOR_CB message is mandatory immediately after a TYP_RES, IDM_RES, RSV_RES or NO_RES message (see also definition of DONOR_CB and repeat search (see chapter 9). More generally: every time data on a match list that was provided by DONOR_CB changes, a DONOR_CB becomes necessary to update the master data. Albert's note: this item needs to be rewritten to describe the need for the DIFF upload on the DR side and an optional search result update on PR side.
  • The term ”donor” in this document usually means ”adult donor” or ”cord blood unit” or "adult donor cryopreserved unit". 
  • The institution paying (INST_PAY) has to be of the institution type (INST_TYPE) FIN.
  • The rules applying to the Match-Connect message fields are the following:
    • It is recommended to transmit every known field value every time.
    • The empty string value (two double quotes ”” or two single quotes ”) as field value means that the field’s content is empty and that the corresponding value in the database has to be deleted. The FML undef value (i.e. ’?’ or ”?”) as the field value means that the field’s content is undefined and the corresponding database value has to be left unchanged.
    • The FML undef value is implicitly assigned to all missing fields of a message.
      Common pitfall: a formerly heterozygous typing has to be changed to homozygous. If the second value of the locus is simply omitted (not transmitted), the typing will remain heterozygous at the remote hub! The value has to be deleted explicitly by an empty value (””) in the second HLA field. Albert's not: I believe that this is now in the hands of the S&M system. But I wonder, if the donor upload describes a similar rule.
  • The WMDA nomenclature files (http://hla.alleles.org/wmda/index.html) must be used for all HLA fields. The recipient may reject messages with invalid values. The details are described in the WMDA Guidelines for use of HLA Nomenclature (https://www.nature.com/articles/bmt201393; follow the link ”Supplementary information”).
  • The Match-Connect semantics for the WMDA approved additional codes are defined as follows:
    • Message UUUU NEW XXXX NNNN
    • PAT_UPD N N DRB3/4/5 DRB3/4/5
    • DONOR_CB N N DRB3/4/5 DRB3/4/5
    • PHEN_LIST N N DRB3/4/5 DRB3/4/5
    • ALM_REQ N N DRB3/4/5 DRB3/4/5
    • ALM_RES N N DRB3/4/5 DRB3/4/5
    • TYP_RES N Y DRB3/4/5 DRB3/4/5
    • SMP_RES Y Y DRB3/4/5 DRB3/4/5
  • Match-Connect patient IDs should be defined in a way that a change of patient data such as name, birth date or transplant centre does not result in a changed Match-Connect ID. Once a patient ID has been assigned for a given patient, the patient ID cannot be changed.
  • Detailed information about the Global Registration Identifier (GRID) can be found on: https://share.wmda.info/display/OptimisingSearchMatchConnect/Project%3A+GRID.
  • HLA changes of a recipient must not cancel requests for the recipient. The requests remain under full responsibility of the transplant centre.
  • Duplicate requests on the same day: This issue becomes particularly difficult if SMP_REQs are concerned - sometimes users want to ”correct” their previous request (i.e. forgot to request quantity and product). The correct way of doing this is to cancel the erroneous request first and send the second one later. However, this procedure might also confuse if not carried out on the same working day. In doubt a phone call helps sorting things out.
  • MSG_DEN, WARNING and TXT_MSG messages have to be presented to the responsible user (search coordinator) by the local Match-Connect administrator in an appropriate manner.
  • If there are results which cannot be delivered via Match-Connect for whatever reason, the usage of an FML message (e.g. to give the result in the remark field) is discouraged - fax or email should be used instead.
  • It’s not only useless but forbidden to give a postbox (POB) in a LAB address since this address is used for delivery of samples. For the same reason ZIP code, City and Country are required in the NEW_ADD message.
  • It makes sense to shorten the stored match lists, for example, if the HLA of a patient changes, since some implementations continue to update every donor that was ever reported for a patient. We decided that if PAT_STAT.REASON_CHNG in [NML, RCM] the match list should be cleared of all previously reported donors but those which were requested for the patient. Registries that allow manually inserted mismatch donors for a patient might have to consider a special treatment for them. This may also apply to the donors from ALM_REQ messages. This used to be a requirement for the donor registry. Now it is for S&M system, so not a membership guideline anymore. But storage of the search results must be described in S&M docs.
  • Generally faxes and emails should be avoided in an electronic communication system. If they become necessary, it’s recommended not to mix channels in message groups, for example, if the TYP_REQ was in Match-Connect, the result should be in Match-Connect as well and not by fax/email (and vice versa).
  • Don’t send information multiple times - WARNINGs are to be used if it happens in order to find errors.
  • It’s recommended to use the Match-Connect patient ID on the labels for the verification typing (CT) tubes because the identification by name is error prone.
  • Multiple *_RES or *_ARR messages are regarded as updates and therefore should be different from the previously sent one.
  • Do not initialize integer and float values with zero but use ””.
  • A set target of two hour response time is recommended, i.e. two hours after sending a patient (the email leaving the sending system), the donor lists should have arrived (the email arrived at the sender). This response time can be met within the current Match-Connect infrastructure if down times and time zones are disregarded. This is not a membership guideline anymore but an SLA requirement for the S&M.
  • The correct action if a request cannot be accepted is to send a NO_RES followed by a DONOR_CB. The NO_RES.REASON shall be given as ”OT”. For severe errors, for example, donor unknown, patient unknown or patient not activated, a MSG_DEN plus DONOR_CB shall be sent.
  • Do not change IDs of patients, donors or addresses: use the primary keys of your database tables prefixed by your hub code as Match-Connect IDs.
  • Only use the specified (see Data Dictionary) character set – a character set translation routine might be necessary.
  • Check the MSG_DEN and WARNING messages you receive from your partners.
  • Return the data as you’ve received it, for example, if you had to change incoming data due to national rules, return the original data with the answer.
  • Consider that Match-Connect is asynchronous: for example, if you want to complain about incoming DONOR_CB messages after a search was stopped, wait a reasonable time before doing so.
  • Increase value of p_max_don_dr in order to receive longer donor lists (Question: where is the donor I’ve seen in BMDW with HLA phenotype X? Answer: s/he is on position 41 of the donor list and your patient only allows p_max_don_dr = 40).
  • If unsure about quoting of FML values, quote everything. This would prevent a lot of FML syntax errors and allow the processing side to react with reasonable remarks in the MSG_DEN message. The API documentation must provide sufficient information on this. 
  • Don’t repeat FML headers / FML field names in each FML statement but use the qualifiers/FIELDS and /CONST. FML is intended to be human readable.
  • Don’t send every FML message in an individual email. Summarize multiple messages to one recipient into a single email.
  • Resolution of patient HLA typing: provide the highest resolution of HLA-A,B and DR possible. DNA low (XX) resolution on HLA-A,B and DR seriously hampers DNA based matching and mismatching.
  • Announce changes in your national system, for example, sending/accepting more Match-Connect messages.
  • Don’t change the message channel. For example, if you receive information by fax that you should receive via Match-Connect ask for the appropriate Match-Connect message. Basically, don’t send the same information twice. This is a duplication of already mentioned rule.
  • Try to improve your national Match-Connect interface: automated LAB/TC address updates (danger of lost samples for verification typing (CT) and work-up), recognition of duplicates (patients, requests), and usage of the correct reference code (i.e. of the recipient’s side) in result messages (to allow correct assignment of results).
  • Institution addresses registered in the Match-Connect network must be kept up to date. Any updates (and updates only) of Match-Connect institutions must be transmitted at least once a year.
  • Provide SMP_RES or NO_RES for all samples received even if the donor is reported as unavailable in the meantime. Closing a request formally by sending an appropriate result message is important (for result reminders, invoicing) because often the donor later shows up as AV again.
  • If a new hub does not want to implement the whole set of available message types, reasonable groups of message types should be implemented together.
    • For example, for an incoming search the following messages should be implemented:
      • IN: PAT_UPD, PAT_STAT, ALM_REQ,
      • OUT: DONOR_CB, PHEN_LIST, MATCH_SUM, ALM_RES
    • Support of typing requests:
      • IN: TYP_REQ, REQ_CAN
      • OUT: TYP_RES, MSG_ACK, NO_RES, DONOR_CB
        plus associated administrative messages like MSG_DEN, WARNING, NEW_ADD A proper new example must be thought of.
  • No labels