Skip to content

Connectors

Deprecated API

The Apptus eSales Connectors are replaced by the Web API v2.

This information is not intended for use with new eSales integrations and assumes eSales version 3.20 or newer.

All examples on this page assumes the Java Connector.

The Apptus eSales Connector is a Java/.NET/PHP API that provides an interface to the eSales Servers that together constitute an eSales installation. The API provides a model where queries are conceptually sent to the eSales cluster as a whole. Should one or more eSales Servers happen to be offline or not respond in time, the Connector will transparently perform any necessary retries and redirections. This means that if requests are made through the Connector both load balancing and failover will be handled automatically.

Connector object

The Connector object allows for communication with an eSales cluster. It can be either a CloudConnector object or an OnPremConnector object. The configuration of the cluster, and the information of the eSales servers, will be fetched based on the information sent in the cluster definition string.

CloudConnector

Use a static method on the CloudConnector class to get a CloudConnector object. Credentials to a cluster, e.g. user name and password, will be provided by Apptus. The Connector will automatically acquire the current cluster configuration from the Apptus Cloud environment as well as automatically refresh it if the configuration changes.

CloudConnector conn = CloudConnector.getOrCreate("esales://username:password");

OnPremConnector

Use a static method on the OnPremConnector class to get an OnPremConnector object. Note that the server addresses, the URI, must be manually configured. The URI is a semicolon separated list of host names and ports for the server in the cluster. If the cluster changes, the Connector will try to keep up by refreshing its configuration from the configured servers. However, its still best to update the configuration string if the cluster needs to change.

OnPremConnector conn = OnPremConnector.getOrCreate("esales://server-1:35810;server-2:35810");

Session object

Some requests made to eSales requires that the request is connected to a session. To identify sessions, Session objects are used upon which requests can be made. A session can be created from the Connector object. The returned Session object can be kept, or a new one can be created when needed.

The customer_key and/or market can be specified when the object is created. If they are unknown when the object is created they can be replaced by null. Note that if the Session objects are kept, as opposed to creating a new one when needed, the customer_key and/or market will automatically be changed in the object if a property notification with the appropriate name (customer_key or market respectively) is made on it.

Also note that creating the Session object does not modify the server. It will apply the market and the customer key to the session first when a notification is made or a panel is retrieved within the session.

Session session = conn.session("MySessionKey", "MyCustomerKey", "Sweden");
...
Session session2 = conn.session("MyOtherSessionKey", null, "Sweden");

Retrieving content

To retrieve the contents of a panel with a Connector, the panel to query must first be specified. The retreiveContent() method can then be called with appropriate arguments. The content from the panel can be retrieved as an object called PanelContent. This object corresponds to the content at some level in the panel hierarchy and can thus either be a container or contain a result. The method isZone() will return true if it is a zone, i.e. a panel which may contain sub-panels, while the method hasResult() will return true if it contains a result. Sub-panels can be retrieved in the following way:

ArgMap arguments = new ArgMap();
arguments.put("attribute", "value");
...
Panel panel = session.panel("/example_page");
PanelContent panelContent = panel.retrieveContent(arguments);
if (panelContent.isZone()) {
    List<PanelContent> subPanels = panelContent.subPanels();
}

If the PanelContent contains any result, the type of the result may vary. It can be one of seven different result types upon which different methods can be invoked. At the point where the result is used, it is most likely known which type of result that is expected from a certain panel. Below several examples of how to retrieve different types of results are shown.

try {
    PanelContent subpanelContent = panelContent.subpanel("search_hits");
    if (subpanelContent.hasResult()) {
        Products products = subpanelContent.resultAsProducts();
        // Treat the products
    }
    subpanelContent = panelContent.subpanel("autocomplete");
    if (subpanelContent.hasResult()) {
        Completions completions = subpanelContent.resultAsCompletions();
        // Treat the completions
    }
    subpanelContent = panelContent.subpanel("corrections");
    if (subpanelContent.hasResult()) {
        Corrections corrections = subpanelContent.resultAsCorrections();
        // Treat the corrections
    }
    subpanelContent = panelContent.subpanel("facets");
    if (subpanelContent.hasResult()) {
        Values values = subpanelContent.resultAsValues();
        // Treat the values
    }
    subpanelContent = panelContent.subpanel("search_hit_count");
    if (subpanelContent.hasResult()) {
        Count count = subpanelContent.resultAsCount();
        // Treat the count
    }
    subpanelContent = panelContent.subpanel("ad_information");
    if (subpanelContent.hasResult()) {
        Ads ads = subpanelContent.resultAsAds();
        // Treat the ads
    }
    subpanelContent = panelContent.subpanel("recent_searches");
    if (subpanelContent.hasResult()) {
        Phrases phrases = subpanelContent.resultAsPhrases();
        // Treat the phrases
    }
} catch (ResultTypeException e) {
  // One of the results did not match the specified result type.
}

Full export

A full export to XML of products, configuration, ads, panels, and synonyms can be done using the Connector. Below is an example of a product export:

try(InputStream stream = conn.exportProducts()) {
    // read stream
} catch (IOException e) {
    System.out.println("Failed to export products");
}

// Or export directly to a file
try {
    conn.exportProducts(new File("/path/to/products.xml"));
} catch (IOException e) {
    System.out.println("Failed to export products to file");
}

// The same procedure can be done for Configuration, Ads, Panels, Synonyms.

Filtered product export

In addition to doing a full export to XML with the Connector, products can also be fetched as the same kind of objects used in panel results. A filter can be specified to only get a subset of all products. Below is an example using the Java Connector:

public static void printPaperbackPrices(Connector eSales) {
    String filter = "category:'books' AND format:'paperback'";
    String presentationAttributes = "title, author, price";
    try (ProductStreamer productStreamer = eSales.exportProducts(filter, presentationAttributes)) {
        for (Product product : productStreamer) {
            String title = product.getValue("title", product.key());
            String author = product.getValue("author", "Unknown author");
            String price = product.getValue("price", "Unknown price");
            System.out.println(title + " by " + author + " costs " + price);
        }
    } catch (InterruptedIterationException e) {
        System.out.println();
        System.out.println("... and maybe more.");
    }
}

For more details, see the documentation for the ProductStreamer class in the documentation for Java or .NET.

Downloads

For Connector downloads, see Downloads.

Connector specific documentation


Last update: September 8, 2021
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE