Automatic Lab Message Processing

Owned by Candice Louw (Unlicensed)
Last updated: Jul 22, 2024
3 min read

Introduction

This guide explains under which circumstances SORMAS can automatically process incoming lab messages. For this to work, the FETCH_MODE property of the EXTERNAL_MESSAGES feature configuration needs to be disabled and the external adapter connecting to SORMAS via ReST to push lab messages needs to call ExternalMessageFacade.saveAndProcessLabmessage.

The lab message needs to contain information about most required fields of persons, cases, samples, and pathogen tests in SORMAS. While some fields can be filled in by the system based on individual implementations for the country/adapter in use (e.g. the "Verified by supervisor" field of pathogen tests), a lab message that is e.g. missing a first or last name cannot be automatically processed.

In addition, ExternalMessageDto contains a field called automaticProcessingPossible. The adapter connecting to SORMAS is responsible for setting the value of this field to tell SORMAS whether it is allowed to automatically process the message in the first place. If this field is set to false, SORMAS will not automatically process the message under any circumstances. How this field is set depends on the internal logic of the adapter in question.

General Preconditions

In general, SORMAS can automatically process lab messages if one of the following conditions apply:

  • A national health ID is specified in the lab message and there is no person with a similar national health ID in the system.

  • A national health ID is specified in the lab message, there is a person with a similar national health ID in the system, but the personal details of both persons match.

  • No national health ID is specified in the lab message and the database does not contain a matching person.

In any other case, SORMAS does not automatically process the lab message because it would not be able to unambiguously associate the lab message with a person.

Scenario 1: National Health ID Specified

Scenario 1.1: National Health ID Not Existing

If the lab message contains a national health ID and the SORMAS database does not contain a person with the same national health ID, automatic processing is always possible. SORMAS will:

  • Create a new person

  • Create a new case for this person

  • Create a sample associated with that case

  • Create a pathogen test associated with that sample

Scenario 1.2: National Health ID Existing

If the lab message contains a national health ID and the SORMAS database already contains a person with the same national health ID, SORMAS checks whether the personal details of the lab message match those of the person in the SORMAS database. For this check to be successful, all of the following fields either need to be identical or empty:

  • First name

  • Last name

  • Birth date

  • Street

  • Postal code

  • City

If at least one of those fields does not match, automatic processing will not be done as SORMAS can't be sure whether the two persons are actually identical.

Otherwise, SORMAS will now check the database for a case of the disease specified in the lab message belonging to the matching person. For this, the automaticSampleAssignmentThreshold field of the respective disease configuration in the database is used. The value of this field defines how old an existing case might be in order for SORMAS to assign the sample and pathogen test resulting from the lab message to it instead of creating a new case.

  • If SORMAS does not find a case of the specified disease belonging to the person, a new case with a new sample and pathogen test is created.

  • If SORMAS finds a case of the specified disease belonging to the person and no automatic sample assignment threshold is defined for this disease, automatic processing is not possible because SORMAS can't determine whether to assign the sample and pathogen test to this case or a newly created one.

If SORMAS finds a case of the specified disease belonging to the person and an automatic sample assignment threshold is defined for this disease, it now checks whether the found case(s) fall into the sample assignment threshold. For this, it compares the sample date of the earliest existing sample for that case to the current date (or falls back to the case report date if the case does not have any samples yet):

  • If the time period between these two dates is lower than the defined threshold, a new sample and pathogen test are created for the existing case

  • If the time period between these two dates is higher than the defined threshold, a new case is created and associated with the created sample and pathogen test

Scenario 2: National Health ID Not Specified

If the lab message does not contain a national health ID, SORMAS performs a search for potentially duplicate persons in the database according to the person similarity criteria.

  • If no potentially duplicate person exists, SORMAS will create a new person, case, sample and pathogen test based on the contents of the lab message.

  • If at least one potentially duplicate person exists, automatic processing is not possible.