GetProducts

GetProducts is by far the most important method in EC. As the name implies it allows you to retrieve products from EC.

In this section, we will walk through this method and all the parameters supported by it.

GetProducts
Parameters	Name	Mandatory	Description
	Channel	Yes	The channel you want products from. This must be supplied.
	Keys	No	The list of KeyField values for the products you want fetched. If no Keys supplied, all products will be fetched.
	Index	No	Index for the first product you want fetched.
	MaxCount	No	Max number of products you want fetched
	IncludeMappings	No	Specifies which mappings should be included for the fetched products. If nothing is specified here all mappings are included.
	ExcludeMappings	No	Specifies which mappings should be excluded. If nothing is specified here, it is assumed to that no mappings are excluded.
	ForceBinaryOutputKind	No	How binaries are output is controlled on the mapping. This parameter overrides that setting on the mapping and forces binaries to be output as specified. Possible values are None, Url, File and Embedded.
	IncludeModificationDates	No	When set to true, modification dates will be output on all elements in result.
	IncludePerfionNamesOnFields	No	When set to true, the name of the feature from which a field comes from is added to output.
	IncludePerfionItemIdsOnSelectables	No	When set to true, the id of a selectable feature output to a Field will be added to the output.
	RemoveUnwantedFeaturesByConfiguration	No	When set to true, a wild-card mapping will only return Features/Fields which are configured for each individual item.
	OrderBy	No	Allows you to order products by a field- or feature-name.
	SiteKey	No	Only fetch products that are in the site denoted by its KeyField.
	CategoryKeys	No	Allows you to fetch products only in the specified categories.
	ModifiedFrom	No	Allows you to fetch only those products that are modified after supplied date time.
	ModifiedTo	No	Allows you to fetch only those products that are modified before supplied date time.
	TimeZone	No	Available from Perfion 4.7 this parameter allows you to control in which time zone “ModifiedFrom”- and “ModifiedTo”-parameters are expressed in. Furthermore it controls the time zone used to output modification dates when IncludeModificationDates is enabled. If this parameter is not supplied, the time zone supplied in Settings will be used (See section Timezone). If no time zone is supplied here either, the time zone of the Perfion Database will be used. This was also the time zone used by the EC API in earlier versions of Perfion.
	OutputMultiValueFieldsIndividually	No	Available from Perfion 2024 R1 SR2: You can now output multi value features mapped to Fields as individual Fields-elements instead of the default of Value-subelements or a value attribute.
Sample Data	Open
Sample request	<Execute method="GetProducts" refreshconfiguration="true">   <Parameter id="Channel" value="My Channel" />   <Parameter id="Keys">     <Value>DFGR1181</Value>     <Value>DFGR1280</Value>   </Parameter>   <Parameter id="IncludeMappings">     <Value>Item No</Value>     <Value>Title</Value>   </Parameter> </Execute>
Sample result	<Response>   <Result>     <Channel name="My Channel">       <TotalCount ignoringpaging=”2”>2</TotalCount>       <Products>         <Product id="623" ecommerceproduct="DFGR1181">           <Fields>             <Field name="Item No">DFGR1181</Field>             <Field name="Title" culture="en-US">Grindenstein Knock-Box, Black</Field>             <Field name="Title" culture="de-DE">Grindenstein Knock-Box, Schwarz</Field>           </Fields>         </Product>         <Product id="622" ecommerceproduct="DFGR1280">           <Fields>             <Field name="Item No">DFGR1280</Field>             <Field name="Title" culture="en-US">Grindenstein Knock-Box, Red</Field>             <Field name="Title" culture="de-DE">Grindenstein Knock-Box, Rot</Field>           </Fields>         </Product>       </Products>     </Channel>   </Result> </Response>

Table 1: GetProducts-method.

In the following sections all possible parameters for GetProducts-method will be described.

GetProducts: Channel-parameter

The channel parameter needs to be supplied in order to tell EC which channel to retrieve products from. See more on channels.

GetProducts: Keys-parameter

The Keys allows you to retrieve only products with the keys supplied.

Consider the following figure showing the KeyField-mapping on the Product-entity:

Open

The following EC-request will fetch exactly these two products (assuming no other products share the same base-value as any of the two):

The above request indeed relies on the KeyField-mapping to find that it maps to the base-value of the Product in Perfion. You can also tell EC which FieldName to use instead of the KeyField. The below request is equivalent to the above:

Notice how fieldname is specified as an attribute on the Keys-parameter. Doing this allows you to do a request using Keys-parameter even without having defined a KeyField-mapping on the product-entity. You, however, must have a Field defined, otherwise EC do not know which feature it maps from. Without such a mapping, you can actually still fetch products, now based on their feature name. The below request is equivalent to the above:

Notice here how the featurename-attribute tells EC that you want products that has a feature named Value (the base-value) set to any of the supplied values. This does not require any mapping. In fact, the EAN-number in the top screenshot is not mapped in EC, but EC still allows you to make the following request, which again is equivalent to the previous queries:

Finally, EC allows you to ask for products by their Perfion ID. That can be done using feature name “PerfionID” as demonstrated by the below request:

GetProducts: Index- and MaxCount-parameters

These two parameters allows you to fetch only a specific part of the result set, a page of products. The following example fetches the first 20 products:

If you successfully retrieve 20 products, you should follow up with the following request fetching the next 20:

You should continue doing that you find anything less than 20 products denoting that there are no more products in result set. Note: The final request may return 0 (zero) products.

Theoretically speaking the Perfion API and hereby the EC API may return products in any order they like, when no ordering is applied. So when requesting paged data, it is recommended to apply an ordering as well, so that you are sure that all products eventually are returned at some point.

Furthermore from version 4.7.9/4.8.2 retrieving products will return two Total Counts. The one we know, that tells how many entities that were fetched by the method call and an attribute telling how many that would have been fetched, if we did not apply any paging. The “TotalCount”-element is simply looking like this:

The above simply tells us, that we have just fetched 1.000 products and we would have gotten 39.973 product, if it were not for the supplied paging-parameters. Note that the ignorepaging-attribute is always returned, even if you do not apply paging. In that that it will simply be the same count as the original total count.

GetProducts: IncludeMappings- and ExcludeMappings-parameters

EC will normally retrieve data for all mappings on Products. In case you only need data on some of these mappings, you can tell EC that, by using either the IncludeMappings-parameter or the ExcludeMappings-parameter.

The IncludeMappings-parameter allows you to include only a subset of all mappings.

The above request fetches only data for mappings with a “To” set to Item No, Title and Main Image. As illustrated in Figure 8, this corresponds to features Value, ItemName and Image.

The ExcludeMappings-parameter does the exact opposite of the IncludeMappings-parameter. The former allows you to retrieve data from all mappings, except those mentioned in ExcludeMappings.

The above request will retrieve all mappings for products except mappings for Accessories and Manual.

You can choose to Exclude a *-mapping. This will exclude all mappings only returning the entity without any mappings on.

This is mainly for debugging purposes to see whether the correct products are returned. 

GetProducts: ForceBinaryOutputKind-parameter

There are three ways images and attachments can be output: Url, File and Embedded. It is all controlled by a parameter on the Output Kind.

In case you for some reason want to override that behavior, you can in a request override the output kind parameter and enforce another output kind. This is achieved using the ForceBinaryOutputKind-parameter as detailed in table

Table 2: The four different options for setting the ForceBinaryOutputKind.

GetProducts: IncludeModificationDates-parameter

Setting this parameter to true, will output all data including a timestamp specifying on which date it was last modified. This is useful; if you want to, on a data unit basis, make sure only to modify what has been changed since last request.

Note: For literals, the date output will be the last modified date of the Mapping containing the literal. All products will hereby have the same last modified date for the same literal. It makes sense, since a literal is last modified on a product when it was updated on the mapping.

Table 3: Sample usage of "IncludeModificationDates" on GetProducts.

GetProducts: IncludePerfionNamesOnFields-parameter

Perfion names are always output on all mappings except for Field and KeyField. This is mainly because data from multiple features of most other output kinds, can be grouped by mapping them to the same “To”-name. The perfionname is not output on Fields and KeyFields due to space-considerations.

For debugging (and other) purposes, it is possible to ask EC to include the perfionname also on Fields and KeyFields. You do that simply by setting the IncludePerfionNamesOnFields-parameter to ‘true’, as can be seen in the following example:

Table 4: Sample usage of "IncludePerfionFeatureNames" on GetProducts.

GetProducts: IncludePerfionItemIdsOnSelectables-parameter

Introduced in Perfion 4.8.17, Perfion 4.9.7 and 4.10.1: Setting a parameter named IncludePerfionItemIdsOnSelectables to true will add the item id of any selectable feature value output to a field to the output. An example is shown in table Table 5 below:

Table 5: Sample usage of "IncludePerfionItemIdsOnSelectables" on GetProducts.

Notice in the table how the selectable features Color and Tags both get an itemid-attribute added to all their elements holding values. “Color”, being Single value, will have its “itemid”-attribute added to the “Field”-element itself, while “Tags”, being multivalued, will, for each of its Value-elements have item id output on each “Value”-element.

GetProducts: RemoveUnwantedFeaturesByConfiguration-parameter

This parameter was introduced in Perfion 4.10 SR3 (4.10.5). This behavior of this parameter highly resembles the same named option in the Perfion API.

RemoveUnwantedFeaturesByConfiguration affects only the result for an ECommerce method, if the mapping holds a *- or **-mapping. This is because only these mappings fetches “configured”-features. All other (so called explicit) mappings are always fetched regardless of this parameter. Furthermore the parameter is only interesting, if the configuration on the base-feature (often named “Product”) has at least one Item Dependent feature, that is, has some Item Dependencies that tells which Product have which sets of features. Almost all installations of Perfion uses Item Dependent Features, and most will use only one. We need an Item Dependency-feature in order for various products to contain various configured feature sets as can be seen in the following two examples.

First consider the following very simple configuration for a base-feature named Vehicle alongside two vehicles: a car and a bus:

Table 6: Sample setup that will be used to demonstrate the effect of “RemoveUnwantedFeaturesByConfiguration”

First take a look at the configuration of “Vehicle”. It has a name feature followed by “VehicleCategory”, where the latter is an Item Dependency-feature. We have currently only two values for that feature: “Cars” and “Busses”. Both have a “Fuel”-feature, but notice that it is only part of “WebDetail” for Cars. This will be important later.

Then look at the Mappings for our “VehicleChannel”. First We map the base-feature “Vehicle” as our context and we select the WebDetail view. See more in Section on the Context-mapping. Then we explicitly map the base-value to a field named “SKU”. Finally we have our *-mapping, mapping everything in WebDetail in the configuration of the “Vehicle”.

Finally we have two vehicles: A bus and a car. As can be seen all features have a value for both vehicles.

The setup shown in Table 6 will now be used to demonstrate the effect of “RemoveUnwantedFeaturesBy­Configuration”. First example describes what is returned if not set. Second example sets it (to “true”) and describes what then happens

Example: Without “RemoveUnwantedFeaturesBy­Configuration”

Without “RemoveUnwantedFeaturesByConfiguration” the ECommerce API will create a fixed list of all features needed to fetch. In the example it is all features in the configuration that has a checkmark set in WebDetail. As can be seen from Table 6 that is the 3 features “Name”, “VehicleCategory” and “Fuel”. “Fuel” is included, since there is a checkmark for “Fuel” somewhere in the configuration, which here is for “Cars”. So without “RemoveUnwantedFeaturesByConfiguration” the *-mapping will fetch “Name”, “VehicleCategory” and “Fuel” for all products. In other words: The configuration is looked upon as a whole, not taking each product into consideration.

Table 7 shows this. Here we do a call to GetProducts fetching all products in the “VehicleChannel” without the “RemoveUnwantedFeaturesByConfiguration”-parameter set. As can be seen from Table 6, we have our two vehicles in that channel.

Table 7: The result of calling GetProducts on the data shown in Table 6 without “RemoveFeaturesByConfiguration”.

And, as can be seen, the result indeed contains these 2 vehicles. And indeed all 3 features “Name”, “VehicleCategory” and “Fuel” are fetched, alongside the explicitly mapped “SKU”.

Example: With “RemoveUnwantedFeaturesBy­Configuration” (set to “true”)

Let us see what happens, if we set the parameter “RemoveFeaturesByConfiguration” to true. The result is shown in Table 29 below:

Table 8: The result of calling GetProducts in the data shown in Table 6 with “RemoveFeaturesByConfiguration”.

Notice that the bus no longer gets the field “Fuel” returned, despite the fact that it holds a value (“Diesel”). This is because the “RemoveFeaturesByConfiguration”-parameter instructs the ECommerce API to evaluate each product individually and only return the features, which are in the configuration for that specific product. Since the bus is in “VehicleCategory” named “Busses” as seen in Table 27, field “Fuel” will simply not be returned for the “Bus”.

GetProducts: OrderBy-parameter

When requesting data from EC you cannot know in which order data is returned unless you specify an “OrderBy”-parameter.

This first example will order products by their key:

Per default, products will be ordered in ascending order alphabetically. You can change the direction of the order in the following manner:

You can also order products based on any field-mapping specified either by its field-name:

or by its feature name:

You can even order by a localizable feature like this, here sorting on its German-value:

GetProducts: SiteKey

In case you have more sites you can ask for only products from a particular site.

Example: The following request fetches only products for site with a key value of “Site B”:

As with the Keys-parameter you can use either the fieldname- or featurename-attribute to specify another field/feature than the KeyField-mapping.

GetProducts: CategoryKeys

This parameter allows you to request only products that are in some category specified by its category-key(s).

The above example will fetch all products in the category with KeyField-mapping set to 1083.

As with the Keys-parameter you can use either the fieldname- or featurename-attribute to specify another field/feature than the KeyField-mapping.

GetProducts: ModifiedFrom- and ModifiedTo-parameters

The ModifiedFrom- and ModifiedTo-parameters are used to fetch only products that are modified with a certain timespan. Consider the following request:

This will return the “Item No” and “Title” for all products modified between 13:00:00 and 14:00:00 on February 12, 2018.

A few notes of when a product is modified:

• A “Product” in Perfion is considered modified if any feature on it has changed its value. This even holds for features not part of any mapping. If you want only to consider features involved in mappings, you should retrieve the products and look at their “lastmodified”-timestamps as described in section GetProducts.

• Remote-features are not considered. Indeed a price or stock quantity may have changed in the ERP-system without Perfion knowing.

GetProducts: OutputMultiValueFieldsIndividually-parameter

When the ECommerce API ouputs multi values as Fields it will do it in one of two ways:

1. If there is more than one value, it will create one Value-subelement to the Field-element per value.

2. If there is exactly one value, it will add a value attribute to the Field-element holding the value.

Both can be seen here:

Using the OutputMultiValueFieldsIndividually-parameter you can force the ECommerce API to return its result as the value of a Field-element, one element per value. This is chosen regardless of how many values there are: