Perfion-API-Reference-2.7[1]

Copyright 2011 Perfion
Perfion API Reference – 2.7

Perfion API Reference

1 Image & File Server .......................................................................................................................... 2
1.1 File Server ................................................................................................................................ 2
1.2 Image Server ............................................................................................................................ 2
1.3 Image Watermarking................................................................................................................ 3
1.4 Proportioning of Multiple Images ............................................................................................. 4

2 Data Web Service............................................................................................................................. 5

3 The Perfion Query ............................................................................................................................ 6
3.1 A simple example ..................................................................................................................... 6
3.2 Result Metadata ....................................................................................................................... 6
3.3 Result Data ............................................................................................................................... 7

4 The Perfion Query - SELECT .............................................................................................................. 9
4.1 Select Specific Features ............................................................................................................ 9
4.2 Select Many Features ............................................................................................................. 10
4.3 Select Expressions .................................................................................................................. 10
4.4 Select Remote Variants........................................................................................................... 11

5 The Perfion Query - FROM ............................................................................................................. 13

6 The Perfion Query - WHERE............................................................................................................ 14
6.1 Features ................................................................................................................................. 14
6.2 Properties............................................................................................................................... 14
6.3 Languages .............................................................................................................................. 15
6.4 Operators ............................................................................................................................... 16
6.5 Hierarchy Notation ................................................................................................................. 18
6.6 Clause Methods...................................................................................................................... 19
6.7 Nested Clauses - AND, OR, ( … )............................................................................................. 20
6.8 System Variables .................................................................................................................... 21

7 The Perfion Query - ORDER ............................................................................................................ 22

8 The Perfion Query - HAVING........................................................................................................... 23

9 The Perfion Query - Known Issues .................................................................................................. 24

10 Changes ......................................................................................................................................... 25

1 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

1 Image & File Server

The Image & File Server API is hosted on a Microsoft IIS Web Server. The Service is designed
according to a pull-strategy such that it scales linearly. Files and images are retrieved from the
Perfion database when needed. Local copies are cached on the Web Server so they only have to be
retrieved once after they have been added or changed.
Images can be delivered directly to a Web Page by adding the following html-code:

<img src="http://ServiceHostName/Perfion/Image.aspx?id=fileId" />

Similarly, files can be retrieved with the following html-code:

<a href="http://ServiceHostName/Perfion/File.aspx?id=fileId" />

Similarly, files containing other content such as flash, video etc. can be included on a web-page for
download or direct feed via the proper html tags such as object for embedding objects etc.
1.1 File Server
The above SRC-URL will retrieve the original file or image as it was stored in the Perfion database.
id
The id parameter specifies the id of the file or image to retrieve. The id value is found via a standard
API data query as described in another section of this document.
action
If the Image or File must be saved directly from a web-page, an action parameter can be added to
the URL in the following manner:

<a href="http://ServiceHostName/Perfion/File.aspx?id=fileId&action=save" />

This causes the browser to open a Save as Dialog, allowing the user to save the file.
For non-image files the action parameter is the only extra parameter available.
1.2 Image Server
For images, a range of additional URL-parameters are available to deliver images in different sizes
and formats as described below. The following example would deliver an image in jpg-format to fit
within a 200 by 200 pixel area.

<img src="http://ServiceHostName/Perfion/Image.aspx?id=fileId&size=200x200&format=jpg" />

Supported Image Formats
The extra functionality provided for manipulating images is available for all the image formats
supported by the Microsoft .NET Framework i.e.; JPEG, GIF, PNG, TIFF, BMP etc. Proprietary image
formats such as Adobe PSD format is currently not supported but will likely be added in a future
version of Perfion.

2 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

dpi

This parameter will scale the image exactly to the specified resolution. This parameter cannot be
combined with the size or fit parameters. For precision, the parameter value can include a decimal
separator (use the period character ‘.’ ).

size

This parameter defines the size in pixels (width x height) in the following manner size=200x200. The
pixels must be expressed in whole integer numbers, i.e. no decimal points are allowed.
The size can be interpreted in several ways since it is possible to define width and height ratios that
are not equivalent to the original image. How the size is interpreted is controlled by the fit
parameter. The default behavior is to scale the image to fit within the specified size by keeping the
aspect ratio.

fit

This parameter controls how to interpret the size parameter.

 fit=fit
Default behavior (equivalent to omitting the parameter).
Scale the image to fit within the specified size by keeping the aspect ratio.

 fit=exact
Scale the image to fit the specified size exactly.
If the specified size does not have the same proportions as the original image, then the image will be
stretched in one or the other dimension.

 fit=crop
Scale the image to fit the specified size exactly.
If the specified size does not have the same proportions as the original image, then the image will be
cropped either at the sides or at the top/bottom thereby leaving the contents of the image undistorted.

 fit=smart
Scale the image to fit the specified size exactly.
If the specified size does not have the same proportions as the original image, then the image is adjusted
via a 50% combination of the above exact and crop fitting methods, i.e. the image is cropped a little less
and stretched a little less.

1.3 Image Watermarking

For protection of Images, it is possible to automatically place a watermark on all images delivered by
the image server. This is simply done by requesting images via a slightly different URL in the
following manner:

<img src="http://ServiceHostName/Perfion/Imagew.aspx?id=fileId&size=200x200&format=jpg" />

Security

The only difference is the addition of a ’w’, which makes the URL point to a different physical ‘aspx’
file on the web server. In this way it is possible to use all the IIS Security options, e.g. if external web
access should only expose watermarked images while others might get access to original non-
watermarked images.

3 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

Sizing and Appearance

Watermarking is applied by creating a specific watermarking-image that is used to overlay any of
the images delivered by the image-server.

The Watermarking-image is always applied in the lower-left hand corner. If the Watermarking image
is larger than the image it is applied to, it is scaled down to fit within the image, which means it will
then fill out 100% of one of the dimensions. If it is desired to only fill e.g. max. 75% of any
dimension, the Watermarking image should be created on an oversized Image canvas with a
transparent background, which will then allow full flexibility in how it will appear.

In the same way, the part of the Watermarking image that should overlay an image can also contain
a degree of transparency in order to make the Watermarking appear smooth and less dominant.

Configuration

Which watermark-image to use is specified in the Web.Config file in the following manner:

<appSettings>
<add key="watermark" value="watermark.png"/>

</appSettings>

In this case the path to watermarking image is relative to the location of the Imagew.aspx file.

1.4 Proportioning of Multiple Images

In order to display multiple images side-by-side it may sometimes be necessary to scale these using
the same dpi, otherwise the size of the contents of the images will look wrong when compared to
one another.

The following method can calculate which dpi-resolution to use for scaling a list of images so each
one of them will fit within the specified width x height frame and match each other proportionately.

float CalcImageScale( int maxWidth, int maxHight, Guid[] imageIDs );

Parameters for the method:

int maxWidth Max. width (in pixels) that every one of the specified images must fit within.
int maxHeight Max. height (in pixels) that every one of the specified images must fit within.
Guid[] imageIDs List of images that are to be scaled equally.

4 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

2 Data Web Service

All data from Perfion can be queried via a single method.

string ExecuteQuery( string query );

Parameters for the method:

string query Xml formatted search.
The Perfion Query Xml is separated into the sections: <Select>, <From>, <Where>, <Having> and
<Order>.
The syntax is inspired by normal SQL and should therefore be easy to learn.

As input, the method takes a Perfion Query in Xml-format. The syntax is inspired by normal SQL, but
is enhanced with the ability to return multi-valued and sequenced data as well as localized data in
multiple languages, and a number of other advanced abilities not possible with the regular SQL
tabular result format.

The method returns all data in Xml-format. For binary features such as images and files, the
binaryID Guid value is returned. The actual Binary data can then be retrieved via the File & Image
Server, as described in another section of this document.

5 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

3 The Perfion Query

The Perfion Query syntax and all its possibilities are described in the following sections.

3.1 A simple example

Below is a very simple example of what a Perfion Query could look like. The query is defined to

return data for the 3 features ItemNumber, Image and Description in the English language for

Products that have 8 Cylinders.

<Query>
<Select languages='EN'>
<Feature id='ItemNumber' />
<Feature id='Image' />
<Feature id='Description' />
</Select>
<From id ='Product'/>
<Where>
<Clause id='Cylinders' operator='=' value='8' />
</Where>

</Query>

Below is an example of what the results from the above query could look like:

<Data>
<Features>
<Product language="EN" caption="Product" unit="" abbr="" group="Marketing" dataType="String" />
<ItemNumber language="EN" caption="Item Number" unit="" abbr="" group="Marketing"

dataType="String" />
<Image language="EN" caption="Image" unit="" abbr="" group="Marketing" dataType="Image" />
<Description language="EN" caption="Description" unit="" abbr="" group="Marketing"

dataType="Text" />
</Features>

<Product id="119" parentId="42" brand="Normal">
<Value language="EN" seq="0">Audi S4 Cabriolet 4.2 FSI Quattro</Value>
<ItemNumber seq="0">AUS4C42FSI</ItemNumber>
<Image seq="0" string="S4 Cabriolet Image 1.jpg">99112bf1-0ab2-4c9f-b243-a1c5f57a94ac</Image>
<Description language="EN" seq="0">The S4 Cabriolet - a car of pure sports character. Its

beautiful design and blistering power mark it as a car of serious open air intent. But this is no showy
convertible. The premium heritage of Audi is displayed in every detail – the elegance of line, the
opulent interior and an understated styling that belies the horsepower beneath. </Description>

</Product>

<Product id="130" parentId="44" brand="Normal">
<Value language="EN" seq="0">Audi A6 Avant 4.2 FSI Quattro</Value>
<ItemNumber seq="0">AUA6A42FSI</ItemNumber>
<Image seq="0" string="A6 Avant Image 3.jpg">b0e0504c-d63f-4449-b5f6-d0c2f2e029e0</Image>
<Description language="EN" seq="0">Spacious, sporty and supremely versatile, the A6 Avant

embodies Vorsprung durch Technik. Exceptional handling, stylish looks and a refined interior make it the
perfect all-rounder.</Description>

</Product>
</Data>

The Xml result always starts with the Metadata about the returned features followed by all the
actual data.

3.2 Result Metadata

The first part of the Xml result always contains a section called <Features>, that contains all the
metadata about the returned features, such as:

id The unique ID of the feature.
In API queries both the feature name and ID can be used.

language Indicates the language of the values of the other attributes in the Xml-element.

6 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

caption The caption to precede the value on e.g. a web page, in a catalog or other output.
captionAlternative
unit An alternative caption.
abbr
group The unit of the value of the feature.
groupOrder
viewGroup The abbreviation (could be used instead of the caption in some situations).
viewGroupOrder
dataType The Information Group the feature belongs to.
viewOrder
The Order of the Information Group as they are defined in Perfion
form
The View Group the feature belongs to (if defined in Perfion)

The Order of the View Group as they are defined in Perfion

The Perfion DataType of the feature (string, number, date, text, image, file, query, table).

The Order of appearance of the features.
Important: This is a first seen order of appearance. Each item in the result-set may have a
different viewOrder defined in Perfion. The viewOrder at this level is set by inspecting
each item until all columns have an order.
This viewOrder is relevant when several Items must be shown together on a list.

A value indicating the form/nature of the feature, which can be either of:
‘Simple’: A simple feature containing only its own base values.
‘Complex’: The feature is extended with a configuration of additional features (e.g. a
Product with many features, or a Designer with additional features).

3.3 Result Data

All the rest of the elements in the Xml contain the actual data. In the above example the enclosing
elements are named <Product> since the returned items are of the feature type Product, as
specified by the <From> element in the Perfion Query.

The enclosing <Product> Item elements always contain the following attributes:

id The unique ID of the item.
parentId The ID of the parent Item (when in a hierarchy). 0 if it has no parent.

brand The brand of the Item (can be either: Virtual, Normal, CatalogRoot or Brand).

order The Order of the Item as defined on the Item itself for its own purpose (e.g. when ordering
the Sections on the left side or defining a special order of Items in a Lookup for their own
purpose). For features that do not allow ‘Custom Ordering’ the Order will always be 0.

childCount The number of child items that have this Item as their parent.
Optional: Only included with Select option ‘IncludeChildCount’ specified.

The feature value elements contained within the <Product> elements may contain the following
attributes:

id The unique ID of the item. For features defined as ‘Selectable’ (i.e. Lookup values).

language The language of the value of the Xml-element (for features defined as ‘Localizable’.

seq The sequence of the values, for features defined to ‘Allow Multiple’ and ‘Sortable’ values.
The sequence is 0 for all other feature values.

relatedOrder This order appears on a feature value element when the specific feature in its definition
includes ‘Sortable Related Items’. The order indicates how the enclosing <Product> Item is
ordered in relation to the feature (e.g. the order of a Product Item within a certain Section).

7 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

viewOrder The order in which the features for an Item should appear (as defined in the Item
Configuration where features can be ordered individually for different Categories or
groupings of Products or Items).
Features included explicitly by the Query are ordered as defined in the Query, followed by all
other features according to their order as defined by the feature Configuration.
Optional: Only included with Select option ‘IncludeFeatureViewOrder’ specified.

Furthermore, for Image and File features the following attributes are used:

string Used to hold the filename of the image or file.

fileSize The file size in bytes.

fileModifiedDate The date when the file was last modified.

8 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

4 The Perfion Query - SELECT

<Select languages='EN,DE' view='Virtual,CatalogRoot,Normal,Branded'>

languages Specifies the languages to be returned (above selects English and German)
view
Specifies the types of Items to be returned (can be any single or multiple combination of
index Virtual, CatalogRoot, Normal or Branded. If e.g. only Normal Items (e.g. Real Products) are
maxCount wanted, only Normal should be specified.

options Used for Paging through a larger result-set.
0-indexed position of the first Item in the result-set. (default: 0)

Used for Paging through a larger result-set.
The maximum number of Items to retrieve, counting from the position specified by the index
attribute. (default: everything)

Specifies special Query execution behaviour.
The following options are available and can be combined (separated by comma):

IncludeDebugInfo

In addition to the Total Execution time, this option ncludes additional Query timing
information for time used by pure SQL, retrieval of remote values and other internal data
filling or configuration tasks.

IncludeTotalCount

Includes the total number of found Items matched by the Where clause. Useful when Paging
through the result-set. May incur extra execution time for large result-sets.

IncludeChildCount

Includes a ‘childCount’ attribute value for each Item in the result-set, with the number of
child items that have the Item as their parent.
This is very useful for e.g. a web-solution for navigating through large hierarchical result-sets,
so navigation trees or menu Items know whether they can unfold to display sub-items (lazy-
loaded when and only if they are needed).

IncludeFeatureViewOrder

Includes a ‘viewOrder’ attribute value for all feature elements in the result-set, specifying the
appearance ordering of features for each of the individual Items.
This is very useful for e.g. a web-solution, making it possible to design fully generic lists and
detailed product or item pages with varying information and order of appearance.

RemoveUnwantedFeaturesByConfiguration

The normal behaviour of the Query during retrieval of a result-set containing more than 1
Item, is to determine what features are relevant for any of the Items in the result-set. If a
feature is relevant for 1 Item it will be retrieved for all other Items also, such that the entire
result-set can be displayed in a list with the same columns available for all Items.
When specifying this option, each Item will be treated individually, and only the feature
values that are specified to appear for each Item will be retrieved. If presented side-by-side
this means that some Items may not display values for some features even though they
might have values defined for these features.
Which features to display values for is determined by the Configuration of a feature.
The exact behaviour of this option is determined by wildcard selection of features in
combination with the ‘view’ attribute on the Select <Feature> element.
This is very useful for e.g. a web-solution, making it possible to design fully generic lists and
detailed product or item pages with varying information and order of appearance.

4.1 Select Specific Features

<Feature id='ItemNumber' />
<Feature id='Actors'>

9 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

The id attribute of the <Feature> elements, specify the name of a feature (or alternatively the
unique ID number of a feature).
4.2 Select Many Features

<Feature id='*' />

Setting the id attribute to the wildcard * character will return all the feature values stored and
managed directly by Perfion.

<Feature id='*' view='ViewList' />

Including a ‘view’ attribute, makes it possible to select all features that are Checked On a specific
View-list in the feature configuration. Currently the following view-lists are available; ViewList,
ViewWeb, ViewLookUp, and Config. Config includes all features that are configured on a feature.

<Feature id='**' view='ViewList' />

Setting the id attribute to a super wildcard ** (double character), in combination with a View-list,
will also include retrieval of all Remote features defined by the Configuration or View-list, live-linked
by Perfion from all the configured remote data sources.
Important
Complex remote features (based on cluster queries), such as e.g. price variants only return the
values according to their default specification in the remote query (when included by wildcard
technique described above).
To control exactly which remote feature variants are returned by the query, the specific remote
features must be included explicitly in the query and include further specification of variants,
parameters and columns (as described in more detail under Select Remote Variants).
4.3 Select Expressions
For data exports to portals or external design tools it is important to be able to format the data,
since these external design tools cannot format numbers and dates etc. – they treat all data as
strings and will present the data as they are received.
Expressions can be used to format the values of a feature. This can make sense in many situations
where e.g. a number must be formatted in a certain way, multi-values must be merged together
into a single value, the value of a composite must be calculated by combining several other feature
values and their metadata etc.
The following expression returns all the names of the Multi-valued feature Actors separated by
comma and a space.

<Feature id='Actors'>
<Expression id='List' expression='@FormatMultiValues({Value}|, )'/>

</Feature>

The output from the above query could look like this:

10 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

<Item>
<Attr feature='Actors' id='200'>Cameron Diaz</Attr>
<Attr feature='Actors' id='201'>Sandra Bullock</Attr>
<Attr feature='Actors' id='202'>Mel Gibson</Attr>
<Attr feature='Actors' expression='List'>Cameron Diaz, Sandra Bullock, Mel Gibson</Attr>

</Item>

The following returns 2 different expressions results on the same Compound feature ProductSize.
The feature ProductSize is defined in Perfion as being a combination of 3 different features; Width,
Height and Length.

<Feature id='ProductSize'>
<Expression id='Compound' expression='@FormatMultiValues({Abbr}:{Value} {Unit}| )'/>
<Expression id='List' expression='@FormatMultiValues({Value} {Unit}| / )'/>

</Feature>

The first expression with id=Compund will return the values as ‘W:200 mm H:20 mm L:400 mm’.
The second expression with id=List will return the values as ‘200 mm / 20 mm / 400 mm’.

4.4 Select Remote Variants

Returning values for remote variants such as e.g. customer specific prices or prices in specific
currencies etc. is done by the following syntax:

<Feature id='Price'>
<Parameter id='@PriceDate' dataType='Date'>2008-09-12 10:45:00</Parameter>
<Variant>EUR-ret</Variant>
<Variant>EUR-net</Variant>
<Column id='Currency'/>
<Expression id='Money' expression='{Value:#,###.00}'/>
<Expression id='MoneyDK' expression='{Value:#,###.00}|DA-DK'/>
<Expression id='Coded' expression='{Value:00000000}'/>

</Feature>

Parameter refers to a parameter named ‘@PriceDate’ and of DataType Date which is defined and
used in the remote query defined in Perfion used to retrieve the remote values. The value of the
Parameter is set to the parameter in the remote query before execution. As many parameters can
be defined as needed.
Variant is similar to Parameter, but is a special parameter that can be multi-valued and is known by
Perfion to be the variant. A unique key (e.g. an ItemNumber) in combination with the variant should
in combination always represent unique rows in the returned remote values.
Column defines the name of an additional informative column value returned from the remote data
source that also should be included in the result set for the specified feature. As many additional
columns can be defined as needed.
In addition to the Parameters, Variants and Columns, it is also possible to format the returned
values by the use of expressions.
The expression id=Money would format the number 1234.5 as 1.234,50
The expression id=Coded would format the number 1234.5 as 00001235
The output from the above query could look like this:

11 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7
<Item>
<Attr feature='Price' variant='EUR-ret' currency='EUR' seq='0'>15.92567</Attr>
<Attr feature='Price' variant='EUR-ret' currency='EUR' seq='0' expression='Money'>15,93</Attr>
<Attr feature='Price' variant='EUR-ret' currency='EUR' seq='0' expression='Coded'>00000016</Attr>
<Attr feature='Price' variant='EUR-net' currency='EUR' seq='1'>34103.98567</Attr>
<Attr feature='Price' variant='EUR-net' currency='EUR' seq='1' expression='Money'>34.103,99</Attr>
<Attr feature='Price' variant='EUR-net' currency='EUR' seq='1' expression='Coded'>00034104</Attr>
</Item>

12 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

5 The Perfion Query - FROM

The From part of the Xml query only has one attribute and that is the ID of the feature to retrieve
related feature values from, such as shown by the example below from the feature Products.

<From id ='Product'/>

From only works on features that are defined as selectable, since this is the only way a feature gets
its own identity and can have related feature values.
The from ID does, however, works on multiple features at the same time as shown by the following
example:

<From id ='Product,Categories,Product2'/>

This is very powerful in that it allows to distribute e.g. products across several features in case this
was needed. Or perhaps search for Persons that for some reason need to be split across several
Person archives etc.
Important
It is not recommended to use multiple features in the From, when using super wildcard ** (double
character) to retrieve values for several configured features. Retrieval of Remote features may not
make sense for all the features included in the From, and may cause slow performance or simply
fail. In such case, design and application of remote queries must be designed appropriately.

13 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

6 The Perfion Query - WHERE

The Where part is built up from a list of clauses that are AND’ed together in the following manner:

<Where>
<Clause id='Category.ID' operator='=' value='3' />
<Clause id='Cylinders' operator='=' value='6' />
<Clause id='EnginePower' operator='BETWEEN'>
<Value>100</Value>
<Value>300</Value>
</Clause>

</Where>

The syntax of the Clause id xml attribute is as follows:

Feature1.Feature2.FeatureN.Property(Language1,Language2,LanguageN)

6.1 Features
Each feature can be written as either the unique featurename or the unique featureID. It is possible
to change the feature name in Perfion so the featureID is more safe to use, but using the name
makes it considerably easier to read and write the queries.
When more features are written after one another, they refer to the values of features on features
such as e.g. Actor.Age>35.
When no features are written the clause refers to the type of items being returned, i.e. the FROM
features e.g. the Product name. In this case a Property must be specified e.g. String='Audi A4'
Wildcard features
Instead of naming a single feature explicity to search for the same value across several features by
using a wildcard instead of the feature name, such as:
*.Number>100 (In case the retrieved Items are Products , this would mean any feature on Products
that has a nummeric value greater than 100, but it could also be written as
Manufacturer.*.Number>100 (meaning any products from Manufacturers that have any nummeric
feature with values greater than 100).
Instead of using wildcards, it is also possible to specify exactly which features to search, e.g.
(105,200,265).Number>100 (meaning any Products that have a nummeric value greater than 100,
on the features with ID 105, 200 or 265. For this special notation the feature ID values must be
used, the feature names are not supported.
6.2 Properties
For a feature such as Actor, its datatype would most likely be defined as a string whereas a feature
such as Age would be a Number. By writing the feature Actor it would then be interpreted as a
string value and Age as a Number value. However, for all features it is possible to explicitly access
the following properties:

 String, Number, Text, Date, BinaryID

14 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

In many cases it is irrelevant to write which property to use since it is derived automatically from
the feature, e.g. writing; Actor='Gibson' or Actor.String='Gibson' has the same meaning since
the feature Actor is defined as datatype string. For the feature Actor it does not make sense to
access any of the other properties since they give no meaning.
For some features it does give meaning to access the properties directly. When working with images
or files they consist of both the binary file and a file name. In these cases these values can be
accessed as Image.String='filename.jpg' and Image.BinaryID='<Guid>' where the Guid is the
unique identity used to reference the binary file.

 StringText
The StringText property combines the String and Text properties for searching purposes, and is
mostly relevant when doing Feature Wildcard searches across multiple features such as e.g.
*.StringText LIKE '%Audi%'
This would find any Product that contains the value Audi on any feature irregardless of whether it is
a String or Text feature.

 ModifiedBy, ModifiedDate, CreatedBy, CreatedDate
These properties would f.x. make it possible to find all products that have values modified since a
specific date. The ModifiedBy and ModiFiedDate properties can be applied anywhere.
The CreatedBy and CreatedDate Properties can be applied anywhere, with the exception that they
cannot follow non-selectable features such as e.g. ItemNumber.CreatedBy='Admin'. In this case
simply write: CreatedBy='Admin' which would yield all Items that were created by the specified
user.

 ID, ParentID, Brand
For Selectable features that have their own identities and can be attributed with other features
themselves, the following extra identity properties are available:
This makes it possible to query against the ID of the actual items as well as their ParentID, which will
probably be the preferred approach for programmatic control e.g. for web sites or other solutions,
since data resultsets will always include the ID and ParentID of all items.
ParentID=0 (will only return Items in the root, i.e. they have no parents)
Furthermore it is also possible to specify which types of Items (e.g. Normal, Virtual, CatalogRoot or
Branded ) to include in the query in the following manner:
Brand='Normal' (will only return normal items)

6.3 Languages
Using languages in clauses are always optional, and can only be relevant for localizable features. The
default behaviour is to search for a value in any language. If the query should only take values from
1 or more languages into account it is possible to do this by including the language codes as in the
following example:

Color(EN,DE) LIKE 'Bl%'

15 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

This example will match all values from English and German language with Color values that starts
with ‘Bl’ in their name such as Blue or Blau.

6.4 Operators

The Perfion SQL Syntax offers the following operators.

=

!=
>
>=
<
<=
LIKE, NOT LIKE
MATCH, NOT MATCH
IN, NOT IN
BETWEEN
HAS, NOT HAS
EXECUTE

The operators will be described with examples below.

LIKE, NOT LIKE, =, !=, <, >, <=, >=

These operators are well known from normal SQL syntax and behave the same. The syntax for
writing the Perfion clause looks like the following example:

<Clause id='EnginePower' operator='>=' value='170' />

The LIKE operator behaves exactly like the well known LIKE operator from normal SQL syntax, with
the possibility of using % for Wildcard searches.

MATCH, NOT MATCH

The MATCH operator is similar to the LIKE operator in that it can be used to perform wildcard
searches. The primary difference between the 2 are, that normal users do not easily understand the
LIKE behavior with explicit use of % as wildcard, but assumes that it is possible to just type a part of
a word, or multiple words, and get some results.

Therefore the MATCH operator automatically surrounds the search value with % wildcards (invisible
to the user). But the MATCH operator goes even further, to split up multiple words into multiple
clauses. The following table illustrates various searches and how they are interpreted:

MATCH Interpretation

Audi Contains Audi (somewhere in the feature value)
Audi A4 Contains both Audi and A4 (somewhere in the feature value)
“Audi A4” Contains “Audi A4” (somewhere in the feature value)
=”Audi A4” The feature value must be exactly “Audi A4”
“Audi A4” Avant Contains “Audi A4” and Avant
Audi*A4* Starts with Audi, and contains A4 somewhere after Audi

IN, NOT IN

The syntax for using an IN clause (with multiple search values) must be written as in the following
example:

16 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

<Clause id='ID' operator='IN'>
<Value>119</Value>
<Value>137</Value>

</Clause>

BETWEEN
The syntax for using a BETWEEN clause must be written as in the following example:

<Clause id='EnginePower' operator='BETWEEN'>
<Value>100</Value>
<Value>300</Value>

</Clause>

Both of the Value elements must always be present. Leaving one of them blank will make the
BETWEEN clause behave as either > or < instead.

HAS, NOT HAS
The syntax is shown by the following example.

<Clause id='EnginePower' operator='HAS' />

The above example will find all items that has a value defined for the EnginePower.
NOT HAS will find all items that does not have a value defined for the specified feature.

EXECUTE

The EXECUTE operator makes it possible to execute predefined behavior. This is a very powerful
ability, which makes it fast and easy to create much more advanced functionality (that would
otherwise be too complicated for normal day-to-day users to figure out), or impossible to defined
via the easy-to-use GUI filters.
The syntax is shown by the following example.

<Clause id='FavoriteSearches' operator='EXECUTE' value='FindSpecialItems' />

The above example will find an Item named ‘FindSpecialItems’ from the feature named
‘FavoriteSearches’, retrieve the Text property value of this Item. In this case, the Text property value
must contain a valid Perfion API query, and the entire Clause part of this query will be added instead
of the above Clause Element.
No retrictions apply to the embedded queries. This means, that it is possible to embed queries into
other predefined queries recursively, and thereby reuse predefined queries in many powerful ways.
If a predefined query is added in the GUI search filter with the EXECUTE operator, the clauses of the
predefined query is added to any other search criteria chosen by the user, which make it possible to
expose the predefined queries in a way that is very easy to understand for the users.

IN HIERARCHY OF
This clause makes it easy to find e.g. all the product items that are in a specified hierarchy of a
category structure. The syntax is shown by the following example.

<Clause id='Category.ID' operator='IN HIERARCHY OF' value='2' />

Assuming the example clause above is applied to searching for product items, then it will find all
product items that are found in categories with Category.ID=2 or any categories in the hierarchy of

17 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

this category (i.e. all child categories at any depth), such that the category with ID=2 is considered to
be the root of the hierarchy to search.
NB: This operator will be deprecated in a future version. Instead use the much more powerful
Hierarchy notation as described in another section of this document.
6.5 Hierarchy Notation
As presented earlier, the syntax of the Clause identity part is as follows:

Feature1.Feature2.FeatureN.Property(Language1,Language2,LanguageN)

Each feature is separated by a . (dot), and this dot-notation is widely used and understood from
many other syntaxes. The Perfion API extends this dot-notation with a very powerful concept that
has been denoted Hierarchy-notation. In addition to the dot, it is possible to use the curly
parentheses { or } to denote a downwards or upwards hierarchy of child or parent Items, like:

Feature1}Feature2.FeatureN{Property(Language1,Language2,LanguageN)

Child-hierarchy
The following example illustrates how it works:

With normal syntax, all Cars can be found by writing the following Clause:

Category='Cars'

With hierarchy-notation all Motor Vehicles (i.e. all Items in both Busses and Cars, or any other
Category at any depth contained inside Motor Vehicles) can be found by the following Clause:

Category{String='Motor Vehicles'

…and since the String property is default for e.g. the Category feature, simply write:

Category{='Motor Vehicles'

…or even more powerful, combine it with other Properties such as:

Category{ LIKE 'Motor%'

NB: The performance of the hierarchy-notation deprecates considerably with too many matches at
the highest level (e.g. if many categories match ‘Motor%’), so it should be used with some
consideration.
The above example illustrates the use of hierarchy-notation on the feature Category assuing that
the Items beeing found are Products. However, the same is possible within the feature itself (e.g.
products without thinking about its features), as illustrated by the following example:

18 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

With normal dot-syntax, the Audi Item above can be found by writing:

String='Audi'

With hierarchy-notation all Audi cars can be found by writing:

{String='Audi'

Parent-hierarchy
The hierarchy-notation can also be used in the parent (upwards) direction. This could be e.g. be
useful to retrieve the entire parenthood of an Item, such as:

}String='Audi A4 1.8 TFSI'

…will return the specific ‘Audi A4 1.8 TFSI’ Item as well as all its parent Items all the way up to the
root Item (in theis case the Item named ‘Audi’).
In most application scenarios the Items will be referred to by their unique ID values. In this case the
above example would be written as:

}ID=106

6.6 Clause Methods
Another powerful concept in the Perfion API are the Clause Methods, which introduce very specific
query clauses that would not be possible to write using normal query syntax.
COMPARE
The Compare Clause Method makes it possible to compare an entire group of Items to another
group of Items, e.g. to find Items that are not in another group or Items that differs on specified
feature values as compared to Items in another group.
Specificly this functionality is very useful when working with Items and their feature values at
different Life Cycle Stages.
The syntax of the COMPARE method is as follows:

19 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

<ClauseMethod id='Compare' operator='='>
<Parameter id='StageFeature' value='Stage' />
<Parameter id='KeyFeature' value='ItemNumber' />
<Parameter id='Stage1ID' value='466' />
<Parameter id='Stage2ID' value='467' />
<Parameter id='IncludeOtherID' value='1' />
<Parameter id='CompareFeatures'>
<Value>Height</Value>
<Value>Width</Value>
<Value>Cylinders</Value>
<Value>Doors</Value>
<Value>Gears</Value>
<Value>FuelCapacity</Value>
</Parameter>

</ClauseMethod>

The Operator Values of the Clause Method can be:

= Find Items that have identical Items in another Stage. (Unchanged Items)

!= Find Items that differs from Items in another Stage. (Modified Items)

IN Find Items that also exists in another Stage.

NOT IN Find Items that do not exist in another Stage. (New or Deleted Items depending upon the
direction of view).

The Parameters and their values are as follows:

StageFeature The Name or ID of a feature (defined as being Selectable) that holds a value indicating what
Stage or Group an Item belongs to.

KeyFeature The Name, ID or Property of a feature that holds a “unique” key value (e.g. such as an
ItemNumber or similar) identifying the Item.

Stage1ID The ID of an Item representing a specific Stage or Group.

Stage2ID The ID of an Item representing another specific Stage or Group.

IncludeOtherID Specifies whether to include the ID of another Item in the result-set, that is found in another
Stage with the same key value. 1 means it should be included.

CompareFeatures Specifies which features are to be compared in order to determine whether 2 Items are
identical.
If no features are specified, the 2 Items must match 100%.
If specific features are specified, the 2 Items must have identical values for these features in
order to be returned as identical.

NB: The above comparison utilises Checksums to work out the differences. This means that it is
theoretically possible for 2 Items to turn up as identical even if they are not, since their Checksums
are identical.

NB2: Binary content such as Files and Images are not compared bit-by-bit, since this would yield too
slow query performance. Only the StoredDate and ModifiedDate are used when comparing binaries.
In most cases this is sufficient evidence of equality.

6.7 Nested Clauses - AND, OR, ( … )

The Perfion SQL Syntax also offers the possibility of creating more complex queries clauses using OR
and nested with parentheses. The syntax is as follows:

20 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

<Where>
<Clause id='Category.ID' operator='=' value='354' />
<Clause id='Stage' operator='=' value='Published' />
<Sub>
<Clause id='Manufacturer' operator='NOT IN'>
<Value>Audi</Value>
<Value>Volvo</Value>
</Clause>
<Clause id='Section' operator='=' value='Audi' />
<Or/>
<Clause id='Manufacturer' operator='IN'>
<Value>BMW</Value>
<Value>Peugeot</Value>
</Clause>
<Clause id='Section' operator='=' value='BMW' />
</Sub>

</Where>

The <Sub> and <Or/> elements are used to construct nested queries.

The <Or/> element can only be used within <Sub> elements, so if OR is needed at the top level, then
the first element within the Clause must be a Sub element. This design choice allows merging of
embedded queries and extra criteria based on user choices in the application GUI.

6.8 System Variables

Instead of explicitly defining values to query for, it is also possible to use the following System
defined variables:

@@USER The currently logged in user.

@@LANGUAGE The primary language of the current user.

@@DATENOW The current Date + Time (at execution time).

The makes it possible to e.g. create a query to find all Items that has been Created by the current
user, by writing:

CreatedBy='@@USER'

21 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

7 The Perfion Query - ORDER

When no Order part is specified, all Items in the result-set are ordered ascending by the ID of the
Items.

The Order part of the query is written in the following manner:

<Order>
<By id='Manufacturer' />
<By id='EnginePower' direction='desc' />
<By id='String(EN)' />

</Order>

The following attributes are available for the <By/> element:

id The Name, ID or Property of a feature on the Items in the From part of the clause.

direction Optional. When not specified as ‘desc’ it defaults to ascending order.

In the same way as for Clauses, the ID specification may contain a Language specification, which is
interpreted as follows:

id='String' The first language specified by the language attribute on the <Select> element is used.
id='String(EN)' The specified language is used.
id='String(*)' No specific language is used

From above, when e.g. no specific language is used, and values exist for multiple languages, then
the value with the “lowest” alpha-numeric value will determine the order, e.g. the English color
‘Black’ will dominate over the German ‘Schwarz’ when ordering is ascending and the other way
around if ordering is descending.

22 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

8 The Perfion Query - HAVING

When creating customer specific catalogs or catalogs specific to other criteria (e.g. regional,
customer groups, etc.) it is easiest done by creating a Master Catalog that includes everything, and
then afterwards removing things that are not relevant for the more specific case.
Post filtering
The Perfion Where clauses are transformed into real SQL clauses against the underlying SQL
database. The biggest difference from the Where clauses is that the Having clauses are not
transformed into SQL statements but instead executed afterwards (in memory) on the result-set
retrieved from the underlying SQL database.
This means that HAVING does not allow complex Features on Features or the Hierarchy-notation
concept since both rely on data that is not found in the result-set.
Remote features
As opposed to the Where clauses, the Having clauses allows criteria on remote feature values (since
they are working directly on the the result-set).
Performance
Since the Having clauses work on the retrieved resultset, it is important to get as many criteria into
the Where clauses as possible in order to optimize performance.
Syntax
The syntax of the Having clauses are identical to the Where clauses. However, not all of the same
operations are typically needed at this stage. The following operators are currently supported for
the Having clauses.

=
!=
>
>=
<
<=
IN
HAS, NOT HAS

23 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

9 The Perfion Query - Known Issues

Hierarchy-Notation combined with Feature Wildcards
When combining Hierarchy-notation with Feature Wildcards at the innermost level it does not work,
i.e. for queries of the following type (where the Wildcard and Hierarchy-notation is applied right
before the Property):

*{String='Motor Vehicles'
(102,104,200){String='Motor Vehicles'
Category.*{String='Motor Vehicles'
Category.(102,104,200){String='Motor Vehicles'

Since the use of Feature Wildcards is used to query across multiple features and hence can be
expected to yield many results, combining this with the Hierarchy-notation would most likely yield
very poor query performance, so this combination would not be recommeded anyway.

24 of 25

Copyright 2011 Perfion
Perfion API Reference – 2.7

10 Changes

The aim of the Perfion API is that it must be backwards compatible with all previous versions.
However, sometimes it may be necessary to change something for a good reason.
This section describes specific changes since version 2.6 that may influence that may influence the
behavior of an application utilizing the API.

Result Set: Item-data Elements (e.g. Products)
1. The behavior defined by the new select option 'IncludeFeatureViewOrder' was added as the

default behavior in the previous version. However, since this behavior slows the query
execution time slightly it is no longer the default query behavior. This option must be included
for this behavior to be executed.
Implication: If you have used the feature view order to arrange features for presentation in an
application, this part of your application will fail. You will then have to alter your API queries to
include this new option.
2. If no ordering is specified (by the new Order-By functionality), the order of all the Items, are
now sorted by ID. In the previous version the order was undetermined.
Implication: None. (Comparing 2 result-sets side-by-side will show a difference).

Result Set: Feature Metadata

1. Features that are not specified in the Configuration for any of the Items returned by the query
are no longer included in the Metadata. Previously many irrelevant features were included in
the Metadata.
Implication: This will not affect you unless you have used any of these irrelevant extra features.

2. When the Query Select option 'IncludeFeatureViewOrder' is used. The Feature metadata is
sorted according to the view order of the features on the Items in the result set. If the result set
has Items with conflicting viewOrder, then the viewOrder of the first found Item in the result set
is used. If some Features are included Explicitly in the query, the order of these features are put
first in their explicit order, and the order of all other configured features are offset by the count
of explicitly included features. In previous versions the order of the Features, were to some
extent Alpha-sorted, but in a number of odd cases undetermined.
When the 'IncludeFeatureViewOrder' option is not set, then the order of the features will be
alpha-sorted, with the exception that explicitly included features will be added first in their
defined order.
Implication: None. (Comparing 2 result-sets side-by-side will show a difference).

3. A feature element is included for every language specified. Previously some could be missing if
there was no Caption in the specified language which has the consequence that some group
information could be missing.
Implication: Most likely you have been missing this information, so it will probably not affect
your application.

25 of 25