Ensemble XML Virtual Document Development Guide - InterSystems

Ensemble XML VirtualDocument Development Guide

Version 2012.130 January 2012

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Ensemble XML Virtual Document Development GuideEnsemble Version 2012.1 30 January 2012 Copyright © 2011 InterSystems CorporationAll rights reserved.

This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from the following sources:Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at www.w3c.org.The primary document developmenttools were special-purpose XML-processing applications built by InterSystems using Caché and Java.

, ,

Caché WEBLINK, Distributed Cache Protocol, M/SQL, M/NET, and M/PACT are registered trademarks of InterSystems Corporation.

, , , ,

InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of InterSystems Corporation.

All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations.

This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive,Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystemsCorporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed,transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part,without the express prior written consent of InterSystems Corporation.

The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extentset forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation.InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in suchstandard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arisingout of the use of such software programs is limited in the manner set forth in such standard software license agreement(s).

THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMSCORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATIONREFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION,COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST.

InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole discretionand without notice, to make substitutions and modifications in the products and practices described in this document.

For Support questions about any InterSystems products, contact:

InterSystems Worldwide Customer Support+1 617 621-0700Tel:+1 617 374-9391Fax:[email protected]:

Table of Contents

About This Book .................................................................................................................................... 1

1 Overview .............................................................................................................................................. 31.1 Introduction to XML Virtual Documents ................................................................................... 31.2 XML Schemas and Virtual Document Schemas ........................................................................ 41.3 Message Validation ..................................................................................................................... 41.4 Virtual Properties ........................................................................................................................ 51.5 Searchable Properties ................................................................................................................. 51.6 Additional Notes ......................................................................................................................... 6

2 Configuration Steps ............................................................................................................................ 72.1 Loading XML Schemas into Ensemble ..................................................................................... 72.2 Adding a Business Service to Handle Inbound XML as Virtual Documents ............................. 82.3 Adding a Business Process to Handle XML Virtual Documents ............................................... 92.4 Adding a Business Operation to Handle XML Virtual Documents ......................................... 10

3 Using Property Paths in XML Virtual Documents ........................................................................ 113.1 Orientation to Virtual Property Paths for XML Virtual Documents ......................................... 11

3.1.1 Basic Syntax for Schema-dependent Paths .................................................................... 113.1.2 Basic Syntax for DOM-style Paths ................................................................................ 12

3.2 Viewing Path Units for XML Virtual Documents .................................................................... 123.2.1 Collapsing of Redundant Inner Elements for Schema-dependent Paths ........................ 153.2.2 Renaming of Duplicate Names ...................................................................................... 15

3.3 Specifying Schema-dependent Paths for XML Virtual Documents ......................................... 163.3.1 Getting or Setting the Contents of an XML Element ..................................................... 163.3.2 Getting or Setting the Value of an XML Attribute ......................................................... 173.3.3 Getting or Setting the Text of a Comment ..................................................................... 17

3.4 Specifying DOM-style Paths for XML Virtual Documents ..................................................... 173.4.1 Getting or Setting Nodes (Basic Paths) .......................................................................... 183.4.2 Using the Basic Path Modifiers ...................................................................................... 193.4.3 Using the Full() Function ............................................................................................... 203.4.4 Getting or Setting the Value of an XML Attribute ......................................................... 213.4.5 Using Path Modifiers to Insert or Append Nodes .......................................................... 213.4.6 Using the element() Function ......................................................................................... 233.4.7 Getting Positions of Elements ........................................................................................ 243.4.8 Getting Counts of Elements ........................................................................................... 243.4.9 Accessing Other Metadata ............................................................................................. 253.4.10 Variations for Documents That Use Namespaces ........................................................ 25

4 Defining Data Transformations for XML Virtual Documents ..................................................... 274.1 Creating a Data Transformation ............................................................................................... 274.2 Available Assignment Actions for XML Virtual Documents ................................................... 284.3 Using Code ............................................................................................................................... 28

4.3.1 The pFormat Argument .................................................................................................. 294.4 Example 1: Copying Most of the Source Document ................................................................ 304.5 Example 2: Using Only a Few Parts of the Source Document ................................................. 314.6 Example 3: Using Code and SetValueAt() ............................................................................... 31

5 Defining Rule Sets for XML Virtual Documents ........................................................................... 335.1 Creating a Rule Set ................................................................................................................... 33

Ensemble XML Virtual Document Development Guide iii

5.2 Example .................................................................................................................................... 34

6 Defining Search Tables for XML Virtual Documents ................................................................... 356.1 Overview of Search Table Classes ........................................................................................... 356.2 Defining a Search Table Class for XML Virtual Documents ................................................... 36

Appendix A:Additional Reference ..................................................................................................... 39A.1 Classes to Use .......................................................................................................................... 39A.2 Business Host Settings ............................................................................................................ 40

iv Ensemble XML Virtual Document Development Guide

About This Book

This book is one of a set that describes how to add virtual document interfaces and processing to Ensemble productions.Specifically it describes how to handle XML documents as virtual documents, which provide efficient indexing of onlythe necessary document elements, according to your needs. This book assumes you are acquainted with the basics of XML,but are not necessarily familiar with XML schemas. It also assumes that you are familiar with Ensemble in general, but notnecessarily with virtual documents.

This book contains the following sections:

• Overview

• Configuration Steps

• Using Property Paths in XML Virtual Documents

• Defining Data Transformations for XML Virtual Documents

• Defining Rule Sets for XML Virtual Documents

• Defining Search Tables for XML Virtual Documents

• Additional Reference

There is also a detailed table of contents.

The following books provide related information:

• Ensemble Virtual Documents explains how the concept of virtual documents allows Ensemble to provide efficientsupport for EDI (electronic data interchange) document exchange.

• Developing Ensemble Productions describes Ensemble development practices in detail.

• Ensemble Best Practices describes best practices for organizing and developing Ensemble productions.

Ensemble XML Virtual Document Development Guide 1

1Overview

This chapter provides an overview of XML virtual documents. It discusses the following topics:

• Introduction

• XML schemas and virtual document schema categories

• Message validation

• Virtual properties

• Searchable properties

• Additional notes

1.1 Introduction to XML Virtual DocumentsIn Ensemble, a virtual document is a kind of message that Ensemble parses only partially. This kind of message has thestandard Ensemble message header and the standard message properties such as ID and DocType. The data in the message,however, is not available as message properties; instead it is stored directly in an internal-use global, for greater processingspeed.

An XML virtual document is a virtual document created from an XML document received by an Ensemble production. Thefollowing shows an example, as shown in the Ensemble message trace:


The RawContent property shows a truncated version of the raw data in the message. The Contents tab displays the fullmessage.

1.2 XML Schemas and Virtual Document SchemasWith most kinds of virtual documents, Ensemble must have information about the expected structure of the document. ForXML virtual documents, it is useful, but not required, for Ensemble to have this information.

Ensemble uses the following generic terminology for all EDI formats:

• In most cases, a document type (also called a document structure) corresponds to an expected type of input message.

For an XML virtual document, a document type is an XML type; thus a document type can correspond to either anexpected input message or a child part of an input message.

• A document schema category (also called a schema category) is a collection of related document types.

For an XML virtual document, a document schema category corresponds directly to an XML schema.

The complete document type is the combination of the category and type and is presented as category:type.

The Management Portal and the Ensemble classes for XML virtual documents both use the generic terminology documenttype and document schema category.

1.3 Message ValidationIf the applicable XML schemas are loaded into Ensemble, the system can validate XML virtual documents. It is not possibleto validate the messages unless the applicable schema is available.

4 Ensemble XML Virtual Document Development Guide

Overview

1.4 Virtual PropertiesA data item in a virtual document is called a virtual property. Ensemble provides syntax to specify the location of a virtualproperty; this syntax is called a virtual property path. For XML virtual documents, these paths can have two differentforms:

• Schema-dependent paths refer to the corresponding XML schema. To use these paths, you must have loaded the XMLschema. It is also necessary to specify the schema to use.

• DOM-style paths treat the XML document as an XML DOM (Document Object Model). You can use these whetheror not the schema is loaded. Also, DOM-style paths provide a wider range of options than do schema-dependent paths.

You use virtual property paths in the following locations:

• In data transformations.

• In business rules. A rule set can use property paths in two ways:

– A rule can define a when condition which typically finds a value in the message (in this case an XML virtualdocument), and compares that to another value. If the condition is true, the associated clause is executed. If therule set is used in a business process that receives XML virtual documents, its conditions can use XML virtualproperty paths.

– A rule can assign a value to a property path. If the rule set is used in a business process that receives XML virtualdocuments, you can use an XML virtual property path.

• In definitions of searchable properties (see the next heading)

Also, users can enter virtual property paths in the Management Portal to filter the messages displayed or search for specificmessages. For example:

1.5 Searchable PropertiesFor standard message bodies, each property of the message is directly searchable in the Management Portal. That is, theuser can use the property for searching or filtering without having to know its path.

By default, none of the data in an XML virtual document is directly searchable in the Management Portal. That is, a usermust know the property path for a data item in order to use that item for searching or filtering.

To assist the user, you can define searchable properties as follows:

• You define a search table class; this class uses virtual property paths to define the searchable properties.

• You configure the applicable business hosts to use the search table class.


Virtual Properties

As the business host receives messages, Ensemble indexes these properties as if they were properties in a standardmessage body.

Users can then use these properties directly without having to know the property paths that they use. For example:

1.6 Additional Notes• When reading XML documents, Ensemble removes the XML declaration, all processing instructions, and all comments.

• If the name of an element or attribute includes a period (.), Ensemble replaces that with a tilde (~).

For example, an XML element named My.Element appears as My~Element in Ensemble.


Overview

2Configuration Steps

This chapter describes the configuration steps needed to use XML virtual documents in a production. It discusses the fol-lowing topics:

• How to load XML schemas into Ensemble

• How to configure a business service to handle inbound XML as virtual documents

• How to configure a business process to route XML virtual documents

• How to configure a business operation to handle XML virtual documents

For information on settings not described here, see “Business Host Settings” in the appendix “Additional Reference.”

Later chapters describe how to create items to use in the production: data transformations, rule sets, and search tables.

2.1 Loading XML Schemas into EnsembleFor XML virtual documents, it is useful, but not required, to load the corresponding XML schemas into Ensemble. If theschemas are available in Ensemble, then Ensemble can validate the documents, and you can use the schema-dependentvirtual property paths (rather than only the DOM-style paths). Also, the DTL editor and the Business Rule Editor provideassistance with the document structure.

To load an XML schema into Ensemble, do the following:

1. Rename the schema file so that its name is informative and unique within this Ensemble namespace. The filename isused as the schema category name in the Management Portal and elsewhere.

If the filename ends with the file extension .xsd, the file extension is omitted from the schema category name. Otherwisethe file extension is included in the name.

2. In the Management Portal, switch to the appropriate namespace.

To do so, click Switch in the title bar, click the namespace, and click OK.

3. Click Ensemble.

4. Click Interoperate.

5. Click XML.

6. Click XML Schema Structures and then click Go.

Ensemble displays the [Ensemble] > [XML Schemas] page.


7. For Choose Action, click Import Schema from File.

8. Specify the file to load. To do so, either type a path and filename or click Browse... and navigate to a file.

You can specify a complete path or a relative path. In the latter case, the path is relative to the System Manager’sdirectory.

9. Click OK.

If the schema was already loaded, Ensemble overwrites it with the current contents of the file.

The schema is loaded into Ensemble is available to all productions in this namespace. This page lists the XML schemas(displayed as document schema categories):

Note: You can use these schemas only to support processing of XML virtual documents as described in this book.

You can also load schemas programmatically by using the EnsLib.EDI.XML.SchemaXSD class directly. This class providesthe Import() class method. The first argument to this method is the name of the file to import, including its full directorypath. For example:

set status= ##class(EnsLib.EDI.XML.SchemaXSD).Import("c:\ENSEMBLE\myapp.xsd")

The EnsLib.EDI.XML.SchemaXSD class also provides the ImportFiles() method. For this method, you can specify the firstargument in either of the following ways:

• As the name of a directory to import files from. Ensemble attempts to import all files in this directory, regardless ofthe file extensions. For example:

set status=##class(EnsLib.EDI.XML.SchemaXSD).ImportFiles("c:\ENSEMBLE\")

• As a list of filenames, separated by semicolons. You must include the full directory path for the first of these, and youcan use wildcards in the filenames. For example:

set status=##class(EnsLib.EDI.XML.SchemaXSD).ImportFiles("c:\ENSEMBLE\*.xsd;*.XSD")

For more information, see the class reference for EnsLib.EDI.XML.SchemaXSD.

2.2 Adding a Business Service to Handle Inbound XMLas Virtual DocumentsTo add a business service to handle inbound XML documents as Ensemble virtual documents, do the following:


Configuration Steps

1. To your production, add a business service that is based on the class EnsLib.EDI.XML.Service.FileService.

2. Specify where this business service will find the inbound XML documents. To do so, specify the FilePath setting,which is the directory that the business service will check for new files.

3. Optionally specify other settings as needed. In particular, you might want to specify the following:

• FileSpec, which specifies the form of filenames to use. The default is * and this causes the service to process allfiles in the given directory.

• DocSchemaCategory, which specifies the XML schema that applies to the inbound documents. Select a XMLschema that you have previously loaded.

You must choose a schema if you want to validate the messages. The schema can also be used if you definesearchable properties.

• Charset, which specifies the character set to use to translate characters in the inbound files. The default is thedefault character encoding of the local Ensemble server. For more options, see the entry for Charset in “AdditionalReference.”

• SearchTableClass. See the chapter “Defining Search Tables for XML Virtual Documents.”

Make sure that this search table class is consistent with the kinds of messages received by this business host. Forexample, if the business host receives messages whose root element is <Transaction>, it would not be appro-priate to use a search table class that defined searchable properties in an <Employee> element.

4. Specify where to send the XML documents. To do so, specify a comma-separated list of values for the TargetConfigNames

setting. Each value should be the name of either a business process or a business operation.

Important: In this release, the prolog (if included) of the XML documents must not include the encoding attribute.That is, the prolog must look like this:

<?xml version="1.0" ?>

In contrast, this is not currently supported:

<?xml version="1.0" encoding="UTF-8"?>

If the XML files are not encoded with the same character set that is the default character encoding of thelocal Ensemble server, specify the Charset setting of the business service that will process them.

2.3 Adding a Business Process to Handle XML VirtualDocumentsTo add a business process to handle XML virtual documents, do the following:

1. To your production, add a business process that is based on the class EnsLib.MsgRouter.VDocRoutingEngine.

2. For this business process, specify the BusinessRuleName setting. Choose the appropriate business rule set that acts onXML virtual documents.

For information on defining these, see the chapter “Defining Rule Sets for XML Virtual Documents.”

3. Optionally specify other settings as needed.


Adding a Business Process to Handle XML Virtual Documents

4. Configure the appropriate business host or hosts in the same production to send XML virtual documents to this businessprocess:

• For a business service, edit the TargetConfigNames setting to include the name of this business process.

• For a business process, specify a BusinessRuleName that routes messages to this business process.

2.4 Adding a Business Operation to Handle XML VirtualDocumentsTo add a business operation to send XML virtual documents to destinations outside of an Ensemble production, do thefollowing:

1. To your production, add a business operation that is based on the class EnsLib.EDI.XML.Operation.FileOperation.

2. Specify the FilePath setting, which is the directory to which the business operation will write the files. The directorymust exist and must be accessible.

3. Optionally specify the SearchTableClass setting. See the chapter “Defining Search Tables for XML Virtual Documents.”

Make sure that this search table class is consistent with the kinds of messages received by this business host. Forexample, if the business host receives messages whose root element is <Transaction>, it would not be appropriateto use a search table class that defined searchable properties in an <Employee> element.

4. Configure the appropriate business host or hosts in the same production to send XML virtual documents to this businessoperation:

• For a business service, edit the TargetConfigNames setting to include the name of this business operation.

• For a business process, specify a BusinessRuleName that routes messages to this business operation.


Configuration Steps

3Using Property Paths in XML VirtualDocuments

This chapter describes how to use property paths in XML virtual documents. It discusses the following:

• Orientation to virtual property paths for XML documents

• How to view property path units for an XML schema

• How to specify schema-dependent paths

• How to specify DOM-style paths

Later chapters describe how to create items that use these property paths: data transformations, rule sets, and search tables.

Note: The code examples in this chapter are fragments from data transformations, because data transformations generallyuse a richer set of property paths than do rule sets and search tables. Also, the emphasis is on DOM-style paths,because those are the paths that you must create manually. (In contrast, when you specify a schema to use,Ensemble displays the structure of the document and automatically generates schema-dependent paths when youdrag and drop or when you use auto-completion.)

3.1 Orientation to Virtual Property Paths for XML VirtualDocumentsThis section briefly introduces virtual property paths for XML virtual documents.

As noted earlier, you can use schema-dependent paths only if you have loaded the corresponding XML schema. You canalways use DOM-style paths, even when no schema is available.

3.1.1 Basic Syntax for Schema-dependent Paths

For XML virtual documents, a schema-dependent path consists of a set of path units separated by periods, as in the followingexample:

unit1.unit2.unit3


Where unit1 represents a child XML element in the document, unit2 represents a child element within unit1, and so on.The leaf unit can represent either a child XML element or an XML attribute.

Each path unit is the name of an element or attribute.

For example:

HomeAddress.City

3.1.2 Basic Syntax for DOM-style Paths

A DOM-style path always starts with a slash and has the basic structure shown in the following example:

/root_unit/unit1/unit2/unit3

Each path unit has the following form.

namespace_identifier:name

Where namespace_identifier represents the XML namespace; this is a token that Ensemble replaces with the actualnamespace URI, as discussed in a later subsection. This token is needed only if the element or attribute is in a namespace,as you will see later in this chapter.

name is the name of an XML element or attribute.

For example:

/$2:Patient/$2:HomeAddress/$2:City

3.1.2.1 XML Namespace Tokens

When you load a schema into Ensemble, Ensemble establishes a set of tokens for the namespaces used in that schema, foruse in any DOM-style paths.

The token $1 is used for first namespace that is declared in the schema; this usually corresponds to the XML schemanamespace (http://www.w3.org/2001/XMLSchema). The token $2 is used for the next namespace that is declaredin the schema, $3 is used for the third, and so on.

Ensemble assigns namespace tokens for all namespaces declared in the schema, whether or not those namespaces areactually used. Therefore, Ensemble might use $3 or a higher value rather than $2 for the items of interest to you, if additionalnamespaces are declared in the schema. It is practical to use the Management Portal to view the individual path units, asdiscussed in the next topic, to be sure that you are using the correct token for a specific path unit.

You can use namespace tokens if you have also loaded the corresponding schema (and have configured the applicablebusiness host to use that schema). Otherwise, you must use the namespace prefixes exactly as given in the XML document.

Note: These namespace tokens are a preliminary and temporary implementation of namespace handling that will bechanged. This means that any data transformations and other items that use them will have to be modified in afuture release.

3.2 Viewing Path Units for XML Virtual DocumentsUntil you are familiar with property paths for XML virtual documents, it is useful to use the Management Portal to viewthe individual path units. You can do this if you have loaded the corresponding schema.

To view the path units for the elements and attributes in a schema:


Using Property Paths in XML Virtual Documents

1. Load the schema as described in the previous chapter.

For example, consider the following XML schema, shown here for reference, for the benefit of readers who arefamiliar with XML schemas:

<?xml version="1.0" ?><s01:schema xmlns:s01="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="www://http.myapp.com"> <s01:complexType name="Patient"> <s01:sequence> <s01:element minOccurs="0" name="Name" type="s01:string"/> <s01:element minOccurs="0" name="Gender" type="s01:string"/> <s01:element minOccurs="0" name="BirthDate" type="s01:date"/> <s01:element minOccurs="0" name="HomeAddress" type="s02:Address" xmlns:s02="www://http.myapp.com"/> <s01:element minOccurs="0" name="FavoriteColors" type="s03:ArrayOfFavoriteColorsItemString" xmlns:s03="www://http.myapp.com"/> <s01:element minOccurs="0" name="Container" type="s04:Container" xmlns:s04="www://http.myapp.com"/> </s01:sequence> <s01:attribute name="MRN" type="s01:string"/> </s01:complexType> <s01:complexType name="Address"> <s01:sequence> <s01:element minOccurs="0" name="StreetAddress" type="s01:string"/> <s01:element minOccurs="0" name="City" type="s01:string"/> <s01:element minOccurs="0" name="State" type="s01:string"/> <s01:element minOccurs="0" name="ZIP" type="s01:string"/> </s01:sequence> </s01:complexType> <s01:complexType name="ArrayOfFavoriteColorsItemString"> <s01:sequence> <s01:element maxOccurs="unbounded" minOccurs="0" name="FavoriteColorsItem" nillable="true" type="s01:string"/> </s01:sequence> </s01:complexType> <s01:complexType name="Container"> <s01:sequence> <s01:element minOccurs="0" name="ChildProperty" type="s05:ChildObject" xmlns:s05="www://http.myapp.com"/> </s01:sequence> </s01:complexType> <s01:complexType name="ChildObject"> <s01:sequence> <s01:element minOccurs="0" name="ChildProperty" type="s01:string"/> </s01:sequence> </s01:complexType></s01:schema>

2. Display the [Ensemble] > [XML Schemas] page. The left column lists XML schemas loaded into this Ensemblenamespace.

3. Click the Document Structures / Document Types link in the row corresponding to the XML schema of interest.

If we do this for the XML schema shown previously, Ensemble then displays this:

4. Click the link for the document type of interest.

If we click Patient, Ensemble then displays this:


Viewing Path Units for XML Virtual Documents

The Name column shows path units in the format needed for schema-dependent paths. In this case, this page tells usthat we can use $2:Name, $2:Gender, $2:BirthDate, $2:HomeAddress, $2:FavoriteColors(),$2:Container, and MRN as path units in schema-dependent paths.

The Element column shows path units in the format needed for DOM-style property paths. In this case, this page tellsus that we can use $2:Name, $2:Gender, $2:BirthDate, $2:HomeAddress,$2:FavoriteColors/$2:FavoriteColorsItem,$2:Container/$2:ChildProperty/$2:ChildProperty, and @MRN as path units in DOM-style paths. Noticethat MRN does not have a namespace prefix; this attribute is not in any namespace.

5. Click additional sub-items as wanted.

If we click Address, Ensemble displays this:

This page displays any additional path units within $2:HomeAddress.

In this case, this page tells us that we can use $2:StreetAddress, $2:City, $2:State, $2:ZIP as path units incombination with the path unit $2:HomeAddress.



3.2.1 Collapsing of Redundant Inner Elements for Schema-dependent Paths

The following shows an example XML document that obeys the schema shown in this section:

<?xml version="1.0" ?><s01:Patient xmlns:s01="www://http.myapp.com" MRN="987654321"> <s01:Name>Lucy Jenkins</s01:Name> <s01:Gender>F</s01:Gender> <s01:BirthDate>1949-03-21</s01:BirthDate> <s01:HomeAddress> <City>Jonestown</City> </s01:HomeAddress> <s01:FavoriteColors> <s01:FavoriteColorsItem>Red</s01:FavoriteColorsItem> <s01:FavoriteColorsItem>Orange</s01:FavoriteColorsItem> <s01:FavoriteColorsItem>Pink</s01:FavoriteColorsItem> </s01:FavoriteColors> <s01:Container> <ChildProperty> <ChildProperty>sample value</ChildProperty> </ChildProperty> </s01:Container></s01:Patient>

Note the following items:

• <FavoriteColors> contains a sequence of multiple <FavoriteColorsItem> elements. On the schema viewerpage, the <FavoriteColors> item is shown simply as $2:FavoriteColors() in the Name column (which showsthe path unit for schema-dependent paths).

In contrast, the same item is shown as $2:FavoriteColors/$2:FavoriteColorsItem in the Element column(which shows the path unit for DOM-style paths).

For a sequence of multiple items of the same type, the schema-dependent path does not use the name of the inner element.(In contrast, the DOM-style path uses all the element names.) More generally, any redundant inner levels found in aschema are ignored in schema-dependent paths; the following item shows another example.

• <Container> includes a single <ChildProperty> element, which includes a single <ChildProperty> element.On the schema viewer page, the <Container> item is shown as $2:Container in the Name column. The schema-dependent path to the data inside <Container> does not use the name of either inner element.

In contrast, the same item is shown as $2:Container/$2:ChildProperty/$2:ChildProperty in the Element

column (which shows the path unit for DOM-style paths).

3.2.2 Renaming of Duplicate Names

If an XML schema has multiple elements at the same level that have the same name but different types, then Ensembleappends _2, _3, and so on, as needed to create unique names at that level. This procedure applies only to the schema-dependent paths. For example, consider a schema that defines the <Person> element to include two elements named<Contact>. One is of type <Phone> and the other is of type <Assistant>. Ensemble displays the schema for the<Person> element as follows:


Viewing Path Units for XML Virtual Documents

Similarly, if the schema has multiple elements at the same level but in different namespaces, then Ensemble appends _2,_3, and so on, as needed to create unique names at that level. This procedure applies only to the schema-dependent paths.

3.3 Specifying Schema-dependent Paths for XML VirtualDocumentsThis section describes how to specify schema-dependent paths for XML virtual documents. It discusses the following:

• How to access contents of an element

• How to access the value of an attribute

• How to access comments

You can use these paths to access values and to set values.

3.3.1 Getting or Setting the Contents of an XML Element

To access the contents of an element, you can use one of the following schema-dependent paths. You also use these pathswhen you create more complex schema-dependent paths as discussed in later subsections.

Refers toSyntax

Contents of the given element. element_name must be a child of the rootelement.

element_name

Contents of the given element. parent is the full path to an element — that is,any syntax shown in this table. In this case, element_name is a child of theelement referred to by parent.

parent.element_name

Contents of the nth element with the name element_name within the givenparent.

parent.element_name(n)

Contents of the last element with the name element_name within the givenparent.

parent.element_name(-)

Consider the following XML document:

<?xml version="1.0" ?><Patient MRN="000111222"> <Name>John Doe</Name> <HomeAddress> <StreetAddress>17 Winding Way</StreetAddress> <City>Dashville</City> <State>OH</State> <ZIP>53790</ZIP> </HomeAddress></Patient>

The following table shows some example paths for this document:

Current Path ValueExample Path

John DoeName

DashvilleHomeAddress.City

000111222MRN



3.3.2 Getting or Setting the Value of an XML Attribute

To access the value of an attribute, you can use one of the following schema-dependent paths. Here (and in the rest of thissection), element_reference is a complete schema-dependent path as described in the previous table.

Refers toSyntax

Value of the attribute_name attribute of the element indicated byelement_reference.

element_reference.attribute_name

3.3.3 Getting or Setting the Text of a Comment

To access a comment, you can use one of the following schema-dependent paths:

Refers toSyntax

Text of the first comment of the given element.element_reference.#

Text of the nth comment of the given element.element_reference.#(n)

Text of the last comment.element_reference.#(-)

Note: Ensemble removes all comments when it reads in XML files. The only comments that can be present are commentsthat you add.

3.4 Specifying DOM-style Paths for XML VirtualDocumentsThis section describes how to specify DOM-style paths for XML virtual documents. It discusses the following:

• How to get or set a document node (basic paths)

• How to use basic path modifiers

• How to use the full() function

• How to get or set the value of an attribute

• How to insert or append nodes

• How to use the element() function

• How to get positions of elements

• How to count items

• How to get other metadata

• How to modify a path to consider namespaces

You can use these paths to access values and to set values (with noted exceptions).

Most of the following subsections assume that the document does not use any XML namespaces. The last subsection givesinformation on adapting these paths for a document that does use XML namespaces.


Specifying DOM-style Paths for XML Virtual Documents

3.4.1 Getting or Setting Nodes (Basic Paths)

In an XML virtual document, there are five kinds of nodes: the root node, elements, text nodes, comments, and processinginstructions. The root node and any element can have child nodes of any type. The other kinds of nodes cannot have childnodes. Attributes are not nodes.

The following table lists basic DOM-style paths to get or set many of the nodes of an XML virtual document. When thereare multiple nodes of the same type or with the same name, and when you do not want the first one, see the next subsection.

You also use these paths when you create more complex DOM-style paths as discussed in later subsections.

Refers toSyntax

Contents of the root node.You can also use "", if the context makesit clear that you are using a DOM-style path (that is, if no schema isloaded).

/

Contents of the root element, whose name is root_element_name./root_element_name

Contents of the first element of the given name (element_name),within the given parent. Here parent is the full path to its parentelement, including (as always) the initial slash.

parent/element_name

First text node in the element indicated by element_reference.element_reference/text()

First comment in the element indicated by element_reference.

The value returned does not include the opening syntax (). Similarly, do not include the opening orclosing syntax when setting the value.

Ensemble removes all comments when it reads in XML files. Theonly comments that can be present are comments that you add.

element_reference/comment()

First processing instruction in the element indicated byelement_reference.

The value returned does not include the opening syntax (<?) or theclosing syntax (?>). Similarly, do not include the opening or closingsyntax when setting the value.

Ensemble removes all processing instructions when it reads in XMLfiles. The only instructions that can be present are instructions thatyou add.

element_reference/instruction()


<?xml version="1.0" ?><Patient> Sample text node   <Name>Fred Williams</Name> <Address> <Street>15 Main Street</Street> </Address></Patient>





Fred Williams/Patient/Name

<Street>15 Main Street</Street>

In this case, the referenced element contains a child element (in contrast tothe previous example). Note that Ensemble ignores whitespace when com-paring DOM-style paths to values.That is, the value here matches the givenpath whether or not the document contains line breaks and indentation.

/Patient/Address

Sample text node/Patient/text()

Sample comment/Patient/comment()

Suppose that we now use a data transformation that contains only the following code:

set status=target.SetValueAt("892 Broadway","/Patient/Address") if 'status {do $system.Status.DisplayError(status) quit} set status=target.SetValueAt("Dr. Badge","/Patient/Doctor/Name") if 'status {do $system.Status.DisplayError(status) quit}

Notice that one of these paths exists already and the other does not; both paths are valid. After we use this transformation,the new document would then look like the following:

<Patient>Sample text node   <Name>Fred Williams</Name> <Address>892 Broadway</Address> <Doctor> <Name>Dr. Badge</Name> </Doctor></Patient>

3.4.2 Using the Basic Path Modifiers

You can add the following basic path modifiers to the end of basic paths (listed in the previous subsection), with notedexceptions. You can use the resulting paths in the same way that you use any of the basic paths.

[n]

Refers to an item by item position. Only instances of that item are counted; items of other types are ignored.

• When you get a value, this syntax returns the nth instance of the item to which the basic path refers (or anempty string otherwise).

• When you set a value, this syntax either overwrites or creates the nth instance of the item to which the basicpath refers.

You can substitute a hyphen (-) to access the last instance. You can also omit the square brackets.

/[n]

Refers to a child element by child element position.

You can substitute a hyphen (-) to access the last child. You can also omit the square brackets.

You can use this only with a basic path that refers to an element. Also, you can use this syntax only when gettinga value.

You can combine these path modifiers, as long as you use the /[n] modifier after the other modifier.

Different path modifiers, listed in a later subsection, enable you to insert or append nodes.




<?xml version="1.0" ?><Patient>   <Name>Fred Williams</Name> <Address>15 Main Street</Address> <Address>777 Myrtle Lane</Address></Patient>


NotesCurrent Path ValueExample Path

Fred Williams/Patient/Name

For these paths, the square brackets are required.Address1 and Address2 would be interpreted aselement names.

15 Main Street/Patient/Address[1]

777 Myrtle Lane/Patient/Address[2]

This path accesses the first child element within thefirst element of the document (which is the onlyelement in the document, according to the XMLstandard). The square brackets are optional here.

Fred Williams/[1]/[1]

This path accesses the first address element withinthe first element of the document.

15 Main Street/1/Address[1]

This path accesses the second element of any namewithin the first element of the document.

15 Main Street/1/2

777 Myrtle Lane/Patient/3

an empty string/Patient/4

777 Myrtle Lane/Patient/-

For these paths, the square brackets are required,because without square brackets, these paths wouldbe interpreted as element names.

Sample comment/Patient/comment()[1]

Another comment/Patient/comment()[2]

Another comment/Patient/comment()[-]

3.4.3 Using the Full() Function

For a path that refers to an element (either a basic path or a path that uses basic modifiers), you can also obtain the openingand closing tags of the element. To do so, add full() to the end of the path.

You can use the full() function when you are setting a value, but only within a data transformation that uses the append

action; see “Assignment Actions for XML Virtual Documents,” in the next chapter.


<?xml version="1.0" ?><Patient> <Name>Fred Williams</Name> <Address> <Street>15 Main Street</Street> </Address></Patient>





<Name>John Doe</Name>/Patient/Name/full()

<Address><Street>15 Main Street</Street></Address>/Patient/Address/full()

<Street>15 Main Street</Street>/Patient/Address/Street/full()

For the root note, use of the full() function is implied. That is, the following two paths are equivalent:

//full()

3.4.4 Getting or Setting the Value of an XML Attribute

To access the value of an attribute, you can use one of the following DOM-style paths. Here (and in the rest of this section),element_reference is a complete DOM-style path to an element.

Refers toSyntax

Value of the given attribute of the given element.element_reference/@attribute_name

(For use only when retrieving values) Value of the nth attribute (inalphabetical order) of the given element.

element_reference/@[n]

Value of the last attribute of the given element.element_reference/@[-]

You can omit the square brackets.

For example, consider the following XML document:

<Patient MRN='123456789' DL='000-00-0000'> <Name>Fred Williams</Name> <Address>15 Main Street</Address></Patient>



123456789/Patient/@MRN

123456789/Patient/@[1]

000-00-0000/Patient/@2

3.4.5 Using Path Modifiers to Insert or Append Nodes

To insert or append nodes, add the following path modifiers to the end of basic paths. Use the path modifiers listed hereonly when you are setting a value.

Also see the next subsection for a couple of additional options.

[~n]

Inserts an instance of the item to which the basic path refers, right before the nth instance of that item, in the givencontext. Nothing is overwritten. See the following table for details.

Here and in the rest of this subsection, n is an integer.



BehaviorExample Path

Inserts a new <Episode> element within <Patient>,before the existing fifth <Episode> element.

If <Patient> does not include five <Episode> elements,Ensemble performs padding; it creates empty <Episode>elements so that the inserted <Episode> is the fifth<Episode>. All the newly inserted elements are at theend of the <Patient> element.

If the path refers to intermediate, nonexistent elements,Ensemble creates those.

/Patient/Episode[~5]

Inserts an <Episode> element within <Patient>, beforethe existing fifth element.

If <Patient> does not include five elements (of any type),this path is invalid. The element() function does not gen-erate empty elements for padding.

/Patient/element(Episode)[~5]

Not allowed, because there is no information about thekind of element to insert.

/Patient/[~5]

/Patient/element()[~5]

For example, consider the following XML document:

<Patient> <Name>Fred Williams</Name> <Address>15 Main Street</Address></Patient>

Also considering the following code from within a data transformation:

set status=target.SetValueAt("INSERTED ADDRESS","/Patient/Address[~2]") if 'status {do $system.Status.DisplayError(status) quit}

This line of code transforms the original document into the following:

<Patient> <Name>Fred Williams</Name> <Address>15 Main Street</Address> <Address>INSERTED ADDRESS</Address></Patient>

For another example, consider the following XML document:

<Patient> <Name>Fred Williams</Name></Patient>

Also considering the following code from within a data transformation:

set status=target.SetValueAt("orthopedics","/Patient/Doctor/Specialty[~2]") if 'status {do $system.Status.DisplayError(status) quit}

This line of code transforms the original document into the following:

<Patient> <Name>Fred Williams</Name> <Doctor> <Specialty/> <Specialty>orthopedics</Specialty> </Doctor></Patient>



[~$n]

Inserts an instance of the item to which the basic path refers, right before the nth node in the given parent. Nothingis overwritten. The path is invalid if the parent does not contain at least n nodes.


Inserts a new <Episode> element within <Patient>,before the existing third node in that parent. The path isinvalid if the parent does not have three nodes.

/Patient/Episode[~$3]

Not allowed. The element() function works only withelement positions.

/Patient/element(Episode)[~$3]

Not allowed, because there is no information about thekind of element to insert.

/Patient/[~3]

Not allowed for multiple reasons; see above items./Patient/element()[~3]

[~]

Appends an instance of the item to which the basic path refers, as the (new) last node of the given parent. Nothingis overwritten.


Appends a new <Episode> element within <Patient>,as the last node in that parent. If the path refers tointermediate, nonexistent elements, Ensemble createsthose.

/Patient/Episode[~]

Appends an <Episode> element within <Patient>, asthe last node in that parent. If the path refers tointermediate, nonexistent elements, the path is invalid.

/Patient/element(Episode)[~]

Not allowed, because there is no information about thekind of element to append.

/Patient/[~]

/Patient/element()[~]

For example, the following shows part of a code element in a data transformation:

set status=target.SetValueAt("orange","/Patient/FavoriteColors/Color[~]") if 'status {do $system.Status.DisplayError(status) quit} set status=SetValueAt("pink","/Patient/FavoriteColors/Color[~]") if 'status {do $system.Status.DisplayError(status) quit}

This adds two new <Color> children to the <FavoriteColors> element. If the <FavoriteColors> elementdoes not exist, Ensemble creates it.

3.4.6 Using the element() Function

You can use the element() function when getting or setting values, as described in the following table:



BehaviorWhen AllowedSyntax

Returns the first child element ofthe given element.

When getting avalue

element_reference/element()

Returns the nth child element ofthe given element.

element_reference/element()[n]

Returns the last child element ofthe given element.

element_reference/element()[-]

Inserts the specified element(given by the element_nameargument) right before the nth childelement of the given parent. Thispath is invalid if the given elementdoes not have at least n childelements.

When setting avalue

parent_element/element(element_name)[~n]

Appends the specified element(given by the element_nameargument) as the last node in thegiven parent.

parent_element/element(element_name)[~]

3.4.7 Getting Positions of Elements

You can use the following syntaxes to get positions of elements.

ReturnsSyntax

Element position of the given element within its parent.element_reference/position()

Node position of the given element within its parent. For nodeposition, Ensemble considers all kinds of nodes, not justelements.

element_reference/node-position()

3.4.8 Getting Counts of Elements

You can use the following syntaxes to get counts of elements.

ReturnsSyntax

Count of child elements within the given parent.• element_reference/[*]

• element_reference/count()

Count of elements of the given name, within the given parent.Notice that there is no slash after the name of the element (incontrast with the previous set of paths).

• parent/element_name[*]

• parent/element_name.count()

Count of child nodes of the given element.• element_reference/[$*]

• element_reference/node-count()



ReturnsSyntax

Count of attributes of the given element.• element_reference/@[*]

• element_reference/@.count()

You can omit the square brackets in all cases except for /[*]. Note that Ensemble also supports the last() function(equivalent to count()) and the node-last() function (equivalent to node-count()); you might prefer to use last() andnode-last() if you are familiar with XPATH, which has a similar last() function.

3.4.9 Accessing Other Metadata

You can use the following functions to access other metadata of the XML virtual document. You can use these functionsonly at the end of a path.

ReturnsFunction

Type of the given node. This function returns one of the following values:

• root

• element

• text

• comment

• instruction

/node-type()

Full name of the given node. For example: s01:Patient/name()

Local name of the given node. For example: Patient/local-name()

Namespace prefix of the given node. For example: s01/prefix()

URI of the namespace to which the given node belongs. For example:www.myapp.org

/namespace-uri()

All the namespace prefixes and their corresponding URIs, in the scope of the givenelement. This information is returned as a comma-separated list. Each list itemconsists of the namespace prefix, followed by an equal signs (=), followed by theURI. The default namespace URI is listed first without a prefix. For example:=http://tempuri.org,s01=http://myns.com

/prefixes()

3.4.10 Variations for Documents That Use Namespaces

If the document uses XML namespaces, for each element or attribute that is in a namespace, you must modify that sectionof the path to include a namespace prefix, followed by colon (:). A namespace prefix is one of the following:

• If you have loaded the corresponding XML schema, use a namespace token as described in “XML Namespace Tokens,”earlier in this chapter. For example: use $2:element_name rather than element_name

• If you have not loaded the XML schema, use the namespace prefix exactly as it appears in the document. For example:s01:Patient

• Use the wildcard * to ignore the namespace. For example: *:Patient

Another option is to ignore all namespaces in the document. To do this, start the path with the wildcard *:/ rather than /



For example: *:/Patient/@MRN

You cannot use any wildcards in a path when you are setting the value for that path.

Note: These namespace tokens are a preliminary and temporary implementation of namespace handling that will bechanged. This means that any data transformations and other items that use them will have to be modified in afuture release.



4Defining Data Transformations for XMLVirtual Documents

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

• 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()

4.1 Creating a Data TransformationTo 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” inDeveloping Ensemble Productions.

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 XMLvirtual documents.

• For Source Document Type, optionally select the XML type expected in the message. Choose an XML type fromone 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 displayseach document structure as a tree. Then you can drag and drop to create the transformation. Ensemble createsactions that use schema-dependent paths. You can edit these to use DOM-style paths instead, if those are neededfor some reason.

• If you do not specify the document types, the document structures are not displayed as trees. In this case, it isnecessary 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.

After you save and compile the data transformation, it is available for use in a rule set; see the chapter “Defining Rule Setsfor XML Virtual Documents.”

4.2 Available Assignment Actions for XML VirtualDocumentsFor XML virtual documents, Ensemble supports the following assignment actions:

• set — Sets a value. If the type of the target element is "any", then the text can include XML markup. The XMLmarkup 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.

Note that insert is not supported.

4.3 Using CodeIf you need to add code elements to support more complex processing, you directly invoke the GetValueAt() andSetValueAt() 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:

• 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.

This method returns the current value at the given property path, or returns an empty string if the path is not valid.


Defining Data Transformations for XML Virtual Documents

SetValueAt()

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

Where:

• 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.

This method evaluates the given property path, and (if the path is valid), uses pValue and pAction to modify thevalue at that path.

Important: It is useful to check the status values returned by these methods. The status contains specific informationwhen you specify invalid paths or attempt actions that are not permitted. This information is particularlyuseful when you are debugging and can save you time.

4.3.1 The pFormat Argument

The pFormat argument for GetValueAt() is a string that forms a set of flags that control the format of the returned string.This string can contain any combination of the following characters:

MeaningCharacter

Use this number of spaces for Indentation in the returned string.1–9

Place attributes in alphabetical order in the element that contains them.a

Use canonical form. If you include this flag in pFormat, the flags e, i, n, t, and w are all ignored.c

Use both opening and closing tags, even for empty elements.e

Include the opening and closing tags of the requested element (rather than just the contentsof the element).

f

Indent with 4 spaces. This option is ignored if unless pFormat includes the flag i or 1-9.i

Include a newline after every text-free element.n

Use double quotes to set off attribute values if possible.q

Use stored returns or newlines. If you include this flag in pFormat, the flags n and w are ignored.r

Use stored indentation whitespace. If you include this flag in pFormat, the flags i, t, and 1-9are ignored.

s

Indent with a tab. If you include this flag in pFormat, the flags 1-9 are ignored.t

Use a Windows-style carriage return and newline after every text-free element.w

Do not include namespaces in the output.x


Using Code

4.4 Example 1: Copying Most of the Source DocumentTo easily define a data transformation that copies most of a source document, do the following in the Data TransformationBuilder:

• 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.

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>}


}

Notice that in this case, the data transformation does not specify the document types because they are unnecessary here.



4.5 Example 2: Using Only a Few Parts of the SourceDocumentTo easily define a data transformation that uses only a few parts of a source document, do the following in the DataTransformation Builder:

• 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 doc-ument area to the target document area. Each action that you add this way is a set action.

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>}


}

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>}


}

4.6 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 commentto 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>


Example 2: Using Only a Few Parts of the Source Document

<![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>}


}

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



5Defining Rule Sets for XML VirtualDocuments

This chapter discusses how to create rule sets for XML virtual documents, for use in business processes. It discusses thefollowing topics:

• How to create a rule set

• Example

To configure a business process to use a rule set, specify its BusinessRuleName setting; see “Adding a Business Processto Handle XML Virtual Documents,” earlier in this book.

5.1 Creating a Rule SetTo create a rule set 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 Rule Set editor in the Management Portal or in Studio, as described in Using Business Rules with Ensemble.

3. For the rule set basic definition, use Virtual Document Message Routing Rule for Type.

This choice sets Context Class to EnsLib.MsgRouter.VDocRoutingEngine. It also sets Rule Assist Class toEnsLib.MsgRouter.VDocRuleAssist.

4. For any rule constraint in the rule set, use the following values:

• For Message Class, use EnsLib.EDI.XML.Document, the class with which Ensemble represents XML virtual docu-ments.

• For Schema Category, optionally select an XML schema that you have previously loaded into Ensemble.

Leave this value blank if you do not have or do not want to use the schema.

• For Document Name, optionally select a document type defined in that schema.

Leave this value blank if you have not specified Schema Category.

5. Create rules as usual, using the XML property paths described earlier in this book. There are two basic scenarios:


• If you have loaded the schema and have specified the target document type, the Expression Editor providesassistance when you start typing Document.

Notice that these property paths are schema-dependent paths, although you could edit them to be DOM-style pathsinstead, if those are needed for some reason.

• If you have not loaded the schema and specified the document type, you must type the path manually. You canuse either schema-dependent paths or DOM-style paths.

After you save and compile the rule set, it is available for use in a business process.

5.2 ExampleThe following shows the class definition for a simple rule set. This rule set has one rule that uses a DOM-style path tocheck the <MRN> element of the <Patient> document. Depending on the returned value, the rule routes the message toeither FileOut1 or FileOut2. Notice that in this case, the rule constraint does not refer to the XML schema or type.

Class Demo09.MyRules Extends Ens.Rule.Definition{

Parameter RuleAssistClass = "EnsLib.MsgRouter.VDocRuleAssist";

XData RuleDefinition [ XMLNamespace = "http://www.intersystems.com/rule" ]{<ruleDefinition alias="" context="EnsLib.MsgRouter.VDocRoutingEngine"><ruleSet name="" effectiveBegin="" effectiveEnd=""><rule name="CheckMRN" disabled="false"><constraint name="msgClass" value="EnsLib.EDI.XML.Document"></constraint><when condition="Document.{/$2:Patient/$2:MRN}="123456789""><send transform="" target="FileOut1"></send><return></return></when><when condition="Document.{/$2:Patient/$2:MRN}!="123456789""><send transform="" target="FileOut2"></send><return></return></when></rule></ruleSet></ruleDefinition>}

}


Defining Rule Sets for XML Virtual Documents

6Defining Search Tables for XML VirtualDocuments

This chapter describes how to define search tables for XML virtual documents. It discusses the following topics:

• Overview

• How to define a search table class

To configure a business service or business operation to use a search table class, specify the SearchTableClass setting ofthat business host. See “Configuration Steps,” earlier in this book.

6.1 Overview of Search Table ClassesBy default, if a user wants to search for data in an XML virtual document, he or she must specify the property path to anydata element of interest. Ensemble provides a mechanism that enables you to define searchable properties, so that users donot have to specify the paths. This mechanism works as follows:

• You define a search table class for each form of XML virtual document that you use. That is, the details must be dif-ferent for a document that contains, for example, <Employee> elements than a document that contains <OrderResult>elements.

This class and its data are available to all productions in the current Ensemble namespace. You can define additionalmappings to make the class available to other namespaces; you must recompile the class if you do so.

• The search table class defines a number of items, each of which specifies the following:

– Applicable document type. For XML virtual documents, a document type corresponds to an XML schema andXML type.

– Name of the searchable property, to be shown in the Management Portal.

– Information about how to retrieve the value of this searchable property. This information uses the appropriatevirtual property path.

• You configure the relevant business hosts to use the search table.

As the business host receives messages, Ensemble indexes these properties as if they were properties in a standardmessage body. You can then use these properties for searching and filtering in the same way that you use propertiesof a standard message body.


Note: Ensemble does not retroactively index messages that were received before you added the search table class.

6.2 Defining a Search Table Class for XML VirtualDocumentsTo create a search table class for XML virtual documents:

• The class must extend EnsLib.EDI.XML.SearchTable or a subclass.

• The class must include an XData block named SearchSpec. For this XData block, you must specify the XML namespaceas follows:

XMLNamespace = "http://www.intersystems.com/EnsSearchTable"

When you specify XMLNamespace, you provide Studio with the information that it needs to provide Studio Assist.

• The top-level element within the XData block must be <Items>.

• The <Items> element must contain one <Item> entry for each searchable property.

For <Item>, details are given below.

The following shows an example:

XData SearchSpec [ XMLNamespace = "http://www.intersystems.com/EnsSearchTable" ]{<Items> <Item DocType="MyApp:Patient" PropName="Gender" >{*:/Patient/Gender}</Item> <Item DocType="MyApp:Patient" PropName="MRN" >{*:/Patient/@MRN}</Item></Items>}

Each <Item> element contains a string expression that describes how to obtain the value for this property. This expressioncan include the following components in any combination:

• Literal characters within double quotes.

• Virtual property syntax within {}.

Square bracket syntax, which is supported in other scenarios, is not supported for XML virtual documents.

• ObjectScript string operators, such as the underscore (_) for concatenation.

• ObjectScript string functions, such as $PIECE or $EXTRACT.

The following list gives the details for the attributes of the <Item> element:

DocType attribute

Required. Specifies the messages to index. Specify one of the following strings:

• "category:structure" — Index this property only in messages whose DocTypeCategory matches categoryand whose DocTypeName matches structure.

For XML virtual documents, category is an XML schema name, and structure is an XML type name.

• "category:" — Index this property in all messages whose DocTypeCategory matches category.

• ":structure" — Index this property in all messages whose DocTypeName matches structure.

• "" — Index this property in all messages.


Defining Search Tables for XML Virtual Documents

In all cases, the property is indexed only if it can be found.

PropName attribute

Required. An arbitrary name that you wish to assign to this searchable property. This is the name shown in theManagement Portal.

You can assign the same PropName to different <Item> elements: When a user selects this PropName for asearch, all the entries with the same PropName are searched.

Specify any string that you expect to be meaningful, when viewed with others in the list.

PropType attribute

Optional. The default is String:CaseInsensitive. You may omit PropType if this virtual property is a string thatignores case.

The PropType may be one of the following literal strings:

• String:CaseSensitive

• String:CaseInsensitive

• Integer

• Numeric

• Boolean

• DateTime:ODBC

• DateTime:HL7

StoreNulls attribute

Optional. Controls what happens when a search encounters an empty string in the XML document. If true, thesearch returns a valid pointer to an empty string. If false, it returns a Not Found status and a null pointer. Specify1 (true) or 0 (false). The default is 0.


Defining a Search Table Class for XML Virtual Documents

AAdditional Reference

This appendix contains additional reference information for items that you use to work with XML virtual documents in anEnsemble production. It discusses the following:

• Classes to use in this production

• Business host settings in this production

A.1 Classes to UseThe following table lists the classes to use when you work with XML virtual documents in an Ensemble production.

Class to useDetailItem

Either:Classnamebusiness service

• EnsLib.EDI.XML.Service.FileService

• Any business service class that extendsEnsLib.EDI.XML.Service.Standard

EnsLib.MsgRouter.VDocRoutingEngineClassnamebusiness process

Either:Classnamebusiness operation

• EnsLib.EDI.XML.Operation.FileOperation

• Any business service class that extendsEnsLib.EDI.XML.Operation.Standard

EnsLib.EDI.XML.DocumentSource Classdata transformation

EnsLib.MsgRouter.VDocRuleAssistRule Assist Classrule set

EnsLib.MsgRouter.VDocRoutingEngineContext Class

EnsLib.EDI.XML.DocumentMessage Class


A.2 Business Host SettingsThis section describes the available settings for the business hosts described in this book, apart from the basic settingsavailable in all productions. For those; see “Configuring Business Hosts” in Configuring Ensemble Productions.

AlertOnBadMessage

Specifies whether a bad inbound message trigger an alert. If this setting is True, any document that fails validationautomatically triggers an alert.

Where available: Any business process based on EnsLib.MsgRouter.VDocRoutingEngine (or, more generally, anybusiness process based on the superclass EnsLib.MsgRouter.RoutingEngine).

Group: Additional Settings.

See also: BadMessageHandler and Validation.

AppendTimestamp

If True, the adapter automatically appends a time stamp to filenames in the ArchivePath and WorkPath directories.This convention helps you avoid name collisions if input files with the same name appear repeatedly.

If AppendTimestamp is True, the adapter uses the default specifier _%C which provides the full date and time downto the millisecond.

For full details on time stamp conventions, see the “Time Stamps in Filenames” section in the “Creating a NewProduction” chapter of Developing Ensemble Productions.

Where available: Any business service that uses a file adapter.


ArchivePath

Specifies the full path of the directory where the adapter should place the input file after processing it. Thisdirectory must exist and must be accessible. If this setting is not specified, the adapter deletes the input file afterprocessing it.

To ensure that the input file is not deleted while your production processes it, InterSystems recommends that youuse the same directory for this setting and the WorkPath setting. Alternatively, you can use only synchronous callsfrom your business service to process the data.


Group: Basic Settings.

See also: WorkPath.

BadMessageHandler

Specifies the XML business operation that disposes of any incoming XML messages that fail validation. Use oneof the following values:

• d — Ensemble examines the DocType property of the document to see if it has a value. This property hasgenerally been assigned based on the MessageSchemaCategory defined in the XML business service. If thed flag is present and the document DocType is blank, the document is declared bad.

• m — Ensemble verifies that the document structure is well formed, and that it can be parsed using the schemaidentified in the DocType property of the document. If the m flag is present in the Validation string, Ensembleuses the following tests:


Additional Reference

1. If the document DocType is blank and the document did not previously fail, the document passes validation.

2. Ensemble uses the document structure identified by the document DocType to construct a map of thedocument pieces. This is the build map for validation.

3. If the build map is created successfully, validation succeeds. Otherwise, an error status is logged indicatingwhich parts of the document structure could not be mapped.

• dm (the default) — Ensemble performs the validation associated with both the d and m flags.

• 1 — Equivalent to dm; retained for backward compatibility.

• A blank string — No validation is performed.

This setting has no effect if Validation is a blank string.



See also: Validation and AlertOnBadMessage.

BusinessRuleName

Specifies the business rule set for this business process to use.



CallInterval

Specifies how frequently, in seconds, the business service will invoke the associated inbound adapter to obtainnew input.

In general, the details depend upon the adapter used. For a file adapter, this setting specifies how often the adapterchecks for input files in the specified location. The interval is measured in seconds. The minimum is 1 second,and the default is 5 seconds. Upon polling, if the adapter finds one or more files, it sends them as Ensemble messagesto the associated business service, one message per file. After processing all the available files, the adapter waitsfor the polling interval to elapse before checking for files again.

Where available: Business services that have an associated adapter of specific types such as a file adapter.


Charset

For a business service, this setting specifies the character set to use to translate characters for the input file. For abusiness operation, this setting specifies the character set to use when writing the output file.

The choices are as follows (not case-sensitive):

• Binary — Binary transfer (the default)

• Ascii — Ascii mode FTP transfer but no character encoding translation

• Default — The default character encoding of the local Ensemble server

• Latin1 — The ISO Latin1 8-bit encoding

• ISO-8859-1 — The ISO Latin1 8-bit encoding


Business Host Settings

• UTF-8 — The Unicode 8-bit encoding

• UCS2 — The Unicode 16-bit encoding

• UCS2-BE — The Unicode 16-bit encoding (Big-Endian)

• Any other alias from an international character encoding standard for which NLS (National Language Support)is installed in Ensemble

Where available: All business services and business operations that use a file adapter.


ConfirmComplete

Indicates what special measures Ensemble takes to confirm complete receipt of a file. The options are:

DescriptionIntegervalue

Listoption

Take no special measures to determine if a file is complete.0None

Wait until the reported size of the file in the input directory stops increasing.This option may not be sufficient when the source application is sluggish.If the operating system reports the same file size for a duration of theFileAccessTimeout setting, then Ensemble considers the file complete.

1Size

Read more data for a file until the operating system allows Ensemble torename the file.

2Rename

Consider the file complete if it can open it in Read mode.4Readable

Consider the file complete if it can open it in Write mode (as a test only; itdoes not write to the file).

8Writable

The effectiveness of each option depends on the operating system and the details of the process that puts the filein the FilePath directory.



DocSchemaCategory

Specifies the XML schema that applies to the inbound documents. Select a schema that you have previouslyloaded; see “Loading XML Schemas into Ensemble.”

The XML schema is needed in the following cases:

• If you validate the messages.

• If you use schema-dependent paths anywhere in the production.

• If you use virtual property paths in the production and these paths include namespace tokens (rather thanactual namespace URIs).

Where available: Any business service based on EnsLib.EDI.XML.Service.FileService (or, more generally, anybusiness service based on the superclass EnsLib.EDI.XML.Service.Standard).




Filename

Name of the file to write.

Where available: Considering only the components described in this book, this setting is available in a businessoperation based on EnsLib.EDI.XML.Operation.Standard or a subclass such asEnsLib.EDI.XML.Operation.FileOperation. (Settings with the same name are available in other, unrelated locationsin the classes in EnsLib.)


FileAccessTimeout

Amount of time for the adapter to wait for the ability to open or move a file that it has found. This ability mightbe blocked, for example, if the data source has not finished writing the file into place.

The default is 10 seconds.



FilePath

For a business service, this setting specifies the full path of the directory in which to look for files. This directorymust exist and must be accessible. The files are retrieved in ascending order by time stamp — that is, the sameorder in which they are available.

For a business operation, this setting specifies the full pathname of the directory into which to write output files.This directory must exist, and it must be accessible through the file system on the local Ensemble machine.

Where available: Any business service or business operation that uses a file adapter.


FileSpec

Specifies the filename or wildcard file specification for file(s) to retrieve. For the wildcard specification, use theconvention that is appropriate for the operating system on the machine on which the production is running.

The files are retrieved in ascending order by time stamp — that is, the same order in which they are available.



ForceSyncSend

Specifies whether to use synchronous calls for all “send” actions defined in this routing process.

If True, make synchronous calls for all “send” actions from this routing process. If False, allow these calls to bemade asynchronously. Setting ForceSyncSend to true is intended to ensure FIFO ordering in the case where thisrouting process and its target business operations all have PoolSize set to 1, and ancillary business operations mightbe called asynchronously from within a data transformation or business operation called from this routing process.

Note that if there are multiple “send” targets, setting ForceSyncSend to true means these targets are called oneafter another in serial fashion, with the next being called after the previous call completes. Also note that synchronouscalls are not subject to the ResponseTimeout setting.

CAUTION: If ForceSyncSend is True, this can cause deadlock if another business process is called by a targetthat is called synchronously from this routing process.





Format

Specifies how to form the outbound document. You can leave this empty, in which case defaults are used. Or youcan specify a string that contains a suitable combination of the following items:

• 1-9 — indent with this number of spaces (4 is the default with the 'i' format specifier)

• a — attributes alphabetical

• c — canonical output; ignores the items 'eintw'

• e — close elements even when empty

• f — full top element not just its contents

• i — indent with 4 spaces unless 't' or 1-9

• n — include newline (lf) after every text-free element

• p — suppress output of namespace prefixes

• q — use double quotes to set off attribute values if possible

• s — use stored indentation whitespace (ignores the items 'it1-9')

• r — use stored returns / newlines (ignores the items 'nw')

• t — indent with tab

• w — add a Windows-style carriage return and line feed after every text-free element

• x — omit namespaces in output

• C(e) — output an XML header line that declares character encoding given by e. If e is empty, use theencoding defined by the adapter. If e begins with ! then force the output stream's encoding. Note that thiswill be applied automatically for file operations configured with a non-UTF-8 character set.

Where available: Considering only the components described in this book, this setting is available in a businessoperation based on EnsLib.EDI.XML.Operation.Standard or a subclass such asEnsLib.EDI.XML.Operation.FileOperation. (Settings with the same name are available in other, unrelated locationsin the classes in EnsLib.)


OpenTimeout

Specifies how long to wait each time the adapter tries to open the output file for writing.

Where available: Any business operation that uses a file adapter.


Overwrite

If a file of the same name exists in the given output directory, this setting controls what happens. If True, overwritethe file. If False, append the new output to the existing file.

Where available: Any business operation that uses a file adapter.




ResponseFrom

Specifies the targets from which the process forwards back a response to the original caller, if the caller requesteda response. Specify a comma-separated list of configured items within the production. If a string is specified, theresponse returned to the caller is the first response that arrives back from any target in the list. If there are noresponses, the process returns an empty “OK” response header.

The Response From string also allows special characters, as follows:

• The * character by itself matches any target in the production, so the process returns the first response fromany target. If there are no responses, it returns an empty “OK” response header.

• If the list of targets begins with a + character, the process returns responses from all targets together, as a listof document header IDs in the response header. If no target responds before the timeout expires, it returns anempty “OK” response header.

• If the list of targets begins with a - character, the process returns only error responses, as a list of documentheader IDs in the response header. If no target responds before the timeout expires, it returns an empty “OK”response header.

If this setting is empty, the process does not request a reply from any target and returns nothing.



See also: ResponseTargetConfigNames, ResponseTimeout.

ResponseTargetConfigNames

Specifies the destinations, in addition to the caller, to which responses are forwarded. Specify a comma-separatedlist of configured items within the production. If the setting is empty, responses are only returned to the caller.This setting takes effect only if the ResponseFrom setting has a value.



See also: ResponseFrom, ResponseTimeout.

ResponseTimeout

Specifies the maximum length of time to wait for asynchronous responses before returning a “ timed-out error”response header. A value of -1 means to wait forever. Note that a value of 0 is not useful, because every responsewould time out. This setting takes effect only if the ResponseFrom setting has a value.



See also: ResponseFrom, ResponseTargetConfigNames.

SearchTableClass

Package and class name of an XML search table class available in this Ensemble namespace. See the chapter“Adding Searchable Properties to XML Virtual Documents.”



Where available: Any business service that is based on EnsLib.EDI.XML.Service.FileService and any businessoperation that is based on EnsLib.EDI.XML.Operation.FileOperation (or, more generally, any business service thatis based on the superclass EnsLib.EDI.XML.Service.Standard and any business operation that is based on thesuperclass EnsLib.EDI.XML.Operation.Standard).


SubdirectoryLevels

Number of levels of subdirectory depth under the FilePath directory that should be searched for files matching theFileSpec pattern.



TargetConfigNames

Specifies the destinations to which inbound virtual XML documents are forwarded. Specify a comma-separatedlist of configured items within the production.

Where available: Any business service that is based on EnsLib.EDI.XML.Service.FileService (or, more generally,any business service that is based on the superclass EnsLib.EDI.XML.Service.Standard).


Validation

Specifies the kinds of validation to perform, if any, for messages received by this business host. Use one of thefollowing values:

• d — Ensemble examines the DocType property of the document to see if it has a value. This property hasgenerally been assigned based on the MessageSchemaCategory defined in the XML business service. If thed flag is present and the document DocType is blank, the document is declared bad.

• m — Ensemble verifies that the document structure is well formed, and that it can be parsed using the schemaidentified in the DocType property of the document. If the m flag is present in the Validation string, Ensembleuses the following tests:

1. If the document DocType is blank and the document did not previously fail, the document passes validation.

2. Ensemble uses the document structure identified by the document DocType to construct a map of thedocument pieces. This is the build map for validation.

3. If the build map is created successfully, validation succeeds. Otherwise, an error status is logged indicatingwhich parts of the document structure could not be mapped.

• dm (the default) — Ensemble performs the validation associated with both the d and m flags.

• 1 — Equivalent to dm; retained for backward compatibility.

• A blank string — No validation is performed.

Where available: Any business service that is based on EnsLib.EDI.XML.Service.FileService and any businessprocess based on EnsLib.MsgRouter.VDocRoutingEngine (or, more generally, any business host that is based oneither superclass, EnsLib.EDI.XML.Service.Standard or EnsLib.MsgRouter.RoutingEngine).


See also: BadMessageHandler and AlertOnBadMessage.



WorkPath

Specifies the full path of the directory where the adapter should place the input file while processing it. Thisdirectory must exist and must be accessible. This setting is useful when the same filename is used for repeatedfile submissions. If this setting is not specified, the adapter does not move the file while processing it.

To ensure that the input file is not deleted while your production processes it, InterSystems recommends that youuse the same directory for this setting and the ArchivePath setting. Alternatively, you can use only synchronouscalls from your business service to process the data.



See also: ArchivePath.