HCL Commerce Version 9.1.15.0 or later

Custom profiles

Endpoint and profile document specification

The endpoint for the profile is:
https://data_environment_hostname:30921/search/resources/api/v2/documents/profiles/profileName

For the full REST API specification, see the Query REST API.

Each profile document is in .json format and has the following structure. 

{
	"indexName": "string",
	"parentProfileName": "string",
	"profileName": "string",
	"query": {
		"highlight": {
			"fields": [
				"name",
				"fieldName"
			],
			"simplePre": "<strong><span class=font2>",
			"simplePost": "</span></strong>"
		},
		"params": [
			{
				"paramName": "value"
			}
		],
		"postprocessor": [
			"postprocessorClass"
		],
		"preprocessor": [
			"preprocessorClass"
		],
		"provider": [
			"providerClass"
		],
		"queryFields": [
			"field1",
			"filed2"
		],
		"responseFields": [
			"field1",
			"filed2"
		],
		"sortFields": {
			"key": "value"
		},
		"spellcheck": {
			"limit": "5"
		},
		"group" : {
			"enable" : "false",
			"sort" : "score desc",
			"field" : "relationship.product.group"
		},
		"hero" : {
			"overrideFieldName" : "url.thumbnail",
			"showGroupPriceRange" : "false",
			"field" : {
				"7741124012283334335" : "Hero"
			}
		}
	}
}

For a description of the field names and values, and the available pre- and post-processors, see Search profile properties.

Customization: Lookup profiles

