Anatomy of the ACORD TXLife XML standard

Under the covers of the insurance industry's primary XML standard

The ACORD Transactional/Business Wrapper (TXLife) XML specification has increasingly become the preferred data format for internal and external data integration within the life, annuities, and health insurance industry. The standard is broad and flexible—a blessing and a curse for implementers. This article provides an introduction to the structure of ACORD TXLife messages, the challenges implementers face, and the tools and techniques that you can use to successfully implement the standard.

Jamie S. Mazur, Software Consultant, PilotFish Technology

Jamie Mazur is a freelance IT consultant and solutions architect for PilotFish Technology. Jamie specializes in data integration, Java, and XML-related technologies, with almost 10 years of working with ACORD XML. He has a passion for seeing the practical application of innovative technical solutions to real-world business problems. Jamie holds several patents in distributed computing techniques. When not behind the glow of his laptop, Jamie is an avid underwater photographer and dedicated father of two.



18 October 2011

Also available in Chinese

Like many other commercial segments, the insurance industry has become increasingly reliant on XML standards for internal and external data integration. In the life, annuities, and health insurance world, the Association for Cooperative Operations Research and Development (ACORD) organization is the standards-bearer, and the ACORD Transactional/Business Wrapper (TXLife) Specification schema is the dialect of choice. Getting started with this complex standard can be a daunting task. In this article, learn the basic structures in an ACORD TXLife XML message as well as how to successfully navigate the standards documentation.

The ACORD standards organization

Frequently used acronyms

  • ACORD: Association for Cooperative Operations Research and Development
  • ACORD TXLife: ACORD Transactional/Business Wrapper
  • GUID: Globally unique identifier
  • XML: Extensible Markup Language
  • XSD: XML Schema Definition

ACORD is the focal point for standards development in the insurance industry. A membership organization comprised of insurance carriers, brokers, agencies, service providers, and vendors, ACORD strives to meet the evolving needs of the industry through the collaborative development of relevant standards. Throughout the association's history, the nature of these standards has evolved to include a variety of deliverables, such as electronic data interchange (EDI) formats, paper forms, and XML schemas. ACORD also serves a wide audience across three distinct verticals: Life, Annuities, and Health; Property and Casualty; and Reinsurance.

This article explores the XML standard for the Life, Annuities, and Health vertical—known in ACORD jargon as the ACORD TXLife standard. TXLife is used for both internal and external integration among industry systems.

Example applications of the ACORD TXLife standard include:

  • Submission of an insurance application to a carrier
  • Sending and receiving orders, status, and results of underwriting requirements
  • Communication of insurance product "profiles" to distributors
  • Transmission of commission information
  • Exchange of in-force or pending policy data

Access the ACORD TXLife standards documentation

Before exploring the standard any farther, however, download the most recent version of the ACORD TXLife XML specification (see Resources for a link). Note that there are separate member and non-member options as you download the file. Significant differences exist between the public and member downloads of the ACORD standard: If you are working for an insurance company or other industry participant, it's worthwhile to determine whether your organization has a membership. Representatives of member companies can easily register on the ACORD website and gain access to the enhanced content.

The public ACORD download contains:

  • The ACORD Life Standards Object Reference Model (PDF)

    This is the best place to start to gain a general understanding of how the TXLife standard is structured. It provides a diagrammatic view of the major components of the ACORD TXLife Schema, serving as a high-level road map to the various logical entities in the model.

  • The ACORD Life Standards Public Documentation (PDF)

    This document is the most comprehensive publicly available source of information about the standard. It offers:

    • A detailed overview of the use of the standard
    • Information about TXLife transaction types
    • A "dictionary" of the logical entities and their field-level documentation
    • The allowable code values for "type code" fields (enumerations)
  • The ACORD TXLife XML Schema (XSD)

    This is the XML schema itself.

The members' download additionally provides:

  • The ACORD Life Standards Help File (CHM)

    This document contains similar information to what is available in the ACORD Life Standards Public Documentation but represented in a more easily navigable Windows® help file format.

  • The ACORD Life Standards Metadata (XML)

    This XML file provides in-depth information about the ACORD model, including documentation and enumerations, in a machine-readable format. This is arguably the most overlooked yet most valuable members-only asset.

  • Alternate (enumerated/documented) version of the TXLife Schema (XSD)

    Three versions of the TXLife schema are included in the members download rather than just one:

    • Clean

      Identical to the public schema

    • Enumerated.

      Includes the allowable values for each type code field

    • Documented

      Includes xsd:annotations to document elements and type code values


Anatomy of an ACORD TXLife message

Now that you have the reference materials you need to work with the TXLife standard, take a look at the skeletal structure of a typical TXLife message (Listing 1).

Listing 1. Listing 1. A typical TXLife message
<TXLife>
  <TXLifeXXX>
    [TXLife Header Section]
      <OLifE>
        [Top Level Objects, e.g., Party/Holding/PolicyProduct/Relation]
      </OLifE>
  </TXLifeXXX>  
</TXLife>

The root node of any ACORD TXLife XML document is <TXLife>. Look at this element first if you're navigating the schema itself.

A second wrapper element is inside the TXLife root element. Although several other options are available, this is most typically <TXLifeRequest>, <TXLifeResponse>, or (less frequently) <TXLifeNotify>.

You use <TXLifeRequest> when submitting an initial request or when initiating a transmission of information. You use <TXLifeResponse> when responding—typically synchronously—to a <TXLifeRequest>. Although you can create a <TXLifeRequest> tag for which no <TXLifeResponse> is expected (for instance, in a fire-and-forget messaging pattern), the reverse is not typical. Most of this structure should be intuitive. What is not as obvious is that a <TXLifeRequest> does not necessarily have to be a request for information. Instead, it can represent a simple transmittal of information, such as the status of an application for insurance. <TXLifeNotify>, which you might assume is correct for this purpose, is actually a seldom-used construct for notifying a requester that some information is ready pending retrieval.

The immediate children of the secondary header are a set of header-like elements that describe the transaction itself. Listing 2 provides one example.

Listing 2. Listing 2. A skeletal TXLife transaction
<?xml version="1.0" encoding="UTF-8"?>
<TXLife Version="2.25.00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://ACORD.org/Standards/Life/2">
<TXLifeRequest>
         <TransRefGUID>C396EEB0-171B-11D4-AB93-009027E539F</TransRefGUID>
         <TransType tc="103">New Business Submission</TransType>
         <TransExeDate>2003-09-11</TransExeDate>
         <TransExeTime>10:48:40</TransExeTime>
         <OLifE>
         </OLifE>
</TXLifeRequest>
</TXLife>

The TransRefGUID is a GUID used to uniquely identify the request. This element is also used as a correlation ID on a corresponding TXLifeResponse message. Although this example uses a standard GUID format in this field, the standard does not impose this. As a result, some implementations generate a more natural key based on certain critical data elements in the message.

The TransType is the transaction type of the message. You may have noticed that the TXLife schema is a single XSD without any message-specific data elements. For instance, there is no NewBusinessRequestMessage element type definition. Instead, the recipient determines the type of message being received from the numeric tc attribute of the TransType element in the header. After the recipient knows the TransType, he or she can make assumptions about how to interpret the business data contained in the XML stream.

Commonly used example TransTypes include:

  • 121. General requirements order request
  • 103. New business submission
  • 1125. Case status notification transmittal
  • 1206. Commission statement transmittal

The ACORD Public TXLife Standards documentation provides basic details for each transaction type in the standard. These details include the general purpose of the message along with the expected content of an XML instance document with the specified TransType.

