Other 90%: Document Schema Designer

Using DSD to Create Valid User-Defined Segment Schemas

Contributed by Jeffrey Dyell, Sr. Engineering Consultant, Pervasive Services Group

(The general consensus among the user community as well as inside Pervasive Software is that thousands of people use 10% of the functionality of the Pervasive® Data Integrator™ toolset to accomplish specific integration goals. People who already own the tools are frequently unaware of the other 90% of the tool's abilities which they could be leveraging. The Other 90% series of articles will spotlight a less well-known piece of Pervasive integration functionality each issue to help users get the most out of the software.)

The Pervasive Document Schema Designer (DSD) is one of the schema designers in Pervasive Data Integrator. Unless you deal with EDI data on a regular basis, you could use Data Integrator for years and never know DSD exists as anything but one of the shortcuts on the menu. Even people who use DSD on a regular basis may not be aware of it. Many health, financial, and other industry standard document schemas like FIX, HL7, HIPAA, EDIFACT, EDI_VICS, HCFA1500, SWIFT, Tradacom, UB92, and X12 are pre-made and readily available from Pervasive. Your sales associate will have information on how to obtain them if you have a need. While a huge subset of business exchange file formats are covered by these standard schemas, within these formats, there is a certain degree of variation. User-defined segments are sometimes used in different ways by different companies. DSD has the flexibility to allow quick easy adaptation to those unique bits of otherwise standard files. DSD even makes creating a brand new schema for a little known EDI format relatively simple by allowing the re-use of existing segment, field, and code libraries.

Simplicity

DSD, like most Pervasive design tools strives to balance ease-of-use for basic tasks with deep power for complex or unusual tasks. In general, if you have an HL7 file, or nearly any other standard interchange file that you wish to either read from or write to, you simply open Map Designer, select HL7 as your connection type, select the pre-built document schema for that version of HL7 and type of file, and select the file. For many users, this is the extent of their use of DSD, using the document schemas already created in DSD and provided to them by Pervasive. That's the ease-of-use, simplicity aspect of the tool, and if standard EDI files are the only data you need to deal with, that gets the job easily and efficiently done. But sometimes, working with EDI data isn't that simple.

Power

For the purpose of showing some of the power of DSD, I'll walk you through creating a custom user-defined Z segment in an HL7 file that is very similar to something we built for a customer recently. For the purposes of this article, I'll just show the first three fields of the custom segment. That should be plenty for you to get the idea of how it's done since the procedure is fairly straightforward. This same procedure can be used to customize any document schema, or even to create new schemas. All of the standard schemas that Pervasive provides were built just like this in DSD using standard specifications as the guide.

Creating a User Defined Segment Schema

This example uses a HL7 2.3 document schema file. The first thing to do is to copy the appropriate document schema, code library, segment library, and field library from the HL7 2.3 folder and paste it into your workspace so that the modifications will not affect the templates. In this case, the example is an A04, patient registration. The files to copy into the workspace are:

HL723.ADT^A04.0.0.ds.xml - the document schema
HL723.codelib.0.0.dcl.xml - the HL7 2.3 code library
HL723.fieldlib.0.0.dfl.xml - the HL7 2.3 field library
HL723.seglib.0.0.dsl.xml - the HL7 2.3 segment library

Open the Map Designer in Pervasive Data Integrator, and select HL7 as the Source Connection.

Select the HL7 2.3 A04 document schema by clicking the down arrow and selecting the HL723.ADT^A04.0.0.ds.xml file.

In the HL7 Properties dialog to the right, browse to and select your local copies of the field and segment libraries, HL723.codelib.0.0.dcl.xml, and HL723.fieldlib.0.0.dfl.xml.

Next, click the "..." button to open Document Schema Designer. This will open the A04 patient registration document schema.

Next choose, the Segment Library tab. Scroll to the bottom of the list to the Z.. user-defined segment. Click on that. In the right column, click on ID to select, then double click in Value to edit. We're going to call this new segment ZZZ.

Type "ZZZ" under Value and push Enter on your keyboard. DSD is somewhat unusual in that it doesn't always accept data changes unless Enter is pushed on the keyboard, so it's good to get into the habit of pushing enter whenever you make a change.

In the File menu, choose Save Segment Library. The window should look like this now.

Right click on the new ZZZ segment in the left column and choose Insert Field.

The first field is a Set ID. In the right column, click under Value next to Item, type Z01, and press Enter. If we were designing a document schema from scratch, following a spec, a standard field number would be chosen from the drop-down list. For a user-defined segment, the Item number is whatever the businesses exchanging this file agree on.

Click on Name, then double click under Value to edit. Type Set ID and press enter.

The data type for this field is SI. Data types are in alphabetical order in the drop down list under Value next to DT.

This field is optional, so leave Opt set to O. Length is 4. Enter that. Leave Repeat set to N since it is non-repeating. Your window should look like this now:

Right click on the field Z01 in the left column, and choose Insert Field. From the layout agreed to by the companies exchanging this file, this field has the properties:

Item - Z02
Name - Patient Temporary Address
DT - AD
Seq - 2
Opt - O
Len - 106
Repeat - N

After entering those properties, right click on that field and choose Insert Field again. The last field in this example has these properties:

Item - Z03
Name - Residence Date
DT - DT
Seq - 3
Opt - O
Len - 8
Repeat - N

Since this example only has these three fields in the user defined segment, this segment is done. From the File menu, choose Save As Segment Library and make certain that you are saving over the copy in your workspace, not the original template library.

Select the Message Definition tab.

Right click on the Segment at the bottom of the definition, the UB2-UB92 data segment. Choose Insert Segment.

In the right column, click in the Value field of ID and click the down arrow. The new ZZZ segment will be the last one in the list since they are in alphabetical order. Choose it, and you will see the fields you have added appear in the bottom half of the right column.

Name the new Segment "User Defined" and put 0 in the Value column next to MinOccurs, so that the segment is optional.

The window should look like this now:

Choose File - Save As Document Schema to save the changes made to this schema and close DSD.

Chose the Document Schema in Map Designer by clicking the down arrow next to the Document Schema box and selecting it.

Switch over to the Map tab so that you can see the new segment. The default Map tab interface is a bit difficult to follow with EDI files. Click Map All on the toolbar This should give you an eaiser to read list of segments in the upper half of the left column. Scroll down to the bottom and click on the plus sign next to ZZZ. Select ZZZ Fields to see the fields available in the new segment.

The AD data type, address, was chosen for Field Z02 in DSD. This has several sub-fields, street address, city, state, etc. that are standard with an AD field. All of these could now be accurately mapped into a database using Map Designer if you had an HL7 file with this user-defined segment in it, or if this same new schema was connected on the target side, a customized HL7 file could be created containing this information.

This example should give a general idea of the power of the Document Schema Designer to customize existing EDI schemas and even to create new ones if needed.