Ensemble XML Virtual Document Development Guide
Defining Data Transformations for XML Virtual Documents
[Home] [Back] [Next]
 InterSystems: The power behind what matters   
Ensemble Interoperability  >  Ensemble XML Virtual Document Development Guide  >  Defining Data Transformations for XML Virtual Documents
Class Reference   
Search:    

This chapter discusses how to create data transformations (specifically DTL-based transformations) for XML virtual documents, for use in rule sets. It discusses the following topics:

Creating a Data Transformation
To create a data transformation for XML virtual documents:
  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:
  4. Create actions within the data transformation as usual, using the XML property paths described in the previous chapter. There are two basic scenarios:
    In either case, you can add code elements to support more complex processing.
After you save and compile the data transformation, it is available for use in a rule set; see the chapter “Defining Rule Sets for XML Virtual Documents.”
Available Assignment Actions for XML Virtual Documents
For XML virtual documents, Ensemble supports the following assignment actions:
Note that insert is not supported.
Using Code
If you need to add code elements to support more complex processing, you directly invoke the GetValueAt() and SetValueAt() methods of the source and target variables. For EnsLib.EDI.XML.Document, these methods are as follows:
GetValueAt()
method GetValueAt(pPropertyPath As %String, 
                  pFormat As %String, 
                  Output pStatus As %Status) as %String
Where:
This method returns the current value at the given property path, or returns an empty string if the path is not valid.
SetValueAt()
method SetValueAt(pValue As %String, 
                  pPropertyPath As %String, 
                  pAction As %String = "set", 
                  pKey As %String = "") as %Status
Where:
This method evaluates the given property path, and (if the path is valid), uses pValue and pAction to modify the value at that path.
Important:
It is useful to check the status values returned by these methods. The status contains specific information when you specify invalid paths or attempt actions that are not permitted. This information is particularly useful when you are debugging and can save you time.
The pFormat Argument
The pFormat argument for GetValueAt() is an optional string that controls the format of the returned string. This string can contain any suitable combination of the characters in the following table:
General Description Character to Include in Format Setting Specific Behavior
Line feeds and carriage returns w Adds a Windows-style carriage return and line feed combination after every text-free element.
r Uses the stored line feeds and carriage returns. This option takes precedence over the options w and n.
n Includes a new line (line feed) after every text-free element. In contrast to w, this option does not add a carriage return.
Indentation. Note that these options are used only if the output includes new lines. i Indents each new line with four spaces.
Any integer from 1 to 9 Indents each new line with this number of spaces. This option takes precedence over the previous indentation option.
t Indents each new line with a tab. This option takes precedence over both of the previous indentation options.
s Uses the stored indentation whitespace. This option takes precedence over the previous indentation options.
Handling attributes a Alphabetizes the attributes in an element.
q Uses double quotes (rather than single quotes) to set off attribute values if possible.
Handling namespaces p Suppresses output of namespace prefixes.
x Suppresses output of namespace declarations.
Handling empty elements e Generates output for each empty element with an open tag and close tag pair. If this option is not set, empty elements are output as a single empty tag.
Other c Canonical output. This option takes precedence over the options e i n t w
f Generates the full element (including both the starting and ending tags), not just the contents within the element.
l Includes information about the location of the schema file that was loaded into Ensemble. This option takes effect only if you use f.
o Includes any XML entities as is, rather than performing XML escaping for those entities.
C(e) Generates an XML header line that declares the given character encoding; e is the non-quoted name of a character encoding such as UTF–8. If e is empty, use the encoding defined by the adapter. If e begins with ! then force the encoding of the output stream. Note that this will be applied automatically for file operations configured with a non-UTF-8 character set.
As noted above, the pFormat argument can equal a combination of these items. For example, if you use the value C(UTF-8)q, the outbound document is in the UTF-8 character set and attributes are set off with double quotes. For another example, if you use the value C(UTF-16)a, the outbound document is in the UTF-16 character set and attributes are alphabetized.
Note:
This information also applies to the Format setting of an XML business operation.
Example 1: Copying Most of the Source Document
To easily define a data transformation that copies most of a source document, do the following in the Data Transformation Builder:
The following shows an example that uses schema-dependent paths:
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;

}
This data transformation copies the source document to the target and then removes the <WorkAddress> and <HomeAddress> elements from the target.
The following shows an equivalent example that uses DOM-style property paths:
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;

}
Notice that in this case, the data transformation does not specify the document types because they are unnecessary here.
Example 2: Using Only a Few Parts of the Source Document
To easily define a data transformation that uses only a few parts of a source document, do the following in the Data Transformation Builder:
The following shows an example that uses schema-dependent paths:
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;

}
This data transformation copies only the MRN and PrimaryCarePhysician properties from the source to the target.
The following shows an equivalent example that uses DOM-style property paths:
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;

}
Example 3: Using Code and SetValueAt()
The following example uses the code action type and uses a DOM-style path. It adds an attribute and an XML comment to the root element: 
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;

}
If the SetValueAt() method returns an error, this transformation uses a utility method to record the details.

[Home] [Back] [Next] [Top of Page] 
Copyright © 1997-2018, InterSystems Corporation
Content for this page loaded from EXML.xml on 2018-10-17 08:05:30