GetCategories
- Morten Lindequist Køhler
- Michael Engesgaard
The GetCategories-request resemble the GetProducts-request very much. In fact, most of the parameters are shared between the two.
GetCategories | |||
Parameters | Name | Mandatory | Description |
Channel | Yes | The channel you want categories from must be supplied. | |
Keys | No | The list of KeyField values for the categories you want fetched. If no Keys supplied, all categories will be fetched. | |
SiteKey | No | Only fetch categories for some site denoted by is KeyField. | |
IncludeMappings | No | Specifies which mappings should be included for the fetched categories. 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 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. | |
FlattenHierarchy | No | When set to true, sub categories will no longer be output as child elements of their parents but all in one big list. Parenthood can still be determined by looking at the output parented-attribute. | |
TimeZone | No | Available from Perfion 4.7 this parameter allows you to control in which time zone that is 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 Mapping |
| ||
Sample Data |
| ||
Sample Request | <Execute method="GetCategories" refreshconfiguration="true">
<Parameter id="Channel" value="My Channel" />
<Parameter id="IncludeMappings">
<Value>CatId</Value>
<Value>Name</Value>
</Parameter>
<Parameter id="SiteKey" value="Site A" />
</Execute> | ||
Sample result | <Response>
<Result>
<Channel name="My Channel">
<Categories>
<Category id="1084" parentid="0">
<Fields>
<Field name="CatId">1084</Field>
<Field name="Name" culture="en-US">My Site</Field>
</Fields>
<Categories>
<Category id="1080" parentid="1084">
<Fields>
<Field name="CatId">1080</Field>
<Field name="Name" culture="en-US">Coffee</Field>
</Fields>
<Categories>
<Category id="1081" parentid="1080">
<Fields>
<Field name="CatId">1081</Field>
<Field name="Name" culture="en-US">Brewing</Field>
</Fields>
<Categories />
</Category>
<Category id="1082" parentid="1080">
<Fields>
<Field name="CatId">1082</Field>
<Field name="Name" culture="en-US">Keeping warm</Field>
</Fields>
<Categories />
</Category>
<Category id="1083" parentid="1080">
<Fields>
<Field name="CatId">1083</Field>
<Field name="Name" culture="en-US">Accessories</Field>
</Fields>
<Categories />
</Category>
</Categories>
</Category>
</Categories>
</Category>
</Categories>
</Channel>
</Result>
</Response> | ||
Table 1: GetCategories-method.
Note in Table 1 that only CatId and Name is output. Note further that hierarchy is built into the result in two ways:
Structural, i.e. a category has in a Categories-element its subcategories. This can be omitted by using the FlattenHierarchy-parameter as described in Section GetCategories.
By id and parentid. A category will as parentid point to its parent-category except when it has no in which parentid would be 0.
The following parameters are shared with GetProducts meaning that Channel, IncludeMappings, ExcludeMappings ForceBinaryOutputKind, IncludeModificationDates, IncludePerfionNamesOnFields and RemoveUnwantedFeaturesByConfiguration work for categories exactly as they do for products. If you need info on any of these please go to appropriate sub-section of section GetProducts.
The remaining Parameters supported will be described in sections below.
GetCategories: Keys-Parameter
The Keys-parameter works for categories as they do for Products. There is a small pitfall using it on categories, though, since it will only fetch a single category when used on a KeyField (assuming this holds a unique value). This means that you will not get any sub-categories for this single category (unless they share the same Key).
In most cases, however, you would just want to retrieve all categories.
GetCategories: SiteKey-Parameter
In case you have more sites in your category structure, as seen on below, you can ask for only categories from a particular site.
Example: The following request fetches only categories for site with a key value of “Site B”:
<Execute method="GetCategories" refreshconfiguration="true">
<Parameter id="Channel" value="My Channel" />
<Parameter id="SiteKey" value="Site B" />
</Execute>NOTE: This requires you to have a KeyField-mapping on Site-entity.
GetCategories: FlattenHierarchy-Parameter
As can be seen in Table 1 the ECommerce API outputs categories hierarchically. In case you want to have categories in a flat element-list instead (using id/parentid-relationship to determine hierarchy) you can use the FlattenHierarchy-parameter:
Sample Data |
|
Sample Request | <Execute method="GetCategories" refreshconfiguration="true">
<Parameter id="Channel" value="My Channel" />
<Parameter id="SiteKey" value="Site B" />
<Parameter id="IncludeMappings">
<Value>CatId</Value>
<Value>Name</Value>
</Parameter>
<Parameter id="FlattenHierarchy" value="true" />
</Execute> |
Sample result | <Response>
<Result>
<Channel name="My Channel">
<Categories>
<Category id="1172" parentid="0">
<Fields>
<Field name="CatId">1172</Field>
<Field name="Name" culture="en-US">My US Site</Field>
</Fields>
</Category>
<Category id="1174" parentid="1172">
<Fields>
<Field name="CatId">1174</Field>
<Field name="Name" culture="en-US">Cars</Field>
</Fields>
</Category>
<Category id="1175" parentid="1174">
<Fields>
<Field name="CatId">1175</Field>
<Field name="Name" culture="en-US">Audi</Field>
</Fields>
</Category>
<Category id="1176" parentid="1174">
<Fields>
<Field name="CatId">1176</Field>
<Field name="Name" culture="en-US">BMW</Field>
</Fields>
</Category>
<Category id="1177" parentid="1174">
<Fields>
<Field name="CatId">1177</Field>
<Field name="Name" culture="en-US">Peugeot</Field>
</Fields>
</Category>
</Categories>
</Channel>
</Result>
</Response> |
Table 2: GetCategories-output is flattened using the FlattenHierarchy-parameter