Configure keyword redirects
This section describes keyword redirects and how to export, create, replace, and modify keyword redirect configuration using the Search Admin and Configuration REST API.
It includes the following topics:
Understand keyword redirects
You can configure your application to send a storefront shopper to a particular URL when the shopper enters a particular search term. The URL can represent a static page in your application (such as an “About Us” page) or a specific search or navigation state. This type of configuration is known as a keyword redirect.
You can configure any number of search terms to redirect the shopper to a particular URL. For example, you can configure the search terms “delivery” and “shipping” to redirect shoppers to a URL such as http://shipping.example.com
.
Configure keyword redirects for multiple sites
If your instance of Oracle Commerce is running multiple sites, you can configure keyword redirects differently for the
different sites by using the siteIds
attribute. A redirect entry created
without the siteIds
attribute applies to all sites.
Keyword redirect objects
Keyword redirects are configured by the following three ecr:type
objects:
- a
redirects
object, which contains a single: redirect-group
object, which contains one or more of the following objects:redirect-entry
objects, each of which specifies the URL to which shoppers are redirected when they enter a particular search term.- Multiple
redirect-entry
objects, each specifying a different search term, can redirect shoppers to the same URL.
Note: It is possible to configure more than one redirect-group
object, but for all ordinary purposes a single redirect-group
object is sufficient.
Sample redirects configuration
The following example illustrates the configuration of a redirects
object containing a redirect-group
object named Products
, which contains redirect-entry
objects named id1
and id2
:
{
"ecr:type": "redirects",
"Products" : {
"ecr:type": "redirect-group",
"id1" : {
"ecr:type": "redirect-entry",
"searchTerms": "canon",
"matchmode": "MATCHEXACT",
"url": "/browse/Canon/_/N-1z141ya"
},
"id2" : {
"ecr:type": "redirect-entry",
"searchTerms": "nikon",
"matchmode": "MATCHEXACT",
"url": "/browse/Nikon/_/N-1z141ya"
}
}
}
Configure the redirects object
This section describes the operations that can be performed to export, create, replace, and modify configuration of the redirects object.
Redirects object attribute
The following table summarizes the attribute of redirects objects.
Attribute | Required? | Type | Values |
---|---|---|---|
"ecr:type" |
yes | String |
There can be only one |
Note: You cannot add attributes to or modify the attribute value of the redirects
object. You can only create it, if for any reason it is missing.
Export redirects object in JSON format
Use the following endpoint to export configuration of the redirects
object, in JSON format:
GET /gsadmin/v1/cloud/redirects.json
In JSON format, the GET endpoint returns full configuration of the redirects
object, and lists the child object, Default
, of the redirects
object; for example:
{
"ecr:lastModifiedBy": "occ_admin",
"ecr:lastModified": "2016-10-26T09:32:32.602-07:00",
"ecr:createDate": "2016-10-26T09:32:32.602-07:00",
"ecr:type": "redirects",
"Default": {
"ecr:lastModifiedBy": "occ_admin",
"ecr:lastModified": "2016-10-26T09:32:32.661-07:00",
"ecr:createDate": "2016-10-26T09:32:32.661-07:00",
"ecr:type": "redirect-group"
}
}
To export the full configuration of the child object of the redirects
object, use the GET method in ZIP format, as described in the following section.
Export redirects object in ZIP format
Use the following endpoint to export configuration of the redirects
object in ZIP format:
GET /gsadmin/v1/cloud/redirects.zip
In ZIP format, the GET endpoint returns not only the redirects object, but also the immediate child object (redirect-group
) of redirects
.
The configuration of all objects is returned in a ZIP file. The ZIP file includes a file named _.json
containing the configuration of the redirects object, and an additional _.json
file containing partial configuration of the redirect-group
object.
For example, suppose that the redirects
object contains a redirect-group
named Default
. The _.json
file that configures the redirects object contains the following:
{
"ecr:lastModifiedBy": "admin",
"ecr:lastModified": "2016-10-17T05:25:35.760-07:00",
"ecr:createDate": "2016-10-17T05:25:35.760-07:00",
"ecr:type": "redirects"
}
The _.json
file that configures the redirect-group
object named Default
is contained in a directory named Default within the ZIP file. This _.json
file contains configuration such as the following:
{
"ecr:lastModifiedBy": "admin",
"ecr:lastModified": "2016-10-24T07:57:48.924-07:00",
"ecr:createDate": "2016-10-24T07:57:48.924-07:00",
"ecr:type": "redirect-group"
}
To get full configuration of a redirect-group
object, specify the following endpoint:
GET /gsadmin/v1/cloud/redirects/redirect-group-name.zip pathname/filename.zip
Create a redirects object
Use the following endpoint to configure the redirects
object, in JSON format or ZIP format:
POST /gsadmin/v1/cloud/redirects
For most purposes, it is convenient to configure all child objects of redirects
through the same request that configures redirects
.
For example, the POST endpoint above can import the following JSON content to configure not only the redirects
object, but also a redirect-group
object named Default
and a redirect-entry
object named id1
within the redirect-group
object:
{
"ecr:type": "redirects",
"Default": {
"ecr:type": "redirect-group",
"id1": {
"ecr:type": "redirect-entry",
"searchTerms": "fujifilm",
"siteIds": "siteA",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us"
}
}
}
Replace the redirects object and its children
In JSON format, use a PUT endpoint to replace the redirects
object and all its child objects with the content provided as input to the endpoint:
PUT /gsadmin/v1/cloud/redirects
Note: The PUT method cannot be used with ZIP format.
In ZIP format, use a POST endpoint to replace the redirects
object and all its child objects with the content provided as input to the endpoint:
POST /gsadmin/v1/cloud/redirects
For example, the PUT and POST endpoints above can import the following JSON content to replace all existing configuration of the redirects
object and its child objects:
{
"ecr:type": "redirects",
"Default": {
"ecr:type": "redirect-group",
"id1": {
"ecr:type": "redirect-entry",
"searchTerms": "kodak",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us"
}
}
}
Configure a redirect-group object
This section describes how to get, create, modify, and replace the configuration of a redirect-group
object.
Redirect-group object attributes
The following table lists the attributes of a redirect-group
object:
Attribute | Required? | Type | Values |
---|---|---|---|
"ecr:type" |
yes | String |
Note: For almost all purposes, only one |
Export the redirect-group object in ZIP format
Use an endpoint of the following form to export configuration of a redirect-group
object in ZIP format:
GET /gsadmin/v1/cloud/redirects/redirect-group-name.ZIP
The ZIP file in which the configuration is downloaded contains the following _.json
files:
- A file containing the configuration of the
redirects
object; for example:
{
"ecr:lastModifiedBy": "occ_admin",
"ecr:lastModified": "2016-10-26T17:11:47.308Z",
"ecr:createDate": "2016-10-26T09:32:32.602-07:00",
"ecr:type": "redirects"
}
- An individual
_.json
file for theredirect-group
object in redirects; for example, the configuration of the Defaultredirect-group
object can be as follows:
{
"ecr:lastModifiedBy": "occ_admin",
"ecr:lastModified": "2016-10-26T10:11:47.369-07:00",
"ecr:createDate": "2016-10-26T10:11:47.369-07:00",
"ecr:type": "redirect-group",
"id1": {
"ecr:type": "redirect-entry",
"searchTerms": "canon",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us",
"searchTermExpansions": {
"0":{"canon": ["canon"]}
}
},
"id2": {
"ecr:type": "redirect-entry",
"searchTerms": "contacts",
"matchmode": "MATCHEXACT",
"url": "/contact-us",
"searchTermExpansions": {
"0": {"contacts": ["contact"]}
}
}
}
Note: searchTermExpansions
is a system-generated attribute.
Do not delete or modify it except when the searchTerms
attribute is
updated, in which case delete the searchTermExpansions
attribute from the
JSON, use the PUT endpoint to update the redirect-group object and generate a new
searchTermExpansions
attribute.
Export the redirect-group object in JSON format
Use an endpoint of the following form to export configuration of a redirect-group object in JSON format:
GET /gsadmin/v1/cloud/redirects/redirect-group-name.json
orGET /gsadmin/v1/cloud/redirects/redirect-group-name
For example, the following endpoint exports configuration of a redirect-group
named Default:
GET /gsadmin/v1/cloud/redirects/Default
The following sample illustrates content of the file to which the configuration of the Default redirect-group object is exported; note that the configuration of the two redirect-entry child objects under Default is contained in this same file:
{
"ecr:type": "redirect-group",
"id1": {
"ecr:type": "redirect-entry",
"searchTerms": "canon",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us",
"searchTermExpansions": {
"0": {"canon": ["canon"]}
}
},
"id2": {
"ecr:type": "redirect-entry",
"searchTerms": "contacts",
"matchmode": "MATCHEXACT",
"url": "/contact-us",
"searchTermExpansions": {
"0": {"contacts": ["contact"]}
}
}
}
Note: searchTermExpansions
is a system-generated attribute.
Do not delete or modify it except when the searchTerms
attribute is
updated, in which case delete the searchTermExpansions
attribute from the
JSON, use the PUT endpoint to update the redirect-group object and generate a new
searchTermExpansions
attribute.
Create the redirect-group object
If no redirect-group
object currently exists, you can create one using the POST method. If a redirect-group
object currently exists, however, you do not need to create another. One redirect-group
object is sufficient for all ordinary purposes.
Use a POST endpoint of the following form to create a redirect-group
object, in JSON format or ZIP format:
POST /gsadmin/v1/cloud/redirects/redirect-group-name
The JSON content that configures the redirect-group object can include the configuration of the redirect-entry
objects that the redirect-group
is to contain; for example, the following content supplied to the POST endpoint above creates a redirect-group
object containing two redirect-entry
objects, id1
and id2
:
{
"ecr:type": "redirect-group",
"id1": {
"ecr:type": "redirect-entry",
"searchTerms": "canon",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us",
"searchTermExpansions": {
"0": {"canon": ["canon"]}
}
},
"id2": {
"ecr:type": "redirect-entry",
"searchTerms": "contacts",
"matchmode": "MATCHEXACT",
"url": "/contact-us",
"searchTermExpansions": {
"0": {"contacts": ["contact"]}
}
}
}
Configure a redirect-entry object
You can get, create, modify, and replace redirect-entry
object
configuration using the Search Admin and Configuration REST API.
Export redirect-entry object configuration in ZIP format
Use a GET endpoint of the following form to export configuration of a redirect-entry
object in ZIP format:
GET /gsadmin/v1/cloud/redirects/redirect-group-name/redirect-entry-name.ZIP
The ZIP file in which the configuration is downloaded contains a file named _.json
that contains the configuration of the redirect-entry
object.
Export redirect-entry object configuration in JSON format
Use a GET endpoint of the following form to export configuration of a redirect-entry
object in JSON format:
GET /gsadmin/v1/cloud/redirects/redirect-group-name/redirect-entry-name
For example, the following GET endpoint exports the configuration of a redirect-entry
object named ID3
:
GET /gsadmin/v1/cloud/redirects/Default/ID3
The following JSON content illustrates configuration of a redirect-entry
object that can be exported by the endpoint above:
{
"ecr:type": "redirect-entry",
"searchTerms": "fujifilm",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us",
"searchTermExpansions": {"0": {"fujifilm": ["fujifilm"]}}
}
Create a redirect-entry object
In JSON or ZIP format, use the following POST endpoint to configure a specified redirect-entry
object in a specified redirect-group
object:
POST /gsadmin/v1/cloud/redirect/redirect-group-name/redirect-entry-name
For example, the following endpoint configures a redirect-entry
object named id3
in a redirect-group
named Default:
POST /gsadmin/v1/cloud/redirect/Default/id3
The following code illustrates the configuration of a redirect-entry
object that can be input to an endpoint in either ZIP or JSON format:
{
"ecr:type": "redirect-entry",
"searchTerms": "fujifilm",
"matchmode": "MATCHEXACT",
"url": "http://www.example.com/about-us"
}
Modify a redirect-entry object
In JSON format, you can use the following endpoint to modify the configuration of a specified redirect-entry
object in a specified redirect-group
object:
PATCH /gsadmin/v1/cloud/redirects/redirect-group-name/redirect-entry-name
Note: The PATCH method cannot be used in ZIP format.
For example, the following endpoint modifies a redirect-entry
object named id3
in a redirect-group
object named Products:
PATCH /gsadmin/v1/cloud/redirects/Products/id3
The endpoint above can use JSON content such as the following to modify the url
attribute of redirect-entry
object named id3
:
{
"ecr:type": "redirect-entry",
"url": "http://www.example.com/about-us"
}
Redirect-entry object attributes
The following table lists the attributes of redirect-entry
objects.
Attribute | Required? | Type | Description |
---|---|---|---|
"ecr:type" |
yes | String |
Note: One or more |
searchTerms |
yes | String | One or more phrases to be compared with search terms entered by shoppers. When matches occur between a searchTerms value and a search term entered by a shopper, the keyword redirect is triggered.
|
matchmode |
yes | String |
The type of match between the specified
|
url |
yes | String | The URL to which users are redirected when a search term entered by a shopper matches a searchTerms value.
|
siteIds |
no | Array of Strings | Specifies one or more site IDs that this redirect entry belongs to. A redirect
entry created without the siteIds attribute applies to all
sites.
|
enableStemming |
no | Boolean | Determines whether the system considers the stems of search terms (for example, “box” the stem of “boxes”) when constructing keyword redirects. |
searchTermExpansions |
no | object | A system-generated attribute |