The HL7 Value Transformers Extension Library adds custom transformers for shaping plain text into values that can be inserted into HL7 fields and components. Use it when a workflow value needs to become an HL7 XPN person name, XCN clinician/provider name, XAD address, XTN phone number, or cleaned identifier value.

This extension library runs directly as transformer code loaded from Integration Soup's Custom Libraries folder.

Download IntegrationSoup.HL7ValueTransformers.msi

Each transformer has a Value parameter for the source text and an Output Variable parameter for the converted result. If Output Variable is left blank, the transformer uses its default variable name, such as XPN, XCN, XAD, or XTN.

Default output variables are Digits for Digits only, LettersAndDigits for Letters and digits only, LettersDigitsSpaces for Letters, digits and spaces only, XPN for Text to HL7 person name, XCN for Text to HL7 clinician name, XAD for Text to HL7 address, and XTN for Text to HL7 phone.

Included Transformers

• Digits only keeps numeric digits, for example (021) 555-0100 becomes 0215550100.
• Letters and digits only removes spaces and punctuation and uppercases letters, for example z aa-0067 becomes ZAA0067.
• Letters, digits and spaces only removes punctuation, collapses repeated spaces, and uppercases letters.
• Text to HL7 person name (XPN) converts names such as Example Patient into Patient^Example.
• Text to HL7 clinician name (XCN) converts clinician/provider names into an XCN identifier and name shape.
• Text to HL7 address (XAD) converts street and locality text into street, other designation, city, state, and postcode components.
• Text to HL7 phone (XTN) cleans phone values, normalizes common international prefixes, and places detected extensions into XTN component 8.

What The HL7 Transformers Produce

Text to HL7 person name (XPN) creates the common HL7 person-name shape family^given^middle. If the input already contains HL7 component separators, each component is escaped and kept in place. If the input contains a comma, the text before the comma is treated as family name and the text after it is split into given and middle names. Without a comma, two name words are treated as given family, and three or more name words are treated as given middle family. Recognized titles such as Dr, Doctor, Mr, Mister, Mrs, Ms, Miss, Master, Prof, and Professor are placed in XPN component 5. Use the optional Name Order parameter when the source has a known order such as FML, LFM, First Middle Last, or Last First Middle.

Examples: Patient, Example becomes Patient^Example, Donald X Duck becomes Duck^Donald^X, Dr Example Doctor becomes Doctor^Example^^^Dr, and CORLEY BRIAN THOMAS with Name Order set to LFM becomes CORLEY^BRIAN^THOMAS.

Text to HL7 clinician name (XCN) creates the common HL7 clinician/provider shape person identifier^family^given^middle. The optional Person Identifier parameter is placed in XCN component 1. If it is left blank, the transformer can detect a leading numeric identifier or a bracketed alphanumeric identifier that contains a digit. Bracketed text without digits, such as a nickname, is kept in the name text with the brackets preserved. Use Name Order to override the default name parsing; add I or ID when the identifier is part of the source value.

Examples: 12345 CORLEY BRIAN THOMAS becomes 12345^THOMAS^CORLEY^BRIAN, CORLEY BRIAN THOMAS with Name Order set to LFM and Person Identifier set to 12345 becomes 12345^CORLEY^BRIAN^THOMAS, and Christina Smith (A1234) becomes A1234^Smith^Christina.

Text to HL7 address (XAD) creates the common address shape street address^other designation^city^state/province^postal code. It accepts either separate address lines or comma-separated address parts. When there is a unit, flat, suite, or similar line before the street line, that earlier line is placed in the other designation component. Locality lines such as Wollongong NSW 2500, Auckland 1010, or separate city and postcode lines are split into the city, state, and postcode components.

Examples: 1 Example Street plus Wollongong NSW 2500 becomes 1 Example Street^^Wollongong^NSW^2500, and Flat 2, 1 Example Street, Auckland, 1010 becomes 1 Example Street^Flat 2^Auckland^^1010.

Text to HL7 phone (XTN) returns a cleaned phone number suitable for an HL7 telecom field. It removes spaces, brackets, dashes, and punctuation, keeps one leading +, converts a leading 00 international prefix to +, and cleans common +64 (0) and +61 (0) formats. If the text includes an extension marker such as ext, extn, extension, x, or #, the extension is placed in XTN component 8.

Examples: +64 (0)21 555 0100 becomes +64215550100, and 09 555 0100 ext 123 becomes 095550100^^^^^^^123.

Using It In A Workflow

1. Run the MSI on the Integration Soup server.
2. Restart the Integration Soup Host Service so the server loads the new transformers.
3. Open the transformer or mapping step that prepares the outbound value.
4. Add one of the HL7 Value Transformers to the transformer chain for the source value.
5. Set the transformer's required Value parameter to the source text you want to convert. This can be a mapped field, variable, data-table value, or typed text.
6. Set Output Variable if you want a custom workflow variable name. If it is left blank, the transformer writes to its default variable, such as XPN, XCN, XAD, or XTN.
7. Insert or map that workflow variable into the target HL7 field or component.

Each transformer converts the single value supplied in the Value parameter and stores the converted text in a workflow variable. It does not replace the current message text.

The name transformers also expose optional parameters. Name Order accepts compact values such as FML, FL, LFM, and LF, or words such as First Middle Last. Use / between alternatives. The XCN transformer also has Person Identifier for XCN component 1.

HL7 Escaping

The name and address transformers escape HL7 separators in component values. Backslash, pipe, caret, ampersand, and tilde become HL7 escape sequences, and line breaks inside a component become spaces.

Requirements And Notes

• The input should be the single plain-text value you want to transform.
• The phone transformer keeps a single leading +, converts a leading 00 international prefix to +, and removes common punctuation.

• Extension Library Directory
• HTML to PDF
• RTF to PDF
• Azure Activities
• AWS Activities
• Encryption Activities
• SFTP Activities
• Validate HL7 Transformer
• HL7 Value Transformers
• Data from PDF

Download HL7 Soup and Integration Host

Return to the Tutorials Directory