Configure Federated Search

Integrating Multiple Search Engines Using Federated Search › Configure Federated Search

Configure Federated Search

The Federated Search feature consists of the following components:

UI components: Enables CA SDM Analyst users to enter search arguments and pass the search request to the Federated Search server.
CAFedSearch servlet: Main component of the federated Search feature and uses a REST interface. The Federated Search servlet runs on a dedicated Tomcat instance within the CA SDM application.
Plug-in search adapter: The plug-in search adapter interfaces the CA SDM application to an external search engine.The adapter translates the generic search requests to a search engine proprietary format and calls the search engine. The Federated Search servlet returns the configured search engine results to the CA SDM UI component.

The following diagram shows how to configure Federated Search with the CA SDM application:

How to Configure Federated Search

Follow these steps:

Complete the Prerequisites

Complete the following prerequisites:

Ensure to select the Federated Search option on the Configure Federated Search wizard while installing the CA SDM application.
Know and decide the search engines that you want to use for Federated Search.
Ensure to have an active Google Account for configuring the Google Plug-in Search Adapter. A Google API key and Google Custom Search Engine ID is also required. For more information, see Google Custom Search Engine https://www.google.com/cse/all
Verify that IIS on the SharePoint server is configured with basic authentication. Microsoft SharePoint adapter requires basic authentication. By default, Basic Authentication is turned off in SharePoint. For more information about how to enable basic authentication in SharePoint, see the Microsoft SharePoint Documentation.
Note: Enable Basic Authentication for _vti_bin in IIS.
To integrate with CA Open Space, version 3.0 on-premise solution is required. For more information, see the CA Open Space documentation. The CA Open Space SaaS offering is not currently supported.

Enable Federated Search

A dedicated Tomcat instance is installed to host the CAFedSearch and FSCrawl servlets. The Federated Search Tomcat is under the control of the Daemon Manager. Tomcat Starts and stops automatically when CA SDM runs or shuts down respectively.

Configure the Federated Search (FS) Tomcat with the following installation options:

Configure Federated Search: Ensure to select this option when installing the CA SDM application. The Tomcat options are available only after selecting this option.
Tomcat Port: Specifies the Federated Search Tomcat Port. Default Port= 8040.
Tomcat Shutdown Port: Specifies the Federated Search Tomcat Shutdown Port. Default Port= 8045.

Generate Configuration XML Files for Federated Search

To configure Federated Search and to decrease editing errors, a utility file fs_adapters_cli is provided. A batch file for Windows and a Shell script for Linux and Unix is provided. The utility file is a Java application that is contained in two Jar files.

Three template files are supplied for CA Open Space, Google, and SharePoint adapters. The adapters-config.xml file is used for both input as well as output to the utility. The adapters.properties file is used as input to the utility. This file holds all the necessary configuration parameters for the adapters. The jfedsearch.log file contains the log file information.

The fs_adapters_cli utility is used to configure the adapters-config.xml file. The utility file installs and uninstalls the adapters by adding or removing entries from the adapters-config.xml. Individual adapter XML configuration files are generated. These files are then included in the adapters-config.xml with the <import> bean directive. Ensure to maintain a clean copy of the adapters-config.xml.

To install an adapter, two entries are added for registering and importing the adapter in the adapters-config.xml file
To uninstall an adapter, two entries are removed for registering and importing the adapter from the adapters-config.xml file.

For more information about using the utility file, see Federated Search Utility Files and Invoke the Utility File to Configure the Search Adapters.

Federated Search Utility Files

The fs_adapters_ cli utility file is located in the CA SDM $NX_ROOT\samples\cafedsearch directory. The following utility file components are available in this location:

Script files:
- fs_adapters_cli .bat (for Windows)
- fs_adapters_cli.sh (for Non-Windows)
JAR files:
- fs_adapters_config_cli.jar
- fs_adapters_config_schema.jar
Templates:
- openspace-tmpl.xml
- google-tmpl.xml
- sharepoint-tmpl.xml
Properties:
- adapters.properties

To install the federated search utility file, run the following command:

fs_adapters_cli -i -k <key> -b <bean> -t <filename> -p <filename>  -o <filename> [-c <filename>]

Use the fs_adapters_cli –h option to get Help on the Utility file. The following attribute options are available:

-b (Optional): Attribute value to map adapters. Refers to an actual ID of an adapter bean. If not specified, then the value from –k is taken as the value for –b.
-c (Optional): The main XML file that contains all the configured adapters.
-h (Optional): Provides Help for the Federated Search Utility.
-i: Specifies the option used for installing the adapter.
-k: Specifies the adapter key attribute.
-o: Specifies the Output XML filename to be generated. Name of the XML file to create and update the merged content of the XML template and SharePoint properties file.
-p (Optional): Indicates the properties file name to merge with the Adapter Definition XML template.
-t: Specifies the name of the XML template file for defining an adapter.
-u: Specifies the name of the adapter XML file to uninstall the adapter.

Invoke the Utility File to Configure the Search Adapters

A Search engine requires specially coded plug-in adapters. A plug-in search adapter translates generic search requests to a search engine proprietary format, calls the search engine, and returns the search requests.

Note: If CA SDM is configured for multi-tenancy, your Tenant is passed along to the search engine. Federated Search has built-in support for multi-tenancy. You can use this to isolate data by a tenant in a single SharePoint implementation.

Important! Do not use ampersands or spaces in the adapters.properties file values.

Follow these steps:

Encrypt passwords for search adapters using the encrypt password utility. To encrypt passwords, navigate to the following CA SDM directory:
```
$NXROOT\bin
```
Run the following command for generating encrypted passwords:
```
encrypt_pwd [-e] <search engine password>
```
The default option is -e.
Open the adapters.properties file from the following CA SDM directory:
```
$NX_ROOT\samples\cafedsearch
```
Edit the adapters.properties file. Specify the appropriate parameters for the adapters you want to configure.
For SharePoint, update the following values in the adapters.properties file:

sharepoint_username=

Enter the user name for SharePoint access.

sharepoint_password=

Enter the encrypted password for SharePoint access as shown in Step1.

sharepoint_hostname=

Enter the hostname.

sharepoint_domainName=

Enter the domain name.

sharepoint_protocol=

Enter the communication protocol (http or https).

sharepoint_portNumber=

Enter the port number. Default is 80.
For Google, update the following values in the adapters.properties file:

google_googleCx=

Enter the unique key value that Google uses to decide which Google Custom Search Account to use.

google_googleApiKey=

Enter the unique key value that helps Google determine the identity of an application. To retrieve the key in the APIs Console, activate JSON/Atom Custom search API. This API provides a new API key for Simple API Access.
For CA Open Space, update the following values in the adapters.properties file:

openspace_protocol=

Enter the communication protocol (http or https).

openspace_portNumber=

Enter the port number for CA Open Space. Default is 8686.

openspace_default_tenant_userName=

If CA SDM is not configured with multi-tenancy, enter a username to perform search in CA Open Space.

openspace_default_tenant_password=

Ener the CA Open Space encrypted password. For more information, see Step1.

openspace_default_tenant_companyHost=

Enter the tenant company host details.
1. In case of CA SDM multi-tenancy, add an entry for each tenant in the openspace-tmpl.xml:
  For example, if CA SDM contains Tenant name as Tenant 1, you have to provide the following values in the openspace-tmpl.xml file:
```
<entry key="Tenant1"> 
```
```
 <bean class="com.ca.ServicePlus.cafedsearch.adapters.openspace.OpenSpaceCompanyDetail">
```
```
  <property name="userName" value="$(openspace_tenant1_userName)"/>
```
```
   <property name="password" value="$(openspace_tenant1_password)"/>
```
```
  <property name="companyHost" value="$(openspace_tenant1_companyHost)"/>
```
```
  </bean>
```
```
</entry>
```
2. Add the following entries for Tenant 1 in the adapters.properties file:
```
openspace_tenant1_userName=
```
```
openspace_tenant1_password=
```
```
openspace_tenant1_companyHost=
```
  Repeat steps a and b for all required tenants in the openspace-tmpl.xml file.
