Confgen Plugin - Usage

The confgen plugin is used to create a set of HAPI structure classes based on an HL7 conformance profile. These structure classes replace the built-in message structures that come with HAPI.

For instance, suppose you are processing an HL7 v2.6 ADT^A01 message. Normally you would take advantage of the HAPI built in type: ca.uhn.hl7v2.model.v25.message.ADT_A01

If you have special requirements however, such as wanting to add custom Z-segments to your message, or remove parts of the structure that you aren't using, you can use this plugin to create your own structures.

Generating a Conformance Profile

Generating a conformance profile requires a free tool called Message Workbench. Message Workbench is free, and can be downloaded from the HL7 tools page (look for "Messaging Workbench" under "V2 Tools"). Note that this tool is Windows only.

When you first start the tool, you will see an empty window:
starting window

Hit "File → New" to create a new blank structure. Hit "File → Change Structure List" and choose the HL7 version you are using. Then hit "File → Load Message Structure..." and then choose the base message type you want to base your message off of:
starting window

You now have a standard HL7 structure you may customize. First, give your specification a name (under Specification), an Organization and an HL7 version. You need to fill these out (even if just with placeholders) or you will get errors later:
starting window

You may navigate the structure using the "message tree" on the lower left of the screen. Next, let's add a custom segment (Z-segment). For this example, we will be adding a segment called ZPV right after the PID segment. First, right click on the "PID" segment in the message tree and hit "Add Seg". Then give your segment a name and description. You might also want to check off "repeatable" if you want your segment to repeat. Click "add" when you are done. Then click "close":
starting window

If you expand the new "ZPV" element in the message tree you can see that MWB has automatically added one field to the segment: "Set ID". If you right click on the Set ID field, you can hit "Add Field" add field to add a new field to the segment. You might also want to delete the Set ID if you don't need it. Enter a name in the text box and select a datatype for the field in the "Select Field Data type". You might also want to check off "repeatable". When you are done, hit "add" and then "done".
starting window

When you have customized the structure to your desired specifications, you will want to save it. (In fact, you should really be saving quite often as the MWB tool can be a bit flaky.) It is important to note that there are two file formats generated by MWB. The first is a native format called ".mwb" which is generated when you hit "File → Save". If you plan on updating your profile in the future, you should always save a copy in this format.

MWB can also generate an XML based conformance profile, which is the format required by HAPI. To generate one, hit "File → Export HL7 Conformance Profile". If this option is greyed out you just need to save your profile as an MWB file, close it, and reopen it (this is a quirk of MWB version 2.8).

Using the Plugin

Usage of the plusing is as follows:

<plugin>
   <groupId>ca.uhn.hapi</groupId>
   <artifactId>hapi-sourcegen</artifactId>
   <version>2.2</version>
   <executions>
      <execution>
         <id>build</id>
         <goals>
            <goal>confgen</goal>
         </goals>
         <configuration>
            
            <!--
            Generated structure classes will be placed in the
            following directory. The plugin adds this to your project
            compilation path. If you are using eclise, you may also want
            to manually add this path to your eclipse source list.  
            -->
            <targetDirectory>${basedir}/target/generated-sources/confgen</targetDirectory>
            
            <!--
            Generated structure classes will be placed in this package.  
            -->
            <packageName>com.acme.hl7.adt</packageName>
            
            <!--
            This is the path to the profile itself.  
            -->
            <profile>${basedir}/src/main/hl7profiles/ADT_A01_FUN.xml</profile>
            
            <!--
            This parameter configures whether or not to generate datatypes. In most
            cases you will want to use NONE, which means that instead of generating
            custom datatype classes the built in HAPI ones will be used. This can
            save a lot of space if you aren't customizing the individual datatypes.
            See the "Confgen Goal" page for more information.  
            -->
            <generateDateTypes>NONE</generateDateTypes>
            
         </configuration>
      </execution>
   </executions>
</plugin>

Using the Generated Sources

Once you have completed the source generation, you have a set of classes you can use in your application.

The following examples assume you have created a custom structure called "ZDT_A01" and generated classes using the confgen plugin.

Sending Custom Structures

To send messages out using your custom structures:

// Create a new instance of the message and initialize it
ZDT_A01 outMsg = new ZDT_A01();
outMsg.initQuickstart("ZDT", "A01", "T");

// .. populate other segments ..
// e.g. outMsg.getPID().getPid3_PatientIdentifierList(0).......

// Create a hapi context and send the message
DefaultHapiContext ctx = new DefaultHapiContext();
Connection conn = ctx.newClient("someserver.com", 8888, false);

// Send the message
Message response = conn.getInitiator().sendAndReceive(outMsg);

Receiving Custom Structures

The easiest way to receive messages and have them parsed into a custom structure is to use a CanonicalModelClassFactory and configure it to always use your custom structure.

DefaultHapiContext ctx = new DefaultHapiContext();
ModelClassFactory mcf = new CanonicalModelClassFactory(ZDT_A01.class);
ctx.setModelClassFactory(mcf);

HL7Service server = ctx.newServer(8888, false);
server.start();