This page explains how to set up your development environment that you can call Fredhopper. It does not describe how to render the Fredhopper query responses. When completed, please proceed with Step 2 - Develop a simple front-end application.
Requirements
Please ensure the following requirements are met before you start:
- Set up a Fredhopper instance in your local environment or get remote access to an instance in Fredhopper's infrastructure.
- Familiarize yourself with the basic concepts of web services and the SOAP protocol. In case you are not familiar with these concepts, please first read up on specialized articles and books, e.g. Introduction to Web Services.
- Please do note that you are expected to follow some general best practice approaches as well as to built on top of the provided WS-Stub classes. In particular:
- You can find information on Querying here: Querying Best Practice and Anti-Patterns
- Make sure to have a proper handling for:
- Connect Exception (TCP/Network)
- Connect Timeout (TCP/Network)
- Connect ok, Request timeout (HTML/Application)
- Response incomplete (HTML/Application)
- Response complete, but containing errors e.g. HTTP (HTML/Application)
- Response complete, HTTP 200, but SOAP corrupt
- Response fine
- Logging and esp. tracing requests which were not picked up by Fredhopper or handled correctly, in case they are critical to your operation (e.g. when populating a cache)
Step 1: Choose your SOAP implementation
In this step you choose the right SOAP implementation for your situation out of the countless implementations of the SOAP standard. Please choose the recommended SOAP implementation below depending if you use a Standard eCommerce platform, or a Bespoke solution.
Standard eCommerce platform
| eCommerce platform | Recommended SOAP implementation |
|---|---|
| Demandware | Axis 1 which is bundled with Demandware |
| Hybris | JAX-WS (part of Java 1.6) |
| IBM WebSphere 6+ | SDO |
| IBM WebSphere 5.x | WebSphere SOAP Engine |
| Intershop 6.3+ | If you use JDK1.6: use JAX-WS; Otherwise: Axis 2 which is bundled with Intershop |
| Intershop 5.x/6.0-6.2 | If you use JDK1.6: use JAX-WS; Otherwise: Axis 1 which is bundled with Intershop |
| Please double check with your eCommerce vendor on the recommended SOAP implementation for your specific version of the platform. |
Bespoke solution
| Development platform | Recommend SOAP implementation |
|---|---|
| Java 1.6+ | JAX-WS (part of Java 1.6) |
| Java 1.4/1.5 | Axis 2 |
| .NET | Part of .NET |
| PHP | PHP SOAP extension |
| ASP (not .NET) | ASP doesn't support SOAP. Use the Fredhopper REST/XML API. See specification in client/xml-rest. |
Step 2: Create your SOAP stub classes
This section explains you how to create the SOAP stub classes that you use to connect to Fredhopper.
|
Location of WSDL The WSDL is in the folder https://extranet.fredhopper.com/downloads/fas/fas7/latest/unpacked/client/webservice/. The Fredhopper Webservice will also return a WSDL at http://<server>:<port>/fredhopper-ws/services/FASWebService?wsdl, but this WSDL should not be used as contains errors in some versions of Fredhopper caused by its automatic creation. |
| SOAP implementation | Explanation | ||
|---|---|---|---|
| JAX-WS | Fredhopper (FAS6.1+) provides pre-compiled Java 1.6 client classes in the library client/java/ws-client-1.x.jar (JavaDoc and Sources). | ||
| Axis 2 | If you use Intershop, please create the stub classes with the Enfinity Studio. Generate SOAP client classes with Axis:
|
||
| Axis 1 |
If you use Intershop, please create the stub classes with the Enfinity Studio. Generate SOAP client classes with Axis:
|
||
| SDO | Consult IBM | ||
| WebSphere SOAP Engine | Consult IBM | ||
| .NET | Consult the Microsoft Windows Communication Foundation Documentation.
|
||
| PHP SOAP extension | Not required | ||
| ASP (not .NET) | Not required |
Step 3: Add libraries to your project
Next you have to add helper libraries to your project helper:
| SOAP implementation | Libraries to be added |
|---|---|
| JAX-WS | Add client/java/ws-client-1.x.jar, client/java/query-lang-2.x.jar (Doc) and servlet-api.jar to the classpath of your Java project |
| Axis 1/2 | Add the classes from directory axis/fas-client, client/java/query-lang-2.x.jar (Doc) and servlet-api.jar to the classpath of your Java project |
| SDO | Consult IBM |
| WebSphere SOAP Engine | Consult IBM |
| .NET | 1. Add the created client classes and query-lang-2.x.dll (Doc) as resources and references to your .NET project. 2. Download the IKVM library: version 7.2.4630.5 for FAS 7.5.0.3 and up or version 0.42.0.6 for older FAS versions. 3. From the folder bin/ of the unzip IKVM library add the following libraries to the .NET project as resources and references:
|
| PHP SOAP extension | Not required |
| ASP (not .NET) | Not required |
|
Explanation for .NET Fredhopper ensures that each .NET library provides the same level of functionality and reliability as its Java counterpart using IKVM.NET. The Fredhopper Java library is converted with IKVM to CIL, compiled to a DLL, and provided for download in the Learning Center. The generated Fredhopper .NET library (DLL) depends on primitive classes that are part of the JVM such as Array, Integer, etc. IKVM provides these Java classes as well as .NET byte code. This means that there is no runtime conversion from Java byte code to CIL and no JVM emulation. Instead, .NET executes straight .NET byte code that implements the same functionality as the Java library. Using IKVM.NET leads to a marginal performance decrease of 3.5% (measured compared to native C# implementation) because the JVM classes have to be translated to .NET native classes. It is not recommended to use MONO instead of the .NET Framework since this leads to a performance decrease of 550%. Since version 2.7 query-lang.dll contains the version of IKVM with which it has been built. You may check it within Windows Explorer > Properties of "query-lang.dll" > Details > File version. The major number is the version of query-lang library and the minors are the IKVM version. Always use the IKVM version corresponding to your Query Lang dll version. |
Step 4: Send test queries to Fredhopper
|
Authentication The examples below assume that Fredhopper can be accessed without any additional authentication. Depending on the deployment scenario you may have to provide additional authentication information before being able to access Fredhopper.
|
This section provides you with code samples to send your first call to Fredhopper:
| SOAP implementation | Code sample |
|---|---|
| JAX-WS |
// Compose query for red shirts Query query = new Query("fh_location=//catalog01/en_US/color=red/$s=shirt"); URL wsdlURL = new URL("http://localhost:8180/fredhopper-ws/services/FASWebService?wsdl"); FASWebServiceService fasServiceService = new FASWebServiceService(wsdlURL, new QName("http://ns.fredhopper.com/XML/output/6.1.0", "FASWebServiceService")); FASWebService fasService = fasServiceService.getFASWebService(); // execute call to FAS Webservice Page page = fasService.getAll(query.toString()); // Print breadcrumbs of selected universe for (Universe u : page.getUniverses().getUniverse()) { if (UniverseType.SELECTED.equals(u.getType())) { Breadcrumbs breadcrumbs = u.getBreadcrumbs(); int nrOfItemsInSelection = breadcrumbs.getNrOfItemsInSelection(); System.out.println("Items in selection: " + nrOfItemsInSelection); // There is only one selected universe in a response, so we can break. break; } } |
| Axis 2 |
// Compose query for red shirts Query query = new Query("fh_location=//catalog01/en_US/color=red/$s=shirt"); FASWebServiceSoapBindingStub stub = new FASWebServiceSoapBindingStub(null, "http://localhost:8180/fredhopper-ws/services/FASWebService"); // execute call to FAS Webservice FhParamsDocument fhParams = FhParamsDocument.Factory.newInstance(); fhParams.setFhParams(query.toString()); PageDocument pageDoc = stub.getAll(fhParams); |
| Axis 1 |
// Compose query for red shirts Query query = new Query("fh_location=//catalog01/en_US/color=red/$s=shirt"); URL endpointURL = new URL("http://localhost:8180/fredhopper-ws/services/FASWebService"); FASWebServiceServiceLocator locator = new FASWebServiceServiceLocator(); FASWebServiceSoapBindingStub stub = new FASWebServiceSoapBindingStub(endpointURL,locator); // execute call to FAS Webservice Page page = stub.getAll(query.toString());
|
| SDO |
// Compose query for red shirts Query query = new Query("fh_location=//catalog01/en_US/color=red/$s=shirt"); try { page = FredhopperClientFacadeImpl.getInstance().getAllRequest("getAll", query.toString()); } catch (InvocationServiceException e) { throw new ECSystemException(ECMessage._ERR_GENERIC, getClass().getName(), "performExecute", new Object[] { e.toString() }, e); } |
| WebSphere SOAP Engine | Consult IBM |
| .NET |
Unable to find source-code formatter for language: vb. Available languages are: actionscript, html, java, javascript, none, sql, xhtml, xml
// Build the query Query query = new Query("fh_location=//catalog01/en_US"); // Send query FASWebServiceService webservice = new FASWebServiceService(); page Page = webservice.getAll(query.toString()); |
| PHP SOAP extension |
Unable to find source-code formatter for language: php. Available languages are: actionscript, html, java, javascript, none, sql, xhtml, xml
<?php // Discover a Fredhopper Query Service $ws_location='http://localhost:8180/fredhopper-ws/services/FASWebService'; $wsdl_location=$ws_location + '?wsdl'; // Create a new soap client $client = new SoapClient($wsdl_location, array('login'=>'username', 'password'=>'password', 'location'=>$ws_location)); // Build the query string $fh_location="fh_location=//catalog01/en_GB/brand={place_the_search_query_here}"; // Send the query string to the Fredhopper Query Server & obtain the result $result = $client->__soapCall('getAll', array('fh_params' => $fh_location)); // Find the universe marked as 'selected' in the result foreach($result->universes->universe as $r) { if($r->{"type"} == "selected"){ // Extract & print the breadcrumbs from the result $breadcrumbs = (array)$r->breadcrumbs; print_r($breadcrumbs); // Extract & print the item information from the result $items = (array)$r->{"items-section"}->items; print_r($items); } } ?> |
| ASP Classic (not .NET) | This is an example for using direct access to REST, there is no known-good SOAP client for ASP Classic (not .NET)
Unable to find source-code formatter for language: vb. Available languages are: actionscript, html, java, javascript, none, sql, xhtml, xml
<% location = "" If Request.QueryString("fh_location") = Null Then location = "//catalog01/en_US" Else location = Request.QueryString("fh_location") End If ' TODO: Build the full query here requestParam = "fh_location=" & location Dim objServer Set objServer = Server.CreateObject("MSXML2.ServerXMLHTTP.3.0") objServer.setTimeouts 30000, 30000, 30000, 30000 ' Query FAS objServer.Open "GET", "http://localhost:8180/fredhopper/query?" & requestParam, False ' Request that redirect responses should be returned in XML as well objServer.setRequestHeader "User-Agent", "XML only client" objServer.Send Set objXML = Server.CreateObject("Msxml2.DOMDocument") If objServer.status = 200 Then objXML.loadXML objServer.responseText CONTENT = "" 'Read Xml and Get elements <facet> set filterNodes = objXML.selectNodes("//universe[@type='selected']/facetmap/filter") 'Loop through the nodes For Each filterNode In filterNodes ' Get Facet Name CONTENT = CONTENT & "<div><h2>" & filterNode.getAttribute("on")& "</h2><div>" set filterSections = filterNode.selectNodes("filtersection") For each filterSection in filterSections Set links = filterSection.selectSingleNode("link") CONTENT = CONTENT & "<a href=Asp_Fredhopper.asp?" & links.selectSingleNode("url-params").text & "><div>" & links.selectSingleNode("name").text & " (" & filterSection.getAttribute("nr") & ")</div></a>" Next Next response.Write(CONTENT) End %>
|
|
WSDL Address vs Endpoint Address Please note that while the WSDL can be retrieved at /fredhopper-ws/services/FASWebService?wsdl, this is not the address to which the actual SOAP requests must be sent. All SOAP requests must be sent to /fredhopper-ws/services/FASWebService, as specified in the WSDL itself. Fredhopper recommends to use a locally cached WSDL to avoid network requests for it, and explicitly define the endpoint to use with the SOAP client. |
Congratulations! You prepared your development environment to get started on implementing your front-end application. Please proceed with Step 2 - Develop a simple front-end application.
Comments
0 comments
Please sign in to leave a comment.