You can use a Lookup profile if the Hero Product Image is enabled. When the term search API has grouping enabled, it uses the Lookup profile to get the group owner (parent product) details. The term search API uses the HCL_findProductsBySearchTerm profile, which has a Lookup profile property with value HCL_findCatalogEntryById. You define the Lookup profile as follows:
{
      "parentProfileName" : "",
      "profileName" : "HCL_findProductsBySearchTerm",
      "lookupProfileName" : "HCL_findCatalogEntryById",
      "indexName" : "product",
      "query" : {
Internally the SearchRelevancyByProductGroupingPostprocessor processor uses the Lookup profile to fetch the product details. Similarly, if a Hero Product Images is enabled for category browsing then the HCL_findProductsByCategory profile has the Lookup profile property with value HCL_findCatalogEntryByIdForBrowse. Internally, the SearchBrowseRelevancyByProductGroupingPostprocessor processor uses the Lookup profile to fetch the product details.
{
      "parentProfileName" : "",
      "profileName" : "HCL_findProductsByCategory",
      "lookupProfileName" : "HCL_findCatalogEntryByIdForBrowse",
      "indexName" : "product",
      "query" : {

Lookup profiles can be defined in the search profile using the lookupProfileNames property, with a key value pair. Lookup profiles are used to fetch the product sku/variant or sku/component merchandising association details for the product. For example, suppose you call the productview/byIds API with the profile HCL_findProductByIds_Details. This profile has post-processors defined to fetch the SKU, component, and merchandising association details. These post-processors use a profile to fetch the respective details.

The HCL_findProductByIds_Details profile is configured with lookup profiles. If you override the profile, ensure that you do not change the LookupProfileNames key. If no lookup profile is specified the call will fall back to the default profiles which are mentioned below in the default HCL_findProductByIds_Details profile.
{
     "profileName" : "HCL_findProductByIds_Details",
     
     "indexName" : "product",

     "lookupProfileNames" : {
          "productSKU" : "HCL_findCatalogEntrySKUs",
          "variantSKU" : "HCL_findCatalogEntrySKUsByVariantIds",
          "component" : "HCL_findCatalogEntryComponents",
          "merchandisingAssoc" : "HCL_findCatalogEntryAssociatedMerchandising"
      },

     "query" : {
SearchCatalogEntryViewSKUQueryPostprocessor
This post processor uses below tow profile to fetch the product and variant SKU details:
  • HCL_findCatalogEntrySKUs
  • HCL_findCatalogEntrySKUsByVariantIds
SearchCatalogEntryViewComponentsQueryPostprocessor
This post processor uses the HCL_findCatalogEntryComponents profile to fetch component details.
SearchCatalogEntryViewMerchandisingAssocQueryPostprocessor
This post processor uses the HCL_findCatalogEntryAssociatedMerchandising profile to fetch merchandising association details.
  • Search profiles can be customized to make use of customized lookup profiles in case you need to limit the response fields returned for sku/component/merchandising details.
  • While customizing lookup profile, do not remove the response field that starts with “relationship” from the profile.
  • lookupProfileName and lookupProfileNames are different. lookupProfileName is used to fetch the product details when a Hero Product Image is enabled, based on the sku parentId details. lookupProfileNames is used to fetch the sku/variant/component and merchandising association details.
  • You can use the provided sample custom profiles to help you limit the number of fields returned by the productview/byIds API for sku/component/merchandising details.

Using a custom lookup profile

You can create an independent custom profile without inheriting any default settings. Creating a standalone custom profile will help with editing any fields that are not required for your customers, such as response fields, providers, or post-processors. By restricting the fields you use, you can reduce attribute payload and improve efficiency. For example, you could create the following profile (the parentProfileName parameter is not a mandatory field and can be left blank):

{ "parentProfileName" : "", "profileName" : "X_findCatalogEntrySKUs",
"indexName" : "product", "query" : { "params" : [
{"maxRows" : "1200"}

], "queryFields" : ["relationship.product.id"], "provider" : [ 
      "com.hcl.commerce.search.internal.expression.provider.SearchInventoryExpressionProvider", 
      "com.hcl.commerce.search.internal.expression.provider.SearchByPublishedEntryOnlyExpressionProvider", 
      "com.hcl.commerce.search.internal.expression.provider.SearchByStorePathExpressionProvider", 
      "com.hcl.commerce.search.internal.expression.provider.SearchByCatalogExpressionProvider", 
      "com.hcl.commerce.search.internal.expression.provider.SearchByLanguageExpressionProvider", 
      "com.hcl.commerce.search.internal.expression.provider.SearchProductEntitlementExpressionProvider"], 
"preprocessor" : [], 
"postprocessor" : [
      "com.hcl.commerce.search.internal.expression.postprocessor.SearchMainCatalogEntryViewResultQueryPostprocessor",
      "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewPriceQueryPostprocessor",
      "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewUserDataQueryPostprocessor"  ], 
"responseFields" : [ "id.catentry","id.store","buyable","id.catalog","identifier.sku.raw","name.raw","name.override.raw",
"description.raw","description.override.raw","url.thumbnail","url.override.thumbnail", "url.image","url.override.image","keyword.text",
"manufacturer.raw","type","prices.","path.","relationship.product.id", "relationship.item.id","attribute.source","url.seo","attachments.", 
"images." ]
 } 
}
Note: You must restart your Query service containers after adding or updating a custom search profile.

You can also override default profiles by creating a custom profile using the same name as a default profile. If a custom profile with the same name as a default profile is available, the custom profile is used and the default profile is ignored.

Custom fields in Search Profiles

Sometimes we need to have some addition fields in response we can get that using below process. Custom fields are described in detail in Inventory and custom fields in a custom search profile (hcltechsw.com).

You can override default search profiles by creating a custom profile using the same name as the default profile. If a custom profile with the same name as a default profile is available, the custom profile is used and the default profile is ignored. For detailed steps on overriding search profiles, see Setting up your custom search profile.

  • Override the default search query profile to include the additional seller_description.raw attribute in the query response.
  • Extend the default HCL_findCatalogEntrySKUs search profile by adding seller_description.raw into the responseFields section of the existing search profile.
    GET http://QUERY_HOST:30920/search/resources/api/v2/documents/profiles/HCL_findCatalogEntrySKUs
  • Execute the GET call to retrieve the default query profile, and execute the PUT call to create the custom query profile using the response of the GET call as a request Body after adding the seller.description.raw attribute in JSON. This would extend the default query profile as follows:
    GET http://QUERY_HOST:30920/search/resources/api/v2/documents/profiles/HCL_findCatalogEntrySKUs

PUT http://QUERY_HOST:30920/search/resources/api/v2/documents/profiles/HCL_findCatalogEntrySKUs

[
    {
        "profileName": "HCL_findCatalogEntrySKUs",
        "indexName": "product",
        "query": {
            "params": [
                {
                    "maxRows": "1200"
                }
            ],
            "queryFields": [
                "relationship.product.id"
            ],
            "provider": [
                "com.hcl.commerce.search.internal.expression.provider.SearchInventoryExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchByPublishedEntryOnlyExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchByStorePathExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchBySellerExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchByCatalogExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchByLanguageExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchProductEntitlementExpressionProvider"
            ],
            "preprocessor": [],
            "postprocessor": [
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchMainCatalogEntryViewResultQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewPriceQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewUserDataQueryPostprocessor"
            ],
            "responseFields": [
                "id.catentry",
                "id.store",
                "buyable",
                "id.catalog",
                "identifier.sku.raw",
                "name.raw",
                "name.override.raw",
                "description.raw",
                "description.override.raw",
                "url.thumbnail",
                "url.override.thumbnail",
                "url.image",
                "url.override.image",
                "keyword.text",
                "manufacturer.raw",
                "id.member",
                "seller.raw",
                "seller_description.raw",
                "type",
                "prices.*",
                "path.*",
                "relationship.product.id",
                "relationship.item.id",
                "attribute.source",
                "url.seo",
                "url.override.seo",
                "attachments.*",
                "images.*",
                "description.long"
            ]
        }
    }
]
The response should be similar to:
{
"Profile created with name":
"HCL_findCatalogEntrySKUs"
}
Repeat this step for the HCL_V2_findProductByPartNumber_Details search profile by adding seller_description.raw into the responseFields section of the existing search profile.

          GET http://QUERY_HOST:QUERY_PORT/search/resources/api/v2/documents/profiles/HCL_V2_findProductByPartNumber_Details

Add seller_description.raw into the responseFields section of the existing search profile to use it as a request body for the below PUT call to override the default HCL_V2_findProductByPartNumber_Details search profile.

PUT http://QUERY_HOST:30920/search/resources/api/v2/documents/profiles/HCL_V2_findProductByPartNumber_Details
{
        "profileName": "HCL_V2_findProductByPartNumber_Details",
        "indexName": "product",
        "query": {
            "params": [
                {
                    "DynamicKitReturnPrice": "true"
                },
                {
                    "maxRows": "50"
                }
            ],
            "queryFields": [
                "identifier.sku.normalized"
            ],
            "provider": [
                "com.hcl.commerce.search.internal.expression.provider.SearchByCatalogExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchByStorePathExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchBySellerExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchByLanguageExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchInventoryExpressionProvider",
                "com.hcl.commerce.search.internal.expression.provider.SearchProductEntitlementExpressionProvider"
            ],
            "preprocessor": [],
            "postprocessor": [
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchMainCatalogEntryViewResultQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewPriceQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewSKUQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewAttributesQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewAttachmentsQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewImagesQueryPostProcessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewComponentsQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewMerchandisingAssocQueryPostprocessor",
                "com.hcl.commerce.search.internal.expression.postprocessor.SearchCatalogEntryViewUserDataQueryPostprocessor"
            ],
            "responseFields": [
                "id.catentry",
                "id.store",
                "id.catalog",
                "buyable",
                "identifier.sku.raw",
                "name.raw",
                "name.override.raw",
                "description.raw",
                "description.override.raw",
                "url.thumbnail",
                "url.override.thumbnail",
                "keyword.text",
                "manufacturer.raw",
                "id.member",
                "seller.raw",
                "seller_description.raw",
                "type",
                "prices.*",
                "path.*",
                "relationship.item.*",
                "relationship.product.id",
                "relationship.component.*",
                "subscription.type",
                "subscription.recurring",
                "url.image",
                "url.override.image",
                "description.long",
                "attribute.source",
                "kit.components",
                "kit.preconfigured",
                "kit.model",
                "kit.URL",
                "kit.default_configuration",
                "kit.pdks",
                "kit.parent.model",
                "kit.configurable",
                "kit.parent.configurable",
                "associations.*",
                "url.seo",
                "attachments.*",
                "images.*"
            ]
        }
    }
The response should resemble:
{
  "Profile created with name": "HCL_V2_findProductByPartNumber_Details"
}

Restart the Query Service container.

Test the customization to verify that the customization is successful.