About retrieving Assembler results using the packaged services

If you have purchased Oracle Commerce Guided Search (without Oracle Commerce Experience Manager), you must retrieve Assembler results via the packaged services.

These services are also available for Experience Manager implementations. In an Experience Manager implementation, the services must be located in the /pages/<Default Site>/services/ directory. The packaged services include the following:

Service URI

Description

/services/dimensionsearch

Returns dimension search results based on a text search.

/services/recorddetails

Returns record detail information for a given record.

/services/guidedsearch

Returns search and navigation results including core features such as Guided Navigation, along with dynamic content returned from content folders.

You query the services by passing a ContentInclude item to the Assembler with the relevant service URI or making an Assembler servlet request specifying the service URI. The services are configured to return results for a specific cartridge or set of cartridges.

The cartridges that are returned by the services cannot be configured on a per-instance basis in Experience Manager, but application-wide default configuration for the cartridges can be specified based on your configuration framework (such as Spring). The exception is the dynamic content that can be configured in content folders and that is returned by the Guided Search Service, which can be configured in Experience Manager.

The services are populated in the Endeca Configuration Repository (for use by the authoring instance) when you run initialize_services after deploying an application. They are promoted to the live content source when you promote the site configuration for the live instance.

The Dimension Search Service returns dimension search results for a keyword search.

The service returns a single DimensionSearchResults object in a dimensionSearchResults property, representing the list of dimensions that match the search term.

The default behavior of this cartridge is configured as part of the CartridgeHandler_DimensionSearchResults bean in the Spring context file for the Assembler. For information about the configuration options for the Dimension Search Results cartridge, refer to the Assembler API Reference (Javadoc) for the DimensionSearchResultsConfig class.

This service exists for cases where you want to retrieve dimension search results only (such as in the case of an auto-suggest dimension search feature). Dimension search results are also returned as part of the response from the Guided Search Service.

The following is an example of the results of a Dimension Search Service query for the URI http://localhost:8006/assembler-authoring/json/services/dimensionsearch?Ntt=fla*&Dy=1, serialized to JSON: 

{
    "@type": "DimensionSearchService",
    "name": "Dimension Search Service",
    "dimensionSearchResults": {
        "@type": "DimensionSearchResults",
        "totalNumResults": 13,
        "dimensionSearchGroups": [
            {
                "@class": "com.endeca.infront.cartridge.model.DimensionSearchGroup",
                "dimensionSearchValues": [ … ],
                "dimensionName": "camera.flash"
            },
            {
                "@class": "com.endeca.infront.cartridge.model.DimensionSearchGroup",
                "dimensionSearchValues": [ … ],
                "dimensionName": "product.features"
            },
            {
                "@class": "com.endeca.infront.cartridge.model.DimensionSearchGroup",
                "dimensionSearchValues": [ … ],
                "dimensionName": "product.category"
            }
        ]
    },
    "endeca:contentPath": "/services/dimensionsearch",
    "previewModuleUrl": "http://localhost:8006/preview"
}

The Record Details Service returns record detail information for a given record.

The service returns a single RecordDetails object in a recordDetails property, representing the details for a single record or an aggregate record.

The default behavior of this cartridge is configured as part of the CartridgeHandler_RecordDetails bean in the Spring context file for the Assembler. For information about the configuration options for the Record Details cartridge, refer to the Assembler API Reference (Javadoc) for the RecordDetailsConfig class.

The following is an Experience Manager example of the results of a record details service query for the URI http://localhost:8006/assembler-authoring/json/services/recorddetails/Canon/Prima-Super-130U-Date/_/A-266556, serialized to JSON: 

{
    "@type": "RecordDetailsService",
    "name": "Record Details Service",
    "recordDetails": {
        "@type": "ProductDetail",
        "record": {
            "@class": "com.endeca.infront.cartridge.model.Record",
            "numRecords": 1,
            "attributes": { … },
            "records": [
                {
                    "@class": "com.endeca.infront.cartridge.model.Record",
                    "numRecords": 0,
                    "attributes": { … }
                }
            ]
        }
    },
    "endeca:siteRootPath": "/pages",
    "endeca:contentPath": "/services/recorddetails",
    "previewModuleUrl": "http://localhost:8006/preview",
    "endeca:assemblerRequestInformation": { … }
}

In a Guided Search implementation without Experience Manager, the site root path would be /services. 

"endeca:siteRootPath": "/services",
"endeca:contentPath": "/recorddetails"

The Guided Search Service returns search and navigation results including core features such as Guided Navigation, along with dynamic content returned for content slots.

The properties returned as part of the response model, as well as their associated configuration, are listed below:

Property name

Response model,

Configuration Bean,

Configuration model

navigation

GuidedNavigation

CartridgeHandler_GuidedNavigation

GuidedNavigationConfig

breadcrumbs

Breadcrumbs

CartridgeHandler_Breadcrumbs

BreadcrumbsConfig

resultsList

ResultsList

ResultsListConfig

CartridgeHandler_ResultsList

searchAdjustments

SearchAdjustments

CartridgeHandler_SearchAdjustments

SearchAdjustmentsConfig

dimensionSearchResults

DimensionSearchResults

CartridgeHandler_DimensionSearchResults

DimensionSearchResultsConfig

zones

Depends on contents of referenced content folders.

CartridgeHandler_ContentSlotList

ContentSlotConfig

The following is an example of the results of a guided search service query for the URI http://localhost:8006/assembler-authoring/json/services/guidedsearch?Ntt=pink+camera, serialized to JSON: 

{
    "@type": "GuidedSearchService",
    "name": "Guided Search Service",
    "navigation": {
        "@type": "GuidedNavigation"
    },
    "breadcrumbs": {
        "@type": "Breadcrumbs",
        "removeAllAction": "/services/guidedsearch",
        "refinementCrumbs": [ ],
        "searchCrumbs": [ … ],
        "rangeFilterCrumbs": [ ]
    },
    "resultsList": {
        "@type": "ResultsList",
        "totalNumRecs": 213,
        "sortOptions": [ … ],
        "firstRecNum": 1,
        "lastRecNum": 10,
        "pagingActionTemplate": "/services/guidedsearch?No=%7Boffset%7D&Nrpp=%7BrecordsPerPage%7D&Ntt=pink+camera",
        "recsPerPage": 10,
        "records": [ … ]
    },
    "searchAdjustments": {
        "@type": "SearchAdjustments",
        "originalTerms": [
            "pink camera"
        ]
    },
    "zones": {
        "@type": "ContentSlotList"
    },
    "endeca:contentPath": "/services/guidedsearch",
    "previewModuleUrl": "http://localhost:8006/preview"
}

Note

For details about the contents of the zones property, see "About dynamic content and the Guided Search Service."

For each dynamic slot that you wish to populate as part of the response from the Guided Search Service, you must configure a ContentSlotConfig object. Each of these objects is set as a property of the default input content item for the ContentSlotHandler.

Specify the following properties for each instance of ContentSlotConfig:

Property name

Value

contentPaths

A List of String typed paths to the content folders from which you want to return results.

templateTypes

(Optional) A List of String typed template type restrictions for the dynamic slot.

templateIds

(Optional) A List of String typed template ID restrictions for the dynamic slot.

ruleLimit

The maximum number of content items to return from this collection. The Assembler returns up to this number of items that match the trigger criteria, based on priority.

Note

The content within a folder depends on the template type or ID restrictions configured for that folder in Experience Manager. While it is possible to configure your default ContentSlotConfig objects with any restrictions you wish, you should ensure that the type and ID restrictions you enter match those in Experience Manager. For example, it is possible to create a ContentSlotConfig object that is restricted by template type "MainContent," while the contentPaths property points to folders in Experience Manager that are restricted to "SecondaryContent" (and thus will never contain any "MainContent" content items).

Example 3. Example

In the example below, the input content item to the ContentSlotHandler is a ContentSlotListConfig object. It is instantiated as "contentSlotList," and contains a ContentSlotConfig object for each dynamic slot in the application. The contentSlotList is passed in to the ConfigInitializer that instantiates it as the input content item for the cartridge handler.

The contentSlotList for the Discover Electronics reference application is configured in the CartridgeHandler_ContentSlotList bean in the Spring context file, assembler-context.xml. For each content folder that is enabled for the Guided Search Service, a ContentSlotConfig bean appears in the contentSlotList as in the example below: 

<bean id="CartridgeHandler_ContentSlotList" class="com.endeca.infront.content.ContentSlotListHandler"
 scope="prototype">
    <property name="contentItemInitializer">
        <bean class="com.endeca.infront.cartridge.ConfigInitializer" scope="request">
            <property name="defaults">
                <bean class="com.endeca.infront.content.ContentSlotListConfig" scope="singleton">
                    <property name="contentSlotList">
                        <list>
                        <bean class="com.endeca.infront.content.ContentSlotConfig" scope="singleton">
                                <property name="contentPaths">
                                  <list>
                                    <value>/content/Right Column Spotlights</value>
                                  </list>
                                </property>
                                <property name="templateTypes">
                                  <list>
                                    <value>SecondaryContent</value>
                                  </list>
                                </property>
                                <property name="templateIds">
                                  <list>
                                    <value>RecordSpotlight</value>
                                    <value>RichTextSecondary</value>
                                  </list>
                                </property>
                                <property name="ruleLimit" value="3"/>
                            </bean>
                        </list>   
                    </property>
                </bean>
            </property>   
        </bean>
    </property>
</bean>

For detailed information about the ContentSlotConfig configuration model and its included properties, see the Assembler API Reference (Javadoc).


The Assembler returns the matching content items for each configured ContentSlotConfig, so the response consists of a list of lists of content items:

Note that the Guided Search Service response is not view-friendly. You must parse it in your application logic to determine if any of the content items returned in the tree correspond to page sections you wish to populate for the end user's current location in the application.

Below is a sample JSON response from the Guided Search Service in the Discover Electronics reference application when the user selects the "Cameras" category: 

"zones": {
    "@type": "ContentSlotList",
    "contentSlotList": [
        {
            "@type": "ContentSlot",
            "templateTypes": [
                "RecordSpotlight"
            ],
            "contents": [
                {
                    "@type": "RecordSpotlight",
                    "title": "Most Popular Cameras",
                    "name": "Spotlight Records",
                    "records": [
                        { … },
                        { … },
                        { … },
                        { … }
                    ]
                },
                {
                    "@type": "RecordSpotlight",
                    "title": "Top Rated Products",
                    "name": "Spotlight Records",
                    "records": [
                        { … },
                        { … },
                        { … }
                    ]
                }
            ],
            "contentPaths": [
                "/content/Right Column Spotlights"
            ],
            "ruleLimit": 3,
            "templateIds": [ ]
        }
    ]
},

It populates two sidebar Record Spotlight cartridges, the first with four records, and the second with three.

This topic outlines the logic required for retrieving properties from the Assembler response model for the included Guided Search Service.

The example below includes processing logic within a renderer JSP file. Oracle recommends including most of your logic for handling Assembler responses in your cartridge handlers, as this minimizes the amount of duplicate code required across multiple renderers.

Note

API documentation for the Assembler packages is available in the assembler\apidoc\assembler directory of your Tools and Frameworks installation.

Recall the serialized Assembler response for the URI http://localhost:8006/assembler-authoring/json/services/guidedsearch?Ntt=pink+camera: 

{
    "@type": "GuidedSearchService",
    "name": "Guided Search Service",
    "navigation": {
        "@type": "GuidedNavigation"
    },
    "breadcrumbs": {
        "@type": "Breadcrumbs",
        "removeAllAction": "/services/guidedsearch",
        "refinementCrumbs": [ ],
        "searchCrumbs": [ … ],
        "rangeFilterCrumbs": [ ]
    },
    "resultsList": {
        "@type": "ResultsList",
        "totalNumRecs": 213,
        "sortOptions": [ … ],
        "firstRecNum": 1,
        "lastRecNum": 10,
        "pagingActionTemplate": "/services/guidedsearch?No=%7Boffset%7D&Nrpp=%7BrecordsPerPage%7D&Ntt=pink+camera",
        "recsPerPage": 10,
        "records": [ … ]
    },
    "searchAdjustments": {
        "@type": "SearchAdjustments",
        "originalTerms": [
            "pink camera"
        ]
    },
    "zones": {
        "@type": "ContentSlotList"
    },
    "endeca:contentPath": "/services/guidedsearch",
    "previewModuleUrl": "http://localhost:8006/preview"
}

To create a sample JSP file that invokes the Assembler:

  1. Import the required packages and create the necessary objects for supporting the Assembler: 

    <%@page language="java" contentType="text/html; charset=UTF-8" %>
<%@page import="com.endeca.infront.assembler.Assembler"%>
<%@page import="com.endeca.infront.assembler.AssemblerFactory"%>
<%-- additional imports removed from this example --%>
<%@page import="org.springframework.web.context.WebApplicationContext"%>
<%@taglib prefix="discover" tagdir="/WEB-INF/tags/discover" %>
<%
    // Create the Web Application Context object
    WebApplicationContext webappCtx = WebApplicationContextUtils.getRequiredWebApplicationContext(application);

    // Get the AssemblerFactory from the Spring context file
    AssemblerFactory assemblerFactory = (AssemblerFactory)webappCtx.getBean("assemblerFactory");

  2. Recall that the packaged services invoke the Assembler with a ContentInclude item. Create the assembler object and the ContentInclude item, and pass it into the Assembler as the configuration model: 

        // Create an Assembler object
    Assembler assembler = assemblerFactory.createAssembler();

    // Construct a content include item for the Guided Search service
    ContentItem contentItem = new ContentInclude("/services/guidedsearch");
    
    // Assemble the content
    ContentItem responseContentItem = assembler.assemble(contentItem);

    The Assembler returns a com.endeca.infront.assembler.ContentItem interface as the response model; this extends the Java Map interface. Assign this response to a responseContentItem object.

  3. get the resultsList object from the responseContentItem: 

        ContentItem resultsListItem = (ContentItem) responseContentItem.get("resultsList");

    This retrieves the top-level resultsList object, which is itself an extension of BasicContentItem, from the Assembler response.

  4. You can now retrieve and use the individual values stored on the resultsList object, for example, the total number of records: 

        String totalNumRecs = resultsListItem.get("totalNumRecs");

    This assigns a value of "213" to the totalNumRecs variable (based on the sample response presented at the start of this topic). Similarly, you could retrieve any other value from the key/value pairs that comprise resultsList, including other objects that extend the Map interface and are themselves made up of key/value pairs.

Refer to the Assembler API documentation for additional information about available Assembler interfaces, implementations, and methods. Following the pattern described in Steps 3-4, you can continue to retrieve values from the Assembler response by calling the get method on the response model object to traverse the nested values.

Copyright © Legal Notices