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 |
 | ||||
Sample request |
| ||||
Sample result |
| ||||
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:
The following EC-request will fetch exactly these two products (assuming no other products share the same base-value as any of the two):
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Keys"> <Value>DFGR1280</Value> <Value>DFGR1181</Value> </Parameter> </Execute> |
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:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Keys" fieldname='Item No'> <Value>DFGR1280</Value> <Value>DFGR1181</Value> </Parameter> </Execute> |
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:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Keys" featurename='Value'> <Value>DFGR1280</Value> <Value>DFGR1181</Value> </Parameter> </Execute> |
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:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Keys" featurename='EANCode'> <Value>9334084001181</Value> <Value>9334084001280</Value> </Parameter> </Execute> |
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:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Keys" featurename='PerfionId'> <Value>623</Value> <Value>622</Value> </Parameter> </Execute> |
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:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Index" value="0" /> <Parameter id="MaxCount" value="20" /> </Execute> |
If you successfully retrieve 20 products, you should follow up with the following request fetching the next 20:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="Index" value="20" /> <Parameter id="MaxCount" value="20" /> </Execute> |
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:
| Code Block |
|---|
<TotalCount ignoringpaging="39973">1000</TotalCount> |
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.
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="IncludeMappings"> <Value>Item No</Value> <Value>Title</Value> <Value>Main Image</Value> </Parameter> </Execute> |
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.
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="ExcludeMappings"> <Value>Accessories</Value> <Value>Manual</Value> </Parameter> </Execute> |
The above request will retrieve all mappings for products except mappings for Accessories and Manual.
| Info |
|---|
NOTE: If you, by mistake, both include and exclude some mapping, it will be excluded. |
You can choose to Exclude a *-mapping. This will exclude all mappings only returning the entity without any mappings on.
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="ExcludeMappings" value="*" /> </Execute> |
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
ForceBinaryOutKind-Parameter | Description |
Not set at all | This will output all binaries as specified on each mapping. |
<Parameter id="ForceBinaryOutputKind" value="None" /> | This will enforce that no binaries are output at all. |
<Parameter id="ForceBinaryOutputKind" value="Url" /> | This will output all binaries as if “Url” was specified on their mappings. |
<Parameter id="ForceBinaryOutputKind" value="File" /> | This will output all binaries as if they had “File”-specied on their mappings without any file-pattern. As ConstructedFileName their Guid with the appropriate file extension will be used. |
<Parameter id="ForceBinaryOutputKind" value="Embedded" /> | This will output all binaries as if “Embedded” was specified on their mappings. |
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.
GetProducts using IncludeModificationDates-parameter | ||
Sample Data | ||
  | ||
Sample Request | ||
| ||
Sample Result | ||
|
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:
GetProducts using IncludePerfionNamesOnFields-parameter | ||
Sample Request | ||
| ||
Sample Result | ||
|
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:
GetProducts using IncludePerfionItemIdsOnSelectables-parameter | ||
Sample Data | ||
| ||
Sample Request | ||
| ||
Sample Result | ||
|
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:
Sample Configuration |
|
Sample Mappings |
|
Sample Vehicles |
 
|
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 “RemoveUnwantedFeaturesByConfiguration”. First example describes what is returned if not set. Second example sets it (to “true”) and describes what then happens
Example: Without “RemoveUnwantedFeaturesByConfiguration”
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.
Sample Request | ||
| ||
Sample Result | ||
|
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”.
| Info |
|---|
Note on the Perfion API The Perfion API works similarly when selecting a * scoped to view “WebDetail”, at least if it has both a Car and Bus in the result of the query. BUT if you did another Perfion API query that happened only to find busses, then Fuel will not be retrieved. On the opposite side: If there, together with the busses, is at least one car, then this car will make the Perfion API also retrieve the “Fuel”-feature and since this feature has data for our busses, the value for “Fuel” will be fetched for them as well.
In other words: The Perfion API looks at the combined configuration for the result of the query, while the ECommerce API looks at the configuration only assuming that all Item Depency-values will be met. |
Example: With “RemoveUnwantedFeaturesByConfiguration” (set to “true”)
Let us see what happens, if we set the parameter “RemoveFeaturesByConfiguration” to true. The result is shown in Table 29 below:
Sample Request | ||
| ||
Sample Result | ||
|
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”.
| Info |
|---|
Note on the Perfion API The Perfion API does the exact same thing when using the option “RemoveFeaturesByConfiguration”. This option has, as opposed to the ECommerce API, more or less always been in the Perfion API. |
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:
| Code Block |
|---|
<Parameter id="OrderBy" /> |
Per default, products will be ordered in ascending order alphabetically. You can change the direction of the order in the following manner:
| Code Block |
|---|
<Parameter id="OrderBy" direction="Desc" /> |
You can also order products based on any field-mapping specified either by its field-name:
| Code Block |
|---|
<Parameter id="OrderBy" fieldname="Title" /> |
or by its feature name:
| Code Block |
|---|
<Parameter id="OrderBy" featurename="ItemName" /> |
You can even order by a localizable feature like this, here sorting on its German-value:
| Code Block |
|---|
<Parameter id="OrderBy" featurename="ItemName(DE)" /> |
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”:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="SiteKey" value="Site B" /> </Execute> |
| Info |
|---|
NOTE: This requires you to have a KeyField-mapping on Site-entity. |
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).
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="CategoryKeys" value="1083" /> <Parameter id="IncludeMappings"> <Value>Item No</Value> <Value>Title</Value> </Parameter> </Execute> |
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:
| Code Block |
|---|
<Execute method="GetProducts" refreshconfiguration="true"> <Parameter id="Channel" value="My Channel" /> <Parameter id="ModifiedFrom" value="2018-02-12T13:00:00" /> <Parameter id="ModifiedTo" value="2018-02-12T14:00:00" /> <Parameter id="IncludeMappings"> <Value>Item No</Value> <Value>Title</Value> </Parameter> </Execute> |
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:
If there is more than one value, it will create one Value-subelement to the Field-element per value.
If there is exactly one value, it will add a value attribute to the Field-element holding the value.
Both can be seen here:
| Code Block |
|---|
<Fields>
<Field name="MultiValueLocalizable" culture="en-US">
<Value>Value A</Value>
<Value>Value B</Value>
<Value>Value C</Value>
</Field>
<Field name="MultiValueLocalizable2" culture="en-US" value="My only value" />
</Fields> |
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:
| Code Block |
|---|
<Fields>
<Field name="MultiValueLocalizable" culture="en-US">Value A</Field>
<Field name="MultiValueLocalizable" culture="en-US">Value B</Field>
<Field name="MultiValueLocalizable" culture="en-US">Value C</Field>
<Field name="MultiValueLocalizable2" culture="en-US">My only value</Field>
</Fields> |
| Table of Contents |
|---|