Integrating Multiple Search Engines Using Federated Search › Create a New Custom Adapter Using the SDK interface

Create a New Custom Adapter Using the SDK interface

Important! CA Federated SDK sample source code is provided to users for creating and deploying alternate custom adapters. However, CA Support will not provide support to write the actual custom code. We do not actively support the creation and deployment of additional adapters beyond the SDK source code samples shipped with the CA Service Desk Manager Application.

The CA Federated Search SDK architecture is designed for extensibility. The SDK contains all the necessary JAR files to develop a custom adapter. Sample Eclipse projects can be imported, and Ant build targets are also provided to build custom search adapters. The SDK is located in the CA SDM directory:

$NX_ROOT\samples\sdk\fedsearch\adapters-source.tar.gz 

The source code of the following adapters can be used to write additional custom adapters:

• Google
• CA Open Space
• Microsoft Share Point

Note: Source code for the CAFedSearch servlet, its underlying framework, and the security filter are not provided. No source code is provided for any of the Crawler Surface components.

The SDK component is written in java and is shared as a jar file (cafedsearch-adapter-sdk-1.0.0.jar). The SDK provides a simple interface to enable customers to develop and deploy their own search adapters.

Follow these steps:

1. Compile the Custom Search Adapter Jar Files
2. Configure the New Custom Search Adapter with the CAFedSearch Component
3. Verify the new Custom Search Adapter

Compile the New Custom Adapter Jar Files

Compile the custom adapter jar files successfully.

Follow these steps:

1. Compile the new custom search adapters. Ensure you have the following jar files in your Java Classpath:

   jsr311-api-1.0.jar

   This jar file is available in the CA SDM directory:

   %NX_ROOT%\java\lib\CXF\
   

   cafedsearch-core.jar

   This file is available in the directory:

   %NX_ROOT%\bopcfg\www\CATALINA_BASE_FS\webapps\cafedsearch\WEB-INF\lib
   

   cafedsearch-adapter-sdk-1.0.0.jar

   This file is available in the directory:

   %NX_ROOT%\bopcfg\www\CATALINA_BASE_FS\webapps\cafedsearch\WEB-INF\lib
   

   log4j-1.2.15.jar (optional)

   This file is available in the directory:

   %NX_ROOT%\java\lib
   

2. Write a new Java Class which extends the SearchAdapter Class and provides an implementation for the abstract method.

   search
   

   The CAFedSearch component invokes and passes search method parameters. These parameters are embedded inside the SearchOptions parameter for each search request from the client.

   Note: Ensure that your implementation is thread safe as the CAFedSearch component maintains only one instance of the Java Class. For each search operation, search method is invoked on the same instance.

3. The SearchOptions parameter for the search method has the following methods:

   getSearchTerms()

   Specifies the method for retrieving the search string.

   getStartIndex()

   Specifies the start index method, the number from which the client wants to search items. Index starts from 1.

   getItemsPerPage()

   Specifies the maximum number of search results that the client expects.

   Note: You can also use other Java Class methods. For example: getUserId()

4. Send the collected information to the external search engine API for retrieving the search results.

   Note: For information about Java Class Methods, see Java Documentation.

5. The search method returns an instance of ResultCollection class. Create an instance of ResultCollection and populate values using the following methods:

   setSources(String name)

   Specifies the name of the search adapter. Names are case-sensitive and must match exactly with the name that is provided in the utility configuration file. For convenience, SearchAdapter provides a method getName() which should be used.

   For example:

   results.setSources(getName());
   

   setTotalResults (int total)

   Specifies the total search result count.

   setStartIndex(int startIndex)

   Specifies a start index of results. This value is as per results from your search engine.

   results.setStartIndex(startIndex);
   

6. A collection of ResultItems must be passed to the ResultCollection object by calling the setSearchResultItems method. To add an instance of ResultItem at a time, use the addSearchResultItem() method.

   Note: For more information about ResultCollection Java class, see the Java documentation.

7. The ResultItem class has the following important methods, which must be filled for each search result item (row).

   setContentText(String txt)

   Specifies a method for setting the search result actual content.

   setContentHTML(String txt)

   Specifies a method for setting the HTML (can contain the HTML tags) content. If the search engine gives HTML highlighted, then set the highlighted text using this method.

   Note: If your search engine does not have this feature, you can write a simple Java class method to highlight the text. The CA Open Space adapter has a simple method to bold terms in the search results.

   setTitleHTML(String titleHTML)

   A method to setting an HTML title (can contain the HTML tags).

   setTitleText(String titleText)

   A method to set a plain title (cannot contain the HTML tags).

   setSource(String source)

   A method to set the source attribute. A typical invocation would be an item setSource(getName());

   Note: If the search adapter requires more jar files, customize the build.xml to compile and prepare an adapter jar file. Ant binaries are required to use the build.xml. Use Ant to run the targets in build.xml to compile and make the JAR files Keep the build.xml along with your source (src) folder. The build.properties file is optional. For more information about Ant binaries, see Ant Help.

   The jar file is successfully compiled.

Configure the New Custom Search Adapter with the CAFedSearch Component

Configure the new search custom adapter jar file with the CAFedSearch Component for creating the CA SDM search sources.

Follow these steps:

1. Copy the jar file from the location dist\lib (created in Compile the New Custom Adapter Jar Files) to the following CA SDM directory:

   %NX_ROOT%\bopcfg\www\CATALINA_BASE_FS\webapps\cafedsearch\WEB-INF\lib
   

2. Navigate to the following CA SDM directory:

   $NX_ROOT\sample\cafedsearch\
   

3. Create a new template xml file for the custom search adapter. For example, the XYZ-tmpl.xml file.
4. The template file contains the following:

   <?xml version="1.0" encoding="UTF-8"?>
   

   <beans default-autowire="byName" xsi:schemaLocation="http://www.springframework.org/schema/beans
   

   http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
   

   http://cxf.apache.org/core
   

   http://cxf.apache.org/schemas/core.xsd
   

   http://cxf.apache.org/jaxrs
   

   http://cxf.apache.org/schemas/jaxrs.xsd" xmlns:cxf="http://cxf.apache.org/core" 
   

   xmlns:jaxrs="http://cxf.apache.org/jaxrs" 
   

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   

   xmlns="http://www.springframework.org/schema/beans">
   

   	<bean autowire="autodetect"
   

   		class=" com.abc.xyz.XYZAdapter "
   

   			id="XYZAdapterConfiguration" scope="singleton">
   

   <property name="username" value="$(xyz_username)"/>
   

       <property name="password" value="$(xyz_password)"/>
   

   </bean>
   

   <bean autowire="autodetect" class="com.abc.xyz.XYZAdapter" id="XYZSearchAdapter" init-method="init" destroy-method="destroy" depends-on="XYZAdapterConfiguration">
   

   			<property name="config" ref="OpenSpaceAdapterConfiguration" />
   

   	</bean>
   

   </beans>
   

5. You can create property values based on the input values provided for the search adapters in step 4.

   Add xyz_username and xyz_password in the adapters.properties file and provide values to the property.

6. Run the utility file to generate configuration XML for custom search adapters:

   fs_adapters_cli -i -k XYZ -b XYZSearchAdapter -t "XYZ-tmpl.xml " -o "xyz.xml
   

7. The xyz.xml file is created and registered in the adapters-config.xml file.
8. Copy the xyz.xml file and adapters-config.xml to the following CA SDM directory:

   $NX_ROOT\samples\cafedsearch\WEB-INF
   

9. Run the following command to restart Federated Tomcat Services:

   pdm_tomcat_nxd -c STOP -t FS
   pdm_tomcat_nxd -c START -t FS
   

10. Create the federated search sources for the XYZ adapter in the CA SDM UI.

    For more information about federated search sources, see Create the Federated Search Sources in CA SDM.

11. In CA SDM, navigate to the Knowledge Management Tab. Select the XYZ check box and perform search operations.

    The new custom search adapter is successfully configured with the CAFedSearch component.

Verify the new Custom Search Adapter

Verify the functionality of your new custom search adapter by using the REST client.

Follow these steps:

1. Download the REST client from the Internet:

   https://code.google.com/p/rest-client/

2. Launch it using Java (JRE is required).
3. Enter the following URL in the REST client UI:

   http://sdmhostname:<FS_Tomcat_Port>/cafedsearch/sdm/search?q=search&userid=<sdmuserid>&source=<Adapter Name>
   

4. Turn off the CA SDM security interceptor. Open the following file for editing and comment out the “<jaxrs:inInterceptors> “ section:

   $NX_ROOT\bopcfg\www\CATALINA_BASE_FS\webapps\cafedsearch\WEB-INF\beans.xml
   

   Note: Turning off the security filter is not recommended in a production environment. Turn off the Security filter in a test environment for verifying the new custom search adapter functionality.

5. Verify that the new custom search adapter is functioning properly. If search results are not displayed, try reviewing the logs, or increase the log level to Debug.