Explaining Configuration in Oracle Commerce Cloud Search

Published in

Oracle Developers

4 min readJun 17, 2019

With Oracle Commerce Cloud search, we expose a lot of configuration to the user via the /gsadmin API. However, included in all of that configuration is some that 1) implementors just should not touch or 2) should be very careful in modifying.

This article is going to discuss the different areas of configuration that you can access via /gsadmin/v1/cloud, explain them a bit and tell you which ones to avoid modifying. We will also discuss the best approaches for modifying attributes, and what you should avoid.

Quick Background on upgrades and migration

We are constantly adding new features to GS with every release. Included in some of those new features is a new configuration that sits aside or updates the existing configuration.

For instance, when we added Dynamic Curation and Boost&Bury, we added configuration to /gsadmin/v1/cloud/pages/Default/services/guidedsearch. The same was true in 18D when advanced support was added for multi-catalogs and multi-site.

As search is upgraded, scripts are executed to merge that new configuration into the existing configuration.

A few things to point out:

New configurations can and will show up as we add features
You need to take steps to not remove that configuration.

For instance, you can back up your configuration by executing GET /gsadmin/v1/cloud.zip, and restore it using POST. However, if you took a 18D backup and then restored it against 19B, you will lose some of that migrated configuration.

Understanding Attributes and ownership

As of 18D, if you execute GET /gsadmin/v1/cloud/attributes, you will see three folders: /system, /ATG, and /keywords. We call each of these “owners” for the attributes underneath them.

I will be fully honest, the names for “system” and “ATG” are not ideal, and if we could do it over, we would definitely change them. But let’s discuss what these are:

/ATG: As you might know, Oracle Commerce Cloud had it’s origins in the ATG commerce platform. Every time indexing takes place, the admin server will re-export all of the ATG attributes, deleting any that were there previously. Thus, these system-managed attributes, and shouldn’t be touched.
/system: This is a set of attributes that ships out of the box, and is necessary for indexing to occur. However, despite the name, these are not managed by the system per se. You can modify these attributes, create new attributes, update attributes found under /ATG. These attributes are not deleted during indexing and persist.
/keywords: These are a new set of attributes added in 18D to support the popular searches feature.

Okay, so let’s give clear guidance here:

Don’t touch attributes under /ATG. It just won’t work. They get deleted and recreated during indexing, so your changes won’t persist.
You can touch /keywords, but don’t. Let’s leave these for future enhancements.
If you are creating entirely new attributes, create your own folder. (Or you can place them under /system, but we are pushing folks to use their own folder)
If there are attributes under /ATG that you wish to modify, those modifications should be under /system

So again, don’t touch anything under /ATG.

If you want to see the final set of attributes that gets used for indexing, you can execute /gsadmin/v1/attributes.merge.json

One final note: Changes to attributes are schema-level changes, and require a baseline index to take effect. I discussed indexing previously in “Understanding Indexing in Oracle Commerce Cloud Search”

Modifying attributes

Let’s take a brief aside when it comes to modifying attributes.

In Oracle Commerce Cloud search (as we mentioned above), when the catalog gets exported to search, the system will recreate the attributes under /attributes/ATG, and therefore you can’t modify those in that location.

Instead, if we want to tweak those attributes, we would place those modifications under /attributes/system, and specify “mergeAction” : “UPDATE”.

For instance, if you wanted to take a property under /attributes/ATG and enable it for record filtering, your JSON under /attributes/system might look something like:

"product.x_customAttribute" : {
  "propertyDataType" : "ALPHA",
  "ecr:type" : "property",
  "isRecordFilterable" : true,
  "mergeAction": "UPDATE" },

To summarize:

Don’t modify anything under /attributes/ATG. It either won’t work or won’t persist over time
If you want to modify an attribute from /attributes/ATG, place it under /attributes/system with “mergeAction”: “UPDATE” along with your changes
Perform GET /gsadmin/v1/cloud/attributes.merge.json to preview your changes. If this errors out, undo your changes.
/gsadmin/v1/cloud/attributes.merge.json is a view that takes into account all of the attribute owners and presents the final merged view. This is what Search looks at when indexing.
Changes to attributes require a baseline index since these are schema-level changes

Configuration to leave alone

Here is a list of folders to leave alone. Some of these aren’t available by REST and are accessed by executing GET /gsadmin/v1/cloud.zip.

/attributeContexts: Some attributes (such as product.category, product.displayName, pricing) are contextual. Meaning, the values on the products can vary based on the locale or price list group. This configuration holds different contexts. We don’t support adding contexts
/workspaces, /editors, /templates, /tools, /configuration: As many of you know, Search for Oracle Commerce Cloud is built off of Oracle Commerce Guided Search (previously Endeca) for on-premise. This configuration is used primarily for on-premise but still exists for the cloud. Just leave it alone.
/precedenceRules/ATG and /precedenceRules/Analytics: Precedence rules are used to control when facets show up. For instance, “don’t show Brand until Category is selected”. There are no precedence rules under /ATG typically, but even so, that is managed by the system. The /Analytics set is used to prevent a few internal facets from showing up on the site. In both cases, don’t touch. We also don’t recommend the use of precedenceRules since they require a baseline index, and aren’t flexible when it comes to Dynamic Curation, etc. Instead, there are other facet management APIs available that should be used and don’t require indexing.