WebSphere Commerce extended XPath notation

When making Get requests for WebSphere Commerce nouns, WebSphere Commerce uses extended XPath notation as the query language to identify which nouns to return. XPath is an industry standard language for addressing parts of an XML document, and the WebSphere Commerce extended XPath notation uses extensions to this standard.

The XPath notion is used because nouns. are defined in an XML schema and can be thought of as XML documents. WebSphere Commerce converts these nouns into a Java class called Service Data Objects (SDOs). SDO properties can be represented as attributes in simple cases such as Strings, or as elements when the SDO properties reference another SDO object. These SDO objects and XML schemas form the WebSphere Commerce logical model.

Mapping XPath notation

When using XPath expressions to request nouns, WebSphere Commerce does not use Java XPath APIs. WebSphere Commerce maps the XPath expression in the Get request to an SQL query which is defined in a query template file (.tpl file). The SQL query contains variables which WebSphere Commerce replaces at runtime. To map an XPath expression to an SQL query, WebSphere Commerce normalizes the XPath expression and associates the expression with an XPath key. To normalize the expression WebSphere Commerce removes the actual data values in the XPath. You can use the XPath key generator to normalize a specific XPath expression. The XPath key generator command-line utility takes an XPath expression as input and generates an XPath key. This key is used to locate the SQL query in the query template file.

The following code snippet is an example of an XPath expression that is not normalized:
/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='ABC123')]]]
To normalize this query, WebSphere Commerce removes the value for the PartNumber. The following code demonstrates the normalized form of this query:
/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber=)]]]
WebSphere Commerce creates a PartNumber variable that can be used within the SQL statement associated with this XPath. The SQL statement is defined in a query template file. The following SQL statement demonstrates the use of the PartNumber variable. This variable, ?PartNumber? is replaced during runtime with actual data values.
SELECT
CATENTRY_ID_1
FROM
(
SELECT
CATENTRY.CATENTRY_ID CATENTRY_ID_1
FROM
CATENTRY
WHERE
CATENTRY.PARTNUMBER IN (?PartNumber?) AND
CATENTRY.MARKFORDELETE = 0 AndPSAgreements
) T1
WHERE EXISTS
(
SELECT
1
FROM
STORECENT
WHERE
CATENTRY_ID_1 = STORECENT.CATENTRY_ID AND
STORECENT.STOREENT_ID IN ( $STOREPATH:catalog$ )
)

For more information about the XPath key generator and normalizing XPath expressions, see Generating your XPath key using the wcs_xpathkey utility

For more information about how XPath expressions map to the SQL query template, see query template file.

You can create your own methods for querying nouns by defining your own XML mappings in a query template file. For more information about creating your own queries, see creating a query.

XPath notation structure

When you use the XPath language, ensure that the XPath matches the logical schema of the response Noun. For example, given the following noun XML:
<Catalog>
    <CatalogGroup>
      <Name>MyCatalogGroupName</Name>
    </CatalogGroup>
</Catalog>
The following XPath expression example shows how to get CatalogGroup nouns based on the name attribute:
/CatalogGroup[Name='MyCatalogGroupName']
The XPath expression matches the structure of the logical schema. The expression is composed of the following components: 
{control parameters}/root node[predicate expressions]
  • The control parameters specify access controls or identify that the query conditions cannot be captured by the logical model. This parameter identifies how much data is to return for the objects queried. For example, a control parameter {_wcf.ap=IBM_Admin_All} is an access profile. Access profiles map to queries in the query template file and indicate that an administrative view of the object information is to be returned. Control parameters that cannot be captured by the logical model can include requests to return information about the current user or for a specific language. For example, the control parameter {self=true} indicates that information from the object is to be retrieved based on the current user. This information cannot be captured by the logical model and is based on the current user ID stored in the command context.
  • The root node is typically the name of the noun to be returned. It is the root element of the XML schema for the noun. In the previous example, the root node is CatalogGroup which is denoted by /CatalogGroup
  • The predicate expressions identify the parameters for the information that the query is to retrieve. Each parameter is used in a conditional statement that must be met for the nouns to be returned. The predicate expression is defined with square brackets [predicate expression]. In the previous example, the query is to return CatalogGroup nouns where the CatalogGroup has the name 'MyCatalogGroupName'.
For more information about the XPath elements and control parameters, see SQL parameters.

Creating XPath expressions

When creating your own XPath expressions you can create simple and complex expressions. Typically simple XPath expressions are explicitly defined and mapped to SQL queries in the query template files. Websphere Commerce, however, does provide another, more dynamic, way to query objects. You can use the search() function to create a more complex XPath expression to query objects. The search() function can be used to reduce the number queries that a developer needs to create. The search() function can be placed in a predicate expression that is within an XPath expression. When you use this search expression, you do not have to define each query in the query template file. WebSphere Commerce automatically generates the query at runtime based on the contents within your search expression. For more information about creating XPath expressions with the search() function, see parametric search support.

When creating any XPath expression, use the following syntax rules and tips to help specify control parameters, root nodes, and predicate expressions:
  • Control parameters - all control parameters are defined within a single set of { } brackets.
  • Control parameters - ensure that you include required prefixes when defining parameters. All access profiles are prefixed with _wcf.ap=. For example to define the IBM_Admin_All access profile use {_wcf.ap=IBM_Admin_All}
  • Control parameters - to add additional parameters use a semicolon. For example {self=true; _wcf.ap=IBM_Admin_All; _wcf.dataLanguageIds='-1'}
  • Root node - the root node must be identified by a forward slash '/' followed by the relative path.
  • Predicate expressions - all predicate expressions are defined within sets of [ ] brackets.
  • Predicate expressions - you can nest expressions to define queries that are to return information based on multiple conditions. For example, the expression [OrganizationIdentifier[(DistinguishedName='DN01')]] defines that the query is to return nouns that have an OrganizationIdentifier with a DistinguishedName of 'DN01'
  • Predicate expressions - you use the 'search' function with XPath expressions. Identify the search function, search(), within the predicate and include the search parameters within the set of ( ) parenthesis. For example, the root node and predicate expression /CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T')] identifies a search expression. This expression identifies that CatalogGroup information is to be returned when the GroupIdentifier is 'T'.
  • Control parameters and predicate expressions - you can use standard operators such as '<' '<=' '>' '>=' '=' '!=' '&' '|'
  • Control parameters and predicate expressions - Items repeating 0 or more times are suffixed with an asterisk.
  • Control parameters and predicate expressions - Items repeating 1 or more times are followed by a '+'
  • Control parameters and predicate expressions - Where items need to be grouped enclose the items in simple parenthesis ().

Examples of XPath expressions

To help you create XPath expressions to query your logical models, the following sample expressions demonstrate valid simple XPath expression syntax:

{_wcf.ap=IBM_Admin_All}/Organization[OrganizationIdentifier[(DistinguishedName='DN01')]]
In the preceding example, the XPath expression defines a query to return organization information based on the distinguished name of the organization. This expression is composed of:
  • The control parameter {_wcf.ap=IBM_Admin_All} which is an access profile that identifies that an administrative view of all information for the objects is to be returned.
  • The root node /Organization which identifies the XPath expression is querying for information within the Organization node in the XML document.
  • The predicate expression [OrganizationIdentifier[(DistinguishedName='DN01')]]. This predicate identifies that the query is to return only the information for organizations with an OrganizationIdentifier that has a DistinguishedName of 'DN01'.
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='DU0101' or PartNumber='DU0102')]]]
In the preceding example, The expression defines a query to retrieve summary information about a catalog entry given its part number. This XPath expression is composed of:
  • The control parameters {_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}. These parameters identify that the query is to return an administrative view of the summary information for the objects in the specified store language.
  • The root node /CatalogEntry identifies the XPath expression returns CatalogEntry nouns.
  • The predicate expression [CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='DU0101' or PartNumber='DU0102')]]]. This predicate identifies that the query is to return catalog entries where the CatalogEntryIdentifier contains an ExternalIdentifier that is a PartNumber with a value of either DU0101 or DU0102.

The following code examples provide additional samples of valid XPath expressions:
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}/CatalogEntry[ParentCatalogGroupIdentifier[(UniqueID='10128')]]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogGroup[ParentCatalogGroupIdentifier[(UniqueID='10125')]

{_wcf.ap=IBM_Admin_CatalogEntryMerchandisingAssociations;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[(UniqueID='10541')]]

{_wcf.ap=IBM_Admin_CatalogEntryAttachmentReference;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[(UniqueID='10541')]]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogGroup[@topCatalogGroup='true']

Examples of query expressions with search functions

To help you create XPath expressions that use search functions to query your logical models, the following sample expressions demonstrate valid XPath expression syntax:

{_wcf.ap=IBM_Admin_CatalogGroupAllParentsDetails;_wcf.dataLanguageIds='-1'}/CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T' or Description/Name='T')]
In this example, the XPath expression defines a query that returns CatalogGroup information based on search results. The expression identifies that WebSphere Commerce is to return information for catalog groups with either a GroupIdentifier or a Description/Name with a value 'T'. The search function specifies to search for the GroupIdentifier within the ExternalIdentifier node for the CatalogGroupIdentifier of a CatalogGroup.
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' or Description/Name='T')]
In this example, the expression includes a search function with both a simple search expression and a wildcard search expression. The wildcard search, specifies to query for any catalogEntryTypeCode contained in the CatalogEntry node that has a value of 'PackageBean' or 'DynamicKitBean'. This wildcard search specifies to query all nodes within the CatalogEntry root node, regardless of the relative path of the catalogEntryTypeCode location. The simple search expression operates as shown in the previous search function example. This search expression combines with the wildcard search expression to specify that only information that matches both search expressions is to be returned.
The following code examples provide additional samples of valid XPath expressions with search functions:
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(starts-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or starts-with(Description/Name, 'T'))]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='ProductBean' or @catalogEntryTypeCode='BundleBean' or @catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(starts-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') and Description/Name='C' and starts-with(CatalogEntryAttribute/Attributes/mfPartNumber, 'T') and CatalogEntryAttribute/Attributes/mfName='B') and ParentCatalogGroupIdentifier[ExternalIdentifier[GroupIdentifier='Bottom']]]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='BundleBean') and search(contains(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or contains(Description/Name, 'T'))]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='BundleBean') and search(ends-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or ends-with(Description/Name, 'T'))]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' or CatalogEntryIdentifier/ExternalIdentifier/PartNumber='B' or Description/Name='T' or Description/Name='B')]