Develop > Persistence layer > Work with WebSphere Commerce services

WebSphere Commerce extended XPath notation

WebSphere Commerce uses an extended XPath notation as the query language to identify the parts of the logical model you want to query. XPath is an industry standard language for addressing parts of an XML document, and the WebSphere Commerce extended XPath notation has some extensions to this standard.

The XML documents being addressed by the extended XPath notation are Nouns, which are converted to a Java class called a Service Data Object (SDO). SDO properties can be represented as attributes (in simple case such as String) or as elements (when its properties reference another SDO object). Usually this XML document is governed by a XML schema which defines the allowable content and semantics. These SDO objects and XML schema form the WebSphere Commerce logical model.

When you use the XPath language, the XPath should match the logical schema of the response Noun. For example, given the following noun XML:

<Catalog>    
<CatalogGroup>      
<Name>MyCatalogGroupName</Name>    
</CatalogGroup>
</Catalog>

The following example shows how to look up by Name:

/CatalogGroup[Name='MyCatalogGroupName']

Note that the XPath expression matches the structure of the logical schema.

WebSphere Commerce extended XPath query notation

The syntax of specifying a query expression is shown here using the extended Backus-Naur Form notation:

• <XPath Extended Query Expression> := <Control Parameters> <XPath Query>

• <Control Parameters> : = '{' '_wcf.ap='<AccessProfile> [ (& | ;) <Name>'='<Value> ]* '}'

• <AccessProfile> : = <Literal>

• <Value> := <Literal>

• <XPath Query> := '/' RelativeLocationPath

• <RelativeLocationPath> := Step | RelativeLocationPath '/' Step

• <Step> := Name (<Predicate>)*

• <Predicate> := '[' <PredicateExpr> ']'

• <PredicateExpr> := <OrExpr>

• <OrExpr> := <AndExpr> | <OrExpr> 'or' <AndExpr>

• <AndExpr> := <RelationalExpr> | <AndExpr> 'and' <RelationalExpr> | '(' <OrExpr> ')'

• <RelationalExpr> := <Property> <Operator> <Value> | <StringMatchingFunction>'('<LocationPathOperand> ',' <Value>')' | <RelativeLocationPath> | <SearchFunction>'(' <SearchParam> ([ 'and' <SearchParam>]* |[ 'or' <SearchParam>]*)+')'

• <Operator> := '<' | '>' | '<=' | '>=' | '=' | '!='

• <StringMatchingFunction> := 'starts-with' | 'contains' | 'ends-with'

• <Value> := <Literal> | <Number>

• <SearchParam> := <ComparsionExpr> | <StringMatchingFunction>

• <ComparsionExpr> := <LocationPathOperand> <Operator> <Value>

• <LocationPathOperand> := [<SimpleRelativeLocationPath>] <Property>

• <SimpleRelativeLocationPath> := <Name> ('/' <Name>)*

• <Literal> := (' " ' (<EscapeQuot> | [^"])* ' " ') | (" ' " (<EscapeApos> | [^'])* " ' ")

• <EscapeQuot> := ' "" '

• <EscapeApos> := " '' "

• <Number> := <Digits> ('.' <Digits>?)? | '.' Digits

• <Property> := ('@')?<Name>

• <Name> := (<Letter> | '_') (<Letter> | <Digit> | '_' | '.' | '-' )*

• <Letter> := [a-zA-Z]

• <Digit> := [0-9]

• <Digits> := [0-9]+

Tip:

• Optional items enclosed in square brackets. For example, ['<PredicateExpr']

• Items repeating 0 or more times are suffixed with an asterisk.

• Items repeating 1 or more times are followed by a '+'

• Alternative choices in a production are separated by the ‘|' symbol. For example, <Alternative A>|<Alternative uicontrol>.

• Where items need to be grouped they are enclosed in simple parenthesis ().

The control parameters section of the extended query expression allows the caller to specify additional information in the query. Use the control parameters when the query cannot be expressed by an XPath query. That is, only use control parameters if the logical model cannot capture the conditions that express in the query.

For example, the caller of the Member component needs to retrieve information about the current user. The returned object is fetched based on the current userId stored in the command context. In this case, the 'self=true' name-value pair in the extended query expression can be used to indicate to the business logic additional information about the requested object. This information cannot be captured by the logical model. The query looks like this: {self=true;_wcf.ap=IBM_Admin_All}/Person.

IBM_Admin_ prefixes all services intended to be used by admin/CMC based services calls. Access profiles which do not follow the new naming conventions continue to function correctly, as compatibility is maintained with earlier versions. IBM recommends, however, that they are followed for existing access profiles, and when making changes to future access profiles. See Access profile naming conventions for more information.

Examples of query expressions

Search for organization by Distinguished Name (DN):

{_wcf.ap=IBM_Admin_All}/Organization[OrganizationIdentifier[(DistinguishedName='DN01')]]

The following example shows how to look up summary information about a catalog entry given its part number:

{_wcf.ap=IBM_Admin_Summary}/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='FU0101' or PartNumber='FU0102')]]]

Sample valid XPaths

{_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']

Sample valid XPaths with search functions

{_wcf.ap=IBM_Admin_CatalogGroupAllParentsDetails;_wcf.dataLanguageIds='-1'}/CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T' or Description/Name='T')]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' or Description/Name='T')]
{_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')]

Related concepts

Get Request and the Show Response

Related tasks

Create a new search expression

+

Search Tips   |   Advanced Search