Ensemble XML Virtual Document Development Guide Defining Data Transformations for XML Virtual Documents [Home] [Back] [Next]

• How to define a data transformation
• Details on the behavior of different actions
• Using code
• Example 1: copying most of the source document
• Example 2: using only a few parts of the source document
• Example 3: using code and SetValueAt()

1. Optionally load the applicable XML schema or schemas into Ensemble.
   See “Loading XML Schemas into Ensemble,” earlier in this book.
2. Use the DTL editor in the Management Portal or in Studio, as described in Developing DTL Transformations.
3. Within the data transformation, use the following values:
   • For Source Class and Target Class, use EnsLib.EDI.XML.Document, the class with which Ensemble represents XML virtual documents.
   • For Source Document Type, optionally select the XML type expected in the message. Choose an XML type from one of the XML schemas you have loaded into Ensemble.
     Leave this value blank if you do not have or do not want to use the schema.
   • For Target Document Type, optionally select a different XML type or remove the value.
     Ensemble initializes Target Document Type with the value you select for Source Document Type, if any.
4. Create actions within the data transformation as usual, using the XML property paths described in the previous chapter. There are two basic scenarios:
   • If you have loaded the schemas and have specified the source and target document types, the DTL editor displays each document structure as a tree. Then you can drag and drop to create the transformation. Ensemble creates actions that use schema-dependent paths. You can edit these to use DOM-style paths instead, if those are needed for some reason.
   • If you do not specify the document types, the document structures are not displayed as trees. In this case, it is necessary to add and edit the actions manually. You can use only DOM-style paths.
   In either case, you can add code elements to support more complex processing.

• set — Sets a value. If the type of the target element is "any", then the text can include XML markup. The XML markup must be well formed, but it will not be validated against any schema.
• append — Appends the new value to the target element, after any subnodes in that element.
• clear — Clears the text context of the target but retains the element and any children. Or, if the target is an attribute, the action clears its value but retains the attribute.
• remove — Removes the target element or attribute.

method GetValueAt(pPropertyPath As %String, 
                  pFormat As %String, 
                  Output pStatus As %Status) as %String

• pPropertyPath is an XML property path, as described earlier in this book.
• pFormat is a set of flags that control the format of the returned string. See the following subsection.
• pStatus is a status that indicates success or failure.

method SetValueAt(pValue As %String, 
                  pPropertyPath As %String, 
                  pAction As %String = "set", 
                  pKey As %String = "") as %Status

• pValue is a suitable value for the given XML property path.
• pPropertyPath is an XML property path, as described in the previous chapter.
• pAction is either "set", "append", "clear", or "remove". For details, see the previous section.
• pKey is not used for XML virtual documents.

• On the Transform tab, select copy from the Create drop-down list.
  Then, by default, the new document will be a copy of the original document.
• Define actions that partly or fully remove selected elements or attributes. To define such an action:
  1. In Add Action, click clear or remove.
  2. Double-click the target property that you want to clear or remove.
  3. Enter any value into Value; this field is required but is ignored in this case.

Class Demo02.MyDTL Extends Ens.DataTransformDTL
{

XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document' 
sourceDocType='Demo02:Patient' targetDocType='Demo02:Patient' create='copy' language='objectscript' >
<assign value='"this value is ignored"' property='target.{WorkAddress}' action='remove' />
<assign value='"this value is ignored"' property='target.{HomeAddress}' action='remove' />
</transform>
}

Parameter REPORTERRORS = 1;

}

Class Demo02A.MyDTL Extends Ens.DataTransformDTL
{

XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document' 
create='copy' language='objectscript' >
<assign value='"this value is ignored"' property='target.{/Patient/WorkAddress}' action='remove' />
<assign value='"this value is ignored"' property='target.{/Patient/HomeAddress}' action='remove' />
</transform>
}

Parameter REPORTERRORS = 1;

}

• On the Transform tab, select new from the Create drop-down list.
  Then, by default, the new document will be empty.
• Define actions that copy selected elements or attributes. To define such an action, drag and drop from the source document area to the target document area. Each action that you add this way is a set action.

Class Demo05.MyDTL Extends Ens.DataTransformDTL 
{

XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document' 
sourceDocType='Demo05:Patient' targetDocType='Demo05:Patient' create='new' language='objectscript' >
<assign value='source.{MRN}' property='target.{MRN}' action='set' />
<assign value='source.{PrimaryCarePhysician}' property='target.{PrimaryCarePhysician}' action='set' />
</transform>
}

Parameter REPORTERRORS = 1;

}

Class Demo05A.MyDTL Extends Ens.DataTransformDTL 
{

XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document' 
create='new' language='objectscript' >
<assign value='source.{/Patient/MRN}' property='target.{/Patient/MRN}' action='set' />
<assign value='source.{/Patient/PrimaryCarePhysician}' 
property='target.{/Patient/PrimaryCarePhysician}' action='set' />
</transform>
}

Parameter REPORTERRORS = 1;

}

Class Demo06.MyDTL Extends Ens.DataTransformDTL 
{

XData DTL [ XMLNamespace = "http://www.intersystems.com/dtl" ]
{
<transform sourceClass='EnsLib.EDI.XML.Document' targetClass='EnsLib.EDI.XML.Document' 
create='copy' language='objectscript' >
<code>
<![CDATA[
 //this part adds an attribute to the document
 set path="/1/@NewAttribute"
 set status=target.SetValueAt("New attribute value",path)
 if 'status {do ##class(MyApp.Utils).Trace("Demo06.MyDTL","Error setting path: ",path)}

 //this part adds a comment to the document
 set path="/1/comment()"
 set status=target.SetValueAt("This is an XML comment",path)
 if 'status {do ##class(MyApp.Utils).Trace("Demo06.MyDTL","Error setting path: ",path)}
 ]]>
</code>
</transform>
}

Parameter REPORTERRORS = 1;

}