Implement HL7 integration with external immunization systems

Any healthcare organization that administers COVID-19 vaccination to residents must report the information to the state. The state's immunization systems accept the data in HL7 format. The state agencies securely store the vaccination information in their databases to track, manage, and report the overall progress of the vaccination program. For example, Centers for Disease Control and Prevention (CDC) stores the vaccination information in Immunization Information Systems (IIS) databases. As a healthcare organization that administers the COVID-19 vaccination, you are responsible for understanding the specific state and federal requirements for reporting vaccination information.

Important

The message structure to report the vaccination information to state healthcare agencies varies for states and countries. The message HL7 integration capability explained in this article provides a template and reference design for the integration with the state agency's immunization system.

As an implementer, it is your responsibility to determine the structure of the message being generated and make necessary modifications to adapt the message structure to the respective immunization system.

How the sample HL7 integration works

Microsoft Vaccination Management can generate HL7 messages and send these messages to the state agency if implemented by the customer. This is achieved through a set of Microsoft Dataverse plug-ins in the sample integration system; implementers can use any other integration approach based on their requirements.

Here is how the sample integration system works:

1. The HL7 message generation is triggered after the shot is administered and the vaccinator selects Complete vaccination in the Frontline worker app. This creates a vaccination record in Microsoft Dataverse that can be viewed in the Vaccination management app under Vaccination, in the Registration area. After the business logic to associate vaccination documents is complete, the Completed field in the vaccination record is set to Yes. This will trigger the message generation plug-in.

2. After the message is generated successfully, a notification log record is created for the vaccination. This will trigger the plug-in to send the HL7 message to the state agency immunization system. The response from the immunization system will be stored in the same record.

   Message generation can also be triggered by setting the Generate HL7 flag on the vaccination record in the Vaccination management app under Vaccination. This will allow the administrator to fix any data issues and regenerate the message if there are errors when sending the data to the state agency.

Each message generation will create a notification log record. The response from the immunization system will also be stored in the same record, thereby allowing you to have a log of the number of times a particular vaccination record was replayed and any issues with each message.

How to implement HL7 integration

Microsoft provides two plug-ins for generation and sharing of HL7 messages in the sample integration system. You can extend these plug-ins according to your requirements.

Contact your Microsoft representative to get the sample plug-in code.

Generate HL7 message plug-in

The Generate HL7 message plug-in generates an Unsolicited Vaccination Record Update (VXU) message based on the CDC specification. The segments and fields in the message are based on the CDC guidelines. The plug-in generates the message by mapping the Vaccination Management data model fields to the CDC specification. As an implementer, you can update the plug-in code and register a plug-in step against the update of the Vaccination table as shown below.

The plug-in consists of the following files:

• Each segment has its own class files with the fields in each. The mapping for each of the fields to the Vaccination Management data model is done in the Populate<[SEGMENTNAME]>Values function. The implementer will have to modify or add mappings as needed.

• The Constants.cs file contains the values that are constant across the integration. These values must be updated by the implementer because they will change across implementations.

• The CRMHelper.cs file consists of the helper functions needed to query Microsoft Dataverse.

• The HL7Message class has the helper functions that stitch the different segments together. The implementer will have to edit the sequence and the segments in the message structure as required.

• The GenerateHL7Message.cs file has the Execute method with the code to initiate this message generation.

Send HL7 message plug-in

The Send HL7 message plug-in creates the SOAP envelope and sends it to the state's immunization system. As an implementer, you can update the plug-in code and register a plug-in step against the creation of the notification log table as shown below.

To specify the immunization system where the data will be sent, update the configuration mentioned in the Secure configuration of the plug-in. The XML code in the configuration has the following format:

<Settings>
    <setting providerId = "">
    <value name="userName"></value>
    <value name = "password"></value>
    <value name = "iisEndpoint"></value>
    <value name = "facilityId"></value>
    </setting>  
</Settings>

The send process currently supports multiple providers and multiple immunization systems based on the configurations. For each provider, repeat the setting configuration as shown above.

The configuration to be used is decided by the plug-in, and it is based on matching the providerId mentioned in the configuration to the accountnumber value on the provider (account) table.

Because the configuration includes the userId and password required for the service call, the details are mentioned in the Secure configuration of the plug-in. Therefore, this plug-in will need to be run under an admin account.