It is important to note that currently ACORD does not publish transaction-specific sub-schemas. The TXLife schema provides an expansive dictionary of data types that you can use in a given message. Within the schema, most elements are optional. The standards documentation provides basic guidance on which fields and data aggregates become required in the context of a specific transaction type.


Represent business data objects with OLifE

The <OLifE> element within the second-level header (for example, TXLifeRequest) is the container for the business data in the message. Look at the ACORD Life Standards Object Reference Model. In this PDF, you will see all of the children of the <OLifE> element. In the ACORD vernacular, these children are called top-level objects. They invariably represent the principal actors or subjects of the TXLife message.

Listing 3 offers an example of a complete TXLife message with an OLifE message body.

Listing 3. Listing 3. Complete TXLife message with OLifE
<TXLife Version="2.25.00">
  <TXLifeRequest PrimaryObjectID="Policy_1">
    <TransRefGUID>706D67C1-CC4D-11CF-91FB444554540000</TransRefGUID>
    <TransType tc="502">Holding Change</TransType>
    <TransExeDate>2006-11-19</TransExeDate>
    <TransExeTime>13:15:33-07:00</TransExeTime>
    <ChangeSubType>
      <ChangeTC tc="9">Change Participant</ChangeTC>
    </ChangeSubType>
    <OLifE>
      <Holding id="Policy_1">
        <HoldingTypeCode tc="2">Policy</HoldingTypeCode>
        <Policy>
          <PolNumber>1234567</PolNumber>
          <LineOfBusiness tc="2">Annuity</LineOfBusiness>
          <Annuity>        
          </Annuity>
        </Policy>
      </Holding>
      <Party id="Beneficiary_1">
        <PartyTypeCode tc="2">Organization</PartyTypeCode>
        <FullName>The Smith Trust</FullName>
        <Organization>
          <OrgForm tc="16">Trust</OrgForm>
          <DBA>The Smith Trust</DBA>
        </Organization>
      </Party>
      <Relation id="Relation_1" 
          OriginatingObjectID="Policy_1"
          RelatedObjectID="Beneficiary_1">
        <OriginatingObjectType tc="4">Holding</OriginatingObjectType>
        <RelatedObjectType tc="6">Party</RelatedObjectType>
        <RelationRoleCode tc="34">Primary Beneficiary</RelationRoleCode>
        <BeneficiaryDesignation tc="1">Named</BeneficiaryDesignation>
      </Relation>
    </OLifE>
  </TXLifeRequest>
</TXLife>

In this message, the primary beneficiary is being added or changed on a policy. There are two top-level objects: the <Holding> and the <Party>. Coincidentally, these are the two most heavily used top-level objects in the ACORD model. Other top-level objects that you are likely to encounter include <PolicyProduct>, <FormInstance>, and <InvestProduct>.

A <Holding> represents any type of financial holding. Most often, it will be a policy, but it can also be an investment, loan, or mortgage. A <Party> represents a person or organization.

In this example, the <Holding> represents an insurance policy. You can determine that this is a policy by the presence of the <Policy> child aggregate as well as through the value of the <HoldingTypeCode>. Similarly, you can see that the <Party> is in fact an organization, given the value of the <PartyTypeCode> and the presence of the <Organization> tag. This is a common design pattern throughout TXLife. Inheritance relationships are most often represented as child elements indicating subtypes. There is at least one other example of this in the XML instance document in Listing 3. Try to find it.


Relationships among top-level objects

You may have noticed that I have not yet discussed the third top-level object in the example. The <Relation> element is the primary means of defining the relationship between two top-level objects. The concept is similar to that of a "many-to-many" relationship table in a database system.

The <Relation> element has the components shown in Table 1.

Table 1. Table 1. Core components of the TXLife Relation element
ComponentDescription
@OriginatingObjectIDA reference to the object that is the noun in the relationship
@RelatedObjectIDA reference to the object that is the direct object of the relationship
OriginatingObjectTypeThe originating top-level object's type
RelatedObjectTypeThe originating top-level object's type
RelationRoleCode/@tcThe nature of the relationship between the two objects

Using this structure, TXLife implementers can avoid duplication of data in the XML stream, as a single entity (for example, a person) can serve in multiple roles within the same message (for example, the insured and owner of an insurance policy).

Rather than using different natural keys based on the object type, ACORD uses IDs and ID references as pointers between related objects. All top-level objects in the model have an id attribute. By convention, IDs are typically created by concatenating the type of the object, an underscore (_), and a counter (for example, "Party_1", "Holding_2").

The content of the id attribute can only to be used to determine relationships between objects within the same TXLife message. They are not intended to be maintained between XML streams. That is, the same logical entity may have a different ID in a later TXLifeRequest or a related TXLifeResponse.

In addition to their use within <Relation> elements, object ID attributes are used in conjunction with ID references throughout the model whenever one object directly references another. ID references of this type are also represented as attributes—for example:

<RequirementInfo AppliesToPartyID="Party_1"
 PhysicianPartyID="Party_2" FulfillerPartyID="Party_3">

Type codes

IDs and ID references are one of the two major uses of XML attributes in the ACORD TXLife XML schema. The other use is ACORD type codes. The type code is the TXLife mechanism for representing any standardized list of allowable values in the standard.

The previously discussed <TransType> tag is an example of a field that uses the type code structure:

<TransType tc="502">Holding Change</TransType>

Any tag with a tc attribute represents a type code field. Type codes have an enumerated set of integer values that you can use as the attribute. These values correspond to a set of human-readable descriptions typically used as the textual body of the element.

A common mistake in ACORD implementation is to code to the text value, not to the tc attribute. The text value is only present for legibility and should never be used in defining processing rules. Another less-common problem is "inventing" type code values rather than using the values enumerated in the ACORD standard.

In those cases where ACORD has not defined a particular value as an option in the enumerated type code list, implementers have the option of using the "Other" value: 2147483647. This value is different and distinct from the "Unknown" value: 0. If the use of "Other" proves too broad (as in the case where you do need to perform processing on this custom value), you can use an ACORD private type code value—a range of integers reserved for customized use. Refer to the standards documentation for the specifics on this topic.

If you are not an ACORD member, you will need to refer to the ACORD Life Standards Public Documentation PDF for valid type code values and their text equivalents. Members can use the documented version of the schema, the machine-readable metadata XML file, or the help file to find this information.


Extensions

The TXLife schema is exceptionally broad and flexible, but there are occasionally times when you need to extend the model. ACORD offers two mechanisms—<OLifeExtension> and <KeyedValue>—to accommodate customization without sacrificing schema compliance.

Most aggregates in the TXLife schema include the OLifEExtension element. This element is defined with type <xsd:any> and can be used to hold arbitrary, custom, complex XML extensions. The VendorCode attribute is defined by ACORD and serves a purpose similar to a namespace. It allows the receiving party to determine who has defined the extension (Listing 4).

Listing 4. Listing 4. Example of an OLifEExtension
<OLifEExtension VendorCode="000">
  <CustomStuff>
    <CustomA>This is important</CustomA>
    <CustomComplexStuff>
      <CustomField>1.0</CustomField>
    </CustomComplexStuff>
  </CustomStuff>
</OLifEExtension>

The other extension mechanism is a KeyedValue. KeyedValues provide a means of adding a simple field to a supporting aggregate:

<KeyedValue VendorCode="000">
  <KeyName>CustomField</KeyName>
  <KeyValue>1.0</KeyValue>
</KeyedValue>

Real-life ACORD implementation challenges and solutions

Now that you have taken a tour of the major components of an ACORD TXLife message, consider the challenges that accompany real-life implementation.

The flexibility of the ACORD standard is a double-edged sword

If you have paged through the documentation or loaded up the schema in the tool of your choice, you were likely impressed by the breadth of what has been defined. Think of an industry-relevant message, and it can probably be represented with the ACORD TXLife schema.

However, this flexibility also carries with it the burden of ambiguity. ACORD does not publish transaction-specific schemas. Even the human-readable documentation for a given transaction type leaves many elements optional and much open to interpretation. As a result, it is possible to build a transaction "to the specification" and even to have it "certified" by ACORD itself, yet have it fail to meet the requirements of the trading partner or system with which you are trying to communicate.

When you are acting as the sender of an ACORD TXLife message, your first source for detailed transaction requirements should be the receiver. Many vendors and service providers have created their own "implementation guides," often containing sample XML payloads. Use these guides as the starting points for your implementation, with the ACORD documentation as supporting reference material.

When you are building a process to receive an ACORD TXLife message, do consult the ACORD transaction documentation, schema, or any relevant ACORD-published implementation guides. However, also consider adopting conventions similar to others that work with the same transaction.

The ACORD TXLife schema presents challenges to traditional tooling

The nature and structure of the ACORD TXLife schema presents its own challenges. First, the schema itself is huge—several megabytes in size. This can cause many of the generic XML tools on the market to respond poorly or crash altogether. The size and scope of the schema can also cause trouble when it is used in conjunction with object-binding technologies such as the Java™ Architecture for XML Binding (JAXB) or when used within a Web Services Description Language (WSDL) file against which a code-generation utility may be run.

It is often advisable to "slim" or "slice" the schema to include only those data elements you will be using in your transaction or transaction set. Although you can certainly do this manually, it is a painstaking process. ACORD and several ACORD-aware vendors offer utilities to facilitate the definition of these sub-schemas.

Second, mapping and transforming proprietary data formats to and from the ACORD TXLife structures can be a daunting task. The main challenge comes from the heavy use of the Relation structure and the reuse of top-level objects. Most graphical transformation tools are linear in nature: You connect a field in the source format to a field in the target. However, in ACORD, the same field (for instance, under "Party") can be used in a number of different contexts (the insurance carrier, the agent, the insured, the beneficiary, and so on).

Think about mapping to the structure of a specific transaction, not to the entire ACORD schema. To this end, consider using a template-based transformation language such as Extensible Stylesheet Language Transformations (XSLT). Using XSLT, you can use a sample XML document for a given transaction as the base of your transformation. From there, you can map your proprietary data into the correct instance of a given top-level object.

With a few rare exceptions, the ACORD Schema enforces element order. Most things are defined as an <xsd:sequence> of many optional elements (top-level objects are an exception). This requires either a great deal of care when handcrafting your transactions or selecting tooling that handles it for you.

If you do choose a language such as XSLT to generate your mappings, pay attention to element order as you build your transaction. Most schema validation tools provide vague error messages when TXLife elements are not in the correct order. The large number of optional elements on a given aggregate can make it maddeningly difficult to determine which fields have been transposed. It is much easier to build your message with this in mind than to go back and correct validation errors after the fact.


Conclusion

The ACORD TXLife specification is a powerful and widely implemented XML standard in the life, annuities, and health insurance industry. Although the schema is immense, the learning curve is manageable after you understand the basic structure of any TXLife message.

XML instance documents begin with the <TXLife> header, where the transaction type and other messaging semantics are defined. The core of a TXLife message is the OLifE element and the top-level objects with which it is populated. Top-level objects such as <Party> and <Holding> represent the business data in the message. The relationships among these objects are handled through the unique <Relation> structure.

The size of the ACORD schema and the absence of transaction-specific schemas create special considerations for ACORD development projects. These factors should be considered during the design and tool-selection phase of an implementation. Luckily, the ACORD website offers a number of utilities and reference materials that will help you get started in the right direction.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML
ArticleID=765409
ArticleTitle=Anatomy of the ACORD TXLife XML standard
publish-date=10182011