The next two chapters describe in detail how to create property paths.
The code examples in this chapter are fragments from data transformations, because data transformations generally use 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 you drag and drop or when you use auto-completion.)
Where unit1 is the name of a child XML element in the document, unit2 is the name of a child element within unit1, and so on. The leaf unit is the name of either a child XML element or an XML attribute.
A DOM-style path always starts with a slash and has the basic structure shown in the following example:
Each path unit has the following form.
Where namespace_identifier represents the XML namespace; this is a token that Ensemble replaces with the actual namespace 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.
When you load a schema into Ensemble, Ensemble establishes a set of tokens for the namespaces used in that schema, for use 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 schema namespace (http://www.w3.org/2001/XMLSchema). The token $2 is used for the next namespace that is declared in 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 are actually used. Therefore, Ensemble might use $3 or a higher value rather than $2 for the items of interest to you, if additional namespaces are declared in the schema. It is practical to use the Management Portal to view the individual path units, as discussed in the next section, 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 applicable business host to use that schema). Otherwise, you must use the namespace prefixes exactly as given in the XML document.
Until you are familiar with property paths for XML virtual documents, it is useful to use the Management Portal to view the 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:
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 a schema are ignored in schema-dependent paths; the following item shows another example.
The <Doctor> element includes a single <Name> element. On the schema viewer page, the <Doctor> item is shown as Doctor in the Name column, as shown in the previous figure.
Notice that the schema-dependent path to the data inside <Doctor> does not use the name of the inner element.
In contrast, the same item is shown as $3:Doctor/$3:Name in the Element column on the right. This column shows the path unit for DOM-style paths.
If a given element can occur multiple times, the Name column displays parentheses () at the end of the element name. For example, see the FavoriteColors() row in the preceding figure.
The Type and Element columns indicate the number of times the element can be repeated. In this case, the element can be repeated five times. If there is no number displayed in parentheses in the Type column, the element can be repeated any number of times.
If an XML schema has multiple elements at the same level that have the same name but different types, 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. 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:
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.