Invoke the fs_adapters_cli once for each adapter you want to configure.
- If you want to configure a CA Open Space adapter, use the bean value as OpenSpaceSearchAdapter and the template as openspace-tmpl.xml as shown in the following example:
```
fs_adapters_cli -i -k OpenSpace -b OpenSpaceSearchAdapter -t "openspace-tmpl.xml" -o "openspace.xml"
```
- To configure a Google adapter, provide the the bean value as GoogleSearchAdapter and the template as google-tmpl.xml as shown in the following example:
```
fs_adapters_cli -i -k Google -b GoogleSearchAdapter -t "google-tmpl.xml" -o "google.xml"
```
- If you want to configure a SharePoint adapter, use the bean value as SharePointSearchAdapter and the template as sharepoint-tmpl.xml as shown in the following example:
```
fs_adapters_cli -i -k SharePoint -b SharePointSearchAdapter -t "sharepoint-tmpl.xml" -o "sharepoint.xml"
```
Modify the -k and -o attribute values with a name of your choice. For more information about the federated search utility file and attributes,.see Federated Search Utility Files.
After installation, if there are any errors, check the log file located in the CA SDM directory:
```
$NXROOT\log\jfedsearch.log
```
Optionally, you can also create your own XML file for registration. All adapter entries are registered in the adapters-config.xml located in the following directory:
```
$NX_ROOT\samples\cafedsearch
```
To create your own XML file for registration, you can also make a copy of the existing adapters-config.xml file name (optional step). Give the modified adapters-config.xml file a name of your choice. For example, xyz.xml file.
Use the -c option with the modified XML file (xyz.xml) to register adapters.
Change the resource value in bean.xml <import resource="adapters-config.xml"/>.
Copy the adapters-config.xml or the modified xyz.xml (step 11) and any associate adapter-specific XML files for Google (google.xml), CA Open Space (openspace.xml), SharePoint (sharepoint.xml) in the following CA SDM directory:
```
$NX_ROOT\bopcfg\www\CATALINA_BASE_FS\webapps\cafedsearch\WEB-INF
```
Restart the Federated Search Tomcat instance:
```
pdm_tomcat_nxd -c STOP -t FS
```
```
pdm_tomcat_nxd -c START -t FS
```
The federated search adapters are configured.
Verify and check the error log files in the CA SDM directory:
```
$NX_ROOT\log\jfedsearch.log
```

Create the Federated Search Sources in CA SDM

The CA SDM Web UI is loosely coupled with the CAFedSearch Servlet. Configure Search Sources in CA SDM to create a new record.

Follow these steps:

Log in to the CA SDM application as Service Desk Administrator.
Select Administration, Knowledge, Federated Search, Search Source to create a new record that represents a federated search engine.
The Search Source contains the Name of the Federated Search Source that is displayed to users.

Note: Code value must match the key value attribute of an entry in the adapters-config.xml.

Search the Knowledge Solution using the New Custom Search Adapter

Search for knowledge documents and articles in the CA SDM application using the new custom search adapter.

Follow these steps:

Log in as a CA SDM Service Desk Administrator.
Navigate to Administration, Knowledge, Federated Search, Search Sources.
Add a new search source Code Key value.
Click Save.
Navigate to Knowledge Management using a new or existing ticket.
Search for the knowledge source that you have created. Click Show Filter to enter the search criteria and click Search.
The search information is displayed.

Uninstall the Search Adapter

To uninstall the search adapters, use the fs_search_cli utility command with the –u option. Use the following utility file command:

fs_adapters_cli -u -k <key> -b <bean> [-c <filename>]-f <filename>]

-u

Specify the -u option to uninstall the search adapters.

-k

Specify the key name value provided at the time of installation.

-b

Specify the bean value provided at the time of installation.

-c

Specify the name of the new search adapter configuration xml, if you created any while configuring the search adapters with Utility.

-f

Gives the Generated output file name at the installation time.

For more information, see Configure Search Adapters with Utility.

For example, if you want to uninstall the Google search adapter, perform the following:

Follow these steps:

Run the utility file command with the -u option for uninstalling the Google search adapter:
```
fs_adapters_cli -u -k Google-b GoogleAdapter-f Google.xml
```
Check and verify that the adapters-config.xml removes registration for Google.
Google.xml file is deleted from the following CA SDM directory:
```
$NX_ROOT\samples\cafedsearch
```
Copy the adapters-config.xml to the following directory:
```
$NX_ROOT\samples\cafedsearch\WEB-INF
```
Delete the google.xml file from this location.

Restart the FS Tomcat:

pdm_tomcat_nxd -c STOP -t FS

pdm_tomcat_nxd -c START -t FS

In the CA SDM UI, verify the Activate Search source entry for this Adapter (Google, in this case).
To uninstall other external search adapters, repeat steps 1 to 6.