Skip to main content
Previous sectionNext section

DTL <subtransform>

Invoke another data transformation.

Synopsis

<subtransform class='Test.HL7.SegDTLa'                     targetObj='target.{IN1grp(iin).IN1}'                     sourceObj='source.{IN1grp(iin).IN1}'/>

Attributes

Attribute Description Value
class
Required. Name of the class that contains the data transformation to be invoked. This class must be in the same namespace as the class that invokes it.
Often, class is a DTL data transformation defined using a DTL <transform> element, as shown in the examples in this topic.
Alternatively, class can identify a custom subclass of Ens.DataTransform that implements the Transform method and does not use DTL.
The full package and class name.
sourceObject
Required. Identifies the property being transformed. This may be an object property or a virtual document property. Generally it is a property of the source object identified by the containing <transform> element’s sourceClass and (for virtual documents) sourceDocType. In this case it is referenced using dot syntax as follows:
source.property or source.{propertyPath}
Property name. For virtual documents and their segments, use virtual property syntax.
targetObject
Required. Identifies the property into which the transformed value will be written. This may be an object property or a virtual document property. Generally it is a property of the target object identified by the containing <transform> element’s targetClass and (for virtual documents) targetDocType.In this case it is referenced using dot syntax as follows:
target.property or target.{propertyPath}
In the case of a subtransform with Create as new or copy, it is not necessary to have a pre-existing target object.
Property name. For virtual documents and their segments, use virtual property syntax.

Elements

Element Purpose
<annotation> Optional. A text string that describes the <subtransform> element.

Description

The <subtransform> element invokes another data transformation. Making a call to <subtransform> allows the containing <transform> element to invoke other data transformations to complete segments of its work. This allows developers greater flexibility in maintaining a suite of reusable DTL transformation code.

Before the <subtransform> element was available, every DTL <transform> stood alone. In order to write multiple DTL transformations that contained an identical sequence of actions, it was necessary to copy and paste the corresponding sections of code from one class into another. Now, each of these DTL classes can replace repeated lines with a <subtransform> element that invokes another class to performs the desired sequence.

The source or target objects for a <subtransform> may be ordinary Ensemble objects, virtual document message objects, or virtual document segment objects representing an individual segment within a virtual document message. The <subtransform> is especially important for interface developers working with HL7 Version 2 or other Electronic Data Interchange (EDI) formats, where each message or document may contain many independent segments that need to be transformed. Having the <subtransform> available means you can create a reusable library of segment transformations that you can call as needed, without duplicating code in the calling transformation.

For virtual documents and their segments, you must use virtual property syntax, such as the {} curly bracket syntax in the following examples. The property path inside the brackets must refer to a particular segment, not to a field within a segment or to a group of segments. For background information, see the book Ensemble Virtual Documents; details are available in the section “Virtual Property Path.”

The following set of examples presents the class code for three <transform> elements. The second and third transformations in this example call the first <transform> as a subtransformation. As required by DTL syntax, each of the three <transform> elements resides in the XData DTL block of its own separate data transformation class.

  • The following <transform> applies to fields within the virtual document segment IN1 for HL7 Version 2.3.1 messages. IN1 provides insurance information for the ADT series of patient admission messages, as will become clear from the next two <transform> examples, which call this <transform> using the <subtransform> element.

    It is common to refer to a <transform> that plays this role as a subtransformation. However, the <subtransform> element does not define this code. The XData DTL block in this example shows that the <transform> element is the primary container for this transformation. It does not really become a subtransformation until another <transform> calls it using a <subtransform> element.

    Class Test.HL7.SegDTLa Extends Ens.DataTransformDTL
    {
    Parameter REPORTERRORS = 1;
    
    XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
      {
      <transform targetClass='EnsLib.HL7.Segment' targetDocType='2.5:IN1'
                 sourceClass='EnsLib.HL7.Segment' sourceDocType='2.3.1:IN1'
                 create='copy' language='objectscript'>
        <assign property='target.{InsurancePlanID.Identifier}'
                value='source.{InsuranceCompanyID(1).ID}'
                action='set'/>
        <assign property='target.{InsuranceCompanyID}'
                value='""'
                action='remove'/>
        <assign property='target.{InsuranceCompanyName}'
                value='..ToLower(source.{InsuranceCompanyName})'
                action='set'/>
      </transform>
      }
    }
    
    Copy code to clipboard
  • The following <transform> shows one type of syntax that you can use to invoke a <subtransform>. Here, the example encloses <subtransform> within a <foreach> to perform the same tasks for each IN1 segment found in the ADT_A01 repeating group IN1grp.

    Class Test.HL7.A01SegDTL Extends Ens.DataTransformDTL
    {
    Parameter REPORTERRORS = 1;
    
    XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
      {
      <transform targetClass='EnsLib.HL7.Message'
                 targetDocType='2.5:ADT_A01'
                 sourceClass='EnsLib.HL7.Message'
                 sourceDocType='Demo.HL7.MsgRouter.Schema:ADT_A01'
                 create='copy' language='objectscript'>
        <foreach property='source.{IN1grp().IN1}' key='iin'>
          <subtransform class='Test.HL7.SegDTLa'
                        targetObj='target.{IN1grp(iin).IN1}'
                        sourceObj='source.{IN1grp(iin).IN1}'/>
        </foreach>
      </transform>
      }
    }
    Copy code to clipboard
  • The following <transform> contains another <subtransform> syntax example. This <transform> combines <foreach> with <if> to find each IN1 segment in the message and transform it.

    Class Test.HL7.A01SegDTLb Extends Ens.DataTransformDTL
    {
    Parameter REPORTERRORS = 1;
    
    XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
      {
      <transform targetClass='EnsLib.HL7.Message'
                 targetDocType='2.5:ADT_A01'
                 sourceClass='EnsLib.HL7.Message'
                 sourceDocType='Demo.HL7.MsgRouter.Schema:ADT_A01'
                 create='copy' language='objectscript'>
        <foreach property='source.{()}' key='i'>
          <assign property='target.{(i):1}' value='i' action='set'/>
          <if condition='target.GetSegmentAt((i)).Name="IN1"'>
            <true>
              <subtransform class='Test.HL7.SegDTLa'
                            targetObj='target.{(i)}'
                            sourceObj='source.GetSegmentAt(i)'/>
            </true>
          </if>
        </foreach>
      </transform>
      }
    }
    Copy code to clipboard