This chapter includes the following sections:
Oracle Enterprise Crawl and Search Framework (ECSF) is an Oracle Fusion Middleware search framework that enables you to quickly expose application context information on various business objects to enable full-text transactional search.
For more information, see the "Managing Search with Oracle Enterprise Crawl and Search Framework" chapter in the Administrator's Guide.
ECSF abstracts an underlying search engine and provides a common set of application programming interfaces (APIs) for developing search functionalities. ECSF serves as an integration layer between the search engine and the Oracle Fusion applications. Figure 28-1 illustrates the architecture of the ECSF framework.
Figure 28-1 Oracle Enterprise Crawl and Search Framework Architecture
ECSF includes the following high-level components:
Searchable Object Manager
Search Designer
Semantic Engine
Fusion Applications Control
ECSF Command Line Administration Utility
Security Services
Data Services
Query Service
ECSF integrates with the Oracle Secure Enterprise Search (Oracle SES) engine to support application search. Oracle SES provides capabilities for crawling and indexing the metadata and objects exposed by ECSF. The Security Plug-in and Crawler Plug-in are modules on Oracle SES that interface with ECSF.
Searchable Object Manager, serving as a metadata manager, manages searchable objects and provides the runtime interface for accessing these objects. At runtime, the Searchable Object Manager loads the searchable objects from persistent storage, validates the searchable object definitions, and provides the searchable objects to the Crawlable Factory component of the Data Service.
The Searchable Object Manager is also responsible for the life cycle management of searchable objects, which administrators can deploy, customize, and enable or disable via the Fusion Applications Control or the ECSF Command Line Administration Utility.
The Search Designer is a page in Oracle JDeveloper 11g that provides the interface for defining the metadata that describes the business objects to be indexed. You can also use this design interface to specify the security mechanism used to protect the data, as well as define the searchable object search characteristics, which include Advanced Search, Faceted Navigation, and Actionable Results.
The Semantic Engine leverages the semantic information of searchable object definitions to create context around the search. It achieves this by interpreting the searchable object definitions with relation to the runtime user information during both crawl and query time. Runtime user information may include the following:
Facets
Actionable results
Security
Personalization
Internationalization
Data structure mapping
Tagging, commenting, rates
Results clustering
Context filtering
Custom weighting
The Fusion Applications Control is an Oracle Enterprise Manager extension that provides a user interface for registering searchable objects in the ECSF schema in the Oracle Fusion Applications database, and for administering the runtime parameters of ECSF, the target search engine, and the configuration of parameters.
The ECSF Command Line Administration Utility is a standalone command line interface that provides a user interface for registering searchable objects in the ECSF schema in the Oracle Fusion Applications database. You can also use this tool for configuring and administering ECSF without external dependencies on Oracle Enterprise Manager.
The Security Service is the runtime server component responsible for providing security information to SES. During query time, this service retrieves the security keys of the user performing the search and passes them to Oracle SES, where they are used to filter the query results.
The Security Service server component is also invoked during crawl time to add security information (access control lists) to data before inserting or creating indexes on the search engine (Oracle SES). An access control list (ACL) is a list that identifies the users who can access the associated object and that specifies the user's access rights to that object. The ACL values generated by the Security Service during crawl time should match the corresponding keys generated during query time.
Note:
In ECSF, the generic term ACL (access control list) is used to describe how Oracle SES and ECSF pass security information and perform security checks by using the information described in the ACL.
The Security Service component is implemented as a security engine with a plug-in interface. The security plug-in determines the format of the ACL keys. For all custom security models, a new Security Plug-in must be implemented. Security Service uses Oracle Platform Security for Java to authenticate users and call the Security Plug-in to retrieve security values for a given searchable object.
For more information about security for ECSF, see Configuring ECSF Security .
Data Service is the primary data interface, based on a proprietary Really Simple Syndication (RSS) feed format, between ECSF and the search engine. In addition to supporting the flow of metadata between ECSF and the search engine, Data Service supports attachments, batching, and error handling.
Data Service authenticates each Oracle SES crawl request by using Oracle Platform Security for Java to validate the user credentials and permissions for crawling the data source.
The Crawlable Factory component, part of Data Service, determines how searchable objects are broken down and manages the construction of RSS feeds to the search engine.
The Query Service provides a search interface for the applications UI and handles all search requests. This service performs query rewrite, parameter substitution, and other preprocessing operations before invoking the underlying configured search engine.
Search results are also serviced via this service. Hooks are provided to preprocess and postprocess data, which facilitates the capability to filter search results.
Oracle SES enables a secure, uniform search across multiple enterprise repositories. ECSF integrates with Oracle SES technology to provide full-text search functionality in Oracle Fusion Applications.
Note:
The application server space is demarcated to identify that ECSF runs in a separate application server, outside the search engine. It is recommended, for performance reasons, that each search engine instance runs on separate hardware.
Oracle SES provides an API for writing security plug-ins (or connectors) in Java. With this API, you can create a security plug-in to meet your requirements. ECSF Security Service interfaces with this security plug-in. The Security Plug-in invokes the Security Service to retrieve keys, to which the user has access, for filtering the results that are delivered to the ECSF query service. A proxy user must be set up on the search engine to invoke the Security Service. The proxy user must have security privileges for the Oracle Fusion applications. For more information about security for ECSF, see Configuring ECSF Security .
The Crawler Plug-in is a search engine (Oracle SES) module that implements the modified RSS feed format between ECSF and Oracle SES. This component deserializes the data sent from ECSF, via the Data Service component, and interfaces with the Oracle SES components that creates the indexes.
You can use the ECSF Command Line Administration Utility to quickly test and manage the searchable objects without having to use Oracle Enterprise Manager Fusion Applications Control.
Note:
Administrators should use Fusion Applications Control to manage the life cycle of searchable objects in the production environment.
Before you can run the utility, you must complete the following setup requirements:
After you have set up the ECSF Command Line Administration Utility, you can run the utility by any of the following ways:
Execute the runCmdLineAdmin.bat
script (Windows)
Execute the runCmdLineAdmin.sh
script (Linux)
Start it as a Java program from a command line interface with the following command:
java oracle.ecsf.cmdlineadmin.CmdLineAdmin
Enter a username and password when prompted.
Note:
If you enter an invalid username and password, you can either reconnect manually by using the connect
command, or exit the ECSF Command Line Administration Utility (type exit
or press Ctrl-C
) and try again.
When you update passwords in the Lightweight Directory Access Protocol (LDAP) credential store from the ECSF Command Line Administration Utility, the jps-config-jse.xml
file must contain the same LDAP information as the jps-config.xml
file. Java Platform Security (JPS) does not propagate the changes from jps-config.xml
to jps-config-jse.xml
automatically.
All commands, responses, and error messages in the ECSF Command Line Administration Utility are logged.
To exit the ECSF Command Line Administration Utility, enter the exit
command at the prompt.
Make the searchable objects accessible to the ECSF Command Line Administration Utility by adding the ADF library JAR file containing the view object and entity object definitions to its class path.
The ECSF Command Line Administration Utility needs the path of the JAR file containing the searchable objects. These metadata objects are validated during register and unregister operations.
You can find the unpacked EAR files containing the searchable object JAR files for the search applications in the following locations:
For Linux OS: /net/mount1/appbase/fusionapps/applications/fscm/deploy/EarFscmSearch.ear/APP-INF/lib/
searchable_object_jar_file
For Windows OS: C:\appbase\fusionapps\applications\fscm\deploy\EarFscmSearch.ear\APP-INF\lib\searchable_object_jar_file
For Linux OS: /net/mount1/appbase/fusionapps/applications/crm/deploy/EarCrmSearch.ear/APP-INF/lib/
searchable_object_jar_file
For Windows OS: C:\appbase\fusionapps\applications\crm\deploy\EarCrmSearch.ear\APP-INF\lib\searchable_object_jar_file
For Linux OS: /net/mount1/appbase/fusionapps/applications/hcm/deploy/EarHcmSearch.ear/APP-INF/lib/
searchable_object_jar_file
For Windows OS: C:\appbase\fusionapps\applications\hcm\deploy\EarHcmSearch.ear\APP-INF\lib\searchable_object_jar_file
To add the ADF library JAR file containing the view object and entity object definitions to the class path for the ECSF Command Line Administration Utility, you must first create the ADF library.
The application JAR file, which contains the searchable objects that are defined in your application, is written to the deploy
directory of the project.
To deploy or undeploy a searchable object, a JAR file containing the searchable object must be specified in the class path of the ECSF Command Line Administration Utility. For information, see About Setting the Class Path.
If you are deploying searchable objects from multiple applications, you must create a JAR file for each of those applications to add the searchable objects to the class path.
In order for the ECSF Command Line Administration Utility to run, the class path must contain the required Oracle classes. Modify and run scripts to set the class path, as well as optional connection information, and run the ECSF Command Line Administration Utility.
Note:
If you receive a java.lang.ClassNotFoundException
exception, then add the JAR file containing that class to ADMIN_CP
in the script.
The ECSF Command Line Administration Utility references the class path to obtain the location of Oracle Library home, Java home, Oracle WebLogic Server home, and the JAR files needed for the ECSF Command Line Administration Utility operations.
Modify and run the runCmdLineAdmin.bat
script to set the class path in a Windows environment.
To set the class path in Windows, do the following:
In a text editor, open the runCmdLineAdmin.bat
script from MW_HOME
/Oracle_atgpf1/ecsf/modules/oracle.ecsf_11.1.1/admin
.
Specify the Oracle Library home directory path by locating the line set ORACLE_LIBRARY_HOME=SET_ORACLE_LIBRARY_HOME
and replace SET_ORACLE_LIBRARY_HOME
with the ATGPF shiphome directory, for example, set ORACLE_LIBRARY_HOME=C:\mw_home\oracle_common
.
Specify the ATGPF Library home directory path by locating the line set ATGPF_LIBRARY_HOME=SET_ATGPF_LIBRARY_HOME
and replace SET_ATGPF_LIBRARY_HOME
with the ATGPF shiphome directory, for example, set ATGPF_LIBRARY_HOME=C:\mw_home\Oracle_atgpf1
.
Specify the ATGPF Library home directory path by locating the line set ATGPF_LIBRARY_HOME=SET_ATGPF_LIBRARY_HOME
and replace SET_ATGPF_LIBRARY_HOME
with the ATGPF Library directory, for example, set ATGPF_LIBRARY_HOME=c:\fmwtools_view\fmwtools\mw_home\jdeveloper
.
Specify the Oracle WebLogic Server home directory path:
Locate the following line: set WLS_HOME=SET_WLS_HOME
Replace SET_WLS_HOME
with the Oracle WebLogic Server home directory path, for example, set WLS_HOME= C:/MW_HOME/wlserver_10.3
Specify the Java home directory path:
Locate the following line: set JAVA_HOME=SET_JAVA_HOME
Replace SET_JAVA_HOME
with the Java home directory path (where the Java executable should be located), for example, set JAVA_HOME=C:\Java\jdk\bin
.
The version of Java used must match the version required by the Oracle build.
Specify the directory path of the application JAR file:
Locate the following line: set APP_JAR=SET_APP_JAR
Replace SET_APP_JAR
with the directory path of the application JAR file you created in About Making Searchable Objects Accessible to the ECSF Command Line Administration Utility, for example, set APP_JAR=C:\Jdeveloper\mywork\Application1\runtime\deploy\archive1.jar
.
Save the script file.
The ECSF Command Line Administration Utility requires an Oracle Fusion Applications database, to which it can either be directly connected or connected through a remote MBean. To use the ECSF Command Line Administration Utility, you must supply the connection information.
Set the connection information in the runCmdLineAdmin
script so that the ECSF Command Line Administration Utility automatically connects to the specified database or MBean server during startup. If you do not include the connection information in the script, then you must manually create the connection to the Oracle Fusion Applications database after you start the ECSF Command Line Administration Utility. For information, see About Manually Connecting to the Database.
The information for connecting to the database or MBean server is saved in the runCmdLineAdmin
script for the ECSF Command Line Administration Utility to use for connecting to the Oracle Fusion Applications database at startup. You are prompted to enter a password after you start the ECSF Command Line Administration Utility.
Modify the runCmdLineAdmin.bat
script to set the connection information in a Windows environment.
To set the connection information in Windows, do the following:
The ECSF Command Line Administration Utility requires an Oracle Fusion Applications database, to which it can either be directly connected or connected through a remote MBean, for command execution. To use the ECSF Command Line Administration Utility, you must supply the connection information.
You can supply connection information either before or after starting the ECSF Command Line Administration Utility. Supplying the connection information before startup allows the ECSF Command Line Administration Utility to automatically connect to the specified database or MBean server during startup. For information, see About Setting the Connection Information.
If you choose not to supply the connection information before startup, you must manually create the connection to the Oracle Fusion Applications database after you start the ECSF Command Line Administration Utility.
To create a connection to the Oracle Fusion Applications database directly, enter one of the following commands at the ECSF Command Line Administration prompt, then press Enter:
connect to database
The ECSF Command Line Administration Utility prompts you for the host name, port, and SID.
connect to database service
The ECSF Command Line Administration Utility prompts you for the host name, port, and service name.
connect to database descriptor
The ECSF Command Line Administration Utility prompts you for the descriptor.
The descriptor
argument must be enclosed in quotation marks and can contain either the SID or service name. For example:
Using SID:
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNECT_DATA=(SID=dbmsdb2)))'
Using service name:
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNECT_DATA=(SERVICE NAME=myservice)))'
connect to database
hostname port SID
You can directly pass the required values as arguments into the command.
connect to database service
hostname port servicename
You can directly pass the required values as arguments into the command.
connect to database descriptor '
descriptor
'
You can directly pass the required value as an argument into the command. The descriptor
argument must be enclosed in quotation marks and can contain either the SID or service name. For example:
Using SID:
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNECT_DATA=(SID=dbmsdb2)))'
Using service name:
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNECT_DATA=(SERVICE NAME=myservice)))'
To create a connection to the Oracle Fusion Applications database through a remote MBean, enter one of the following commands at the ECSF Command Line Administration prompt, then press Enter:
connect to mbeanserver
The ECSF Command Line Administration Utility prompts you for the required values.
connect to mbeanserver
hostname port
You can directly pass the required values as arguments into the command.
The ECSF Command Line Administration Utility prompts you to enter a username and password.
The JPS Config file (jps-config-jse.xml
) contains the credential store information needed for running the ECSF Command Line Administration scripts. You must provide the path of the JPS Config file by modifying the ECSF Command Line Administration scripts.
To set the JPS Config file path, do the following:
runCmdLineAdmin.bat
(Windows) or runCmdLineAdmin.sh
(Linux) script, located in ORACLE_HOME
/jdeveloper/ecsf
, in a text editor.JPS_CONFIG
parameter to point to the location of jps-config-jse.xml
(usually at DOMAIN_HOME
/config/fmwconfig/jps-config-jse.xml
).The scripts for the ECSF Command Line Administration Utility point to the logging configuration file (ecsfcla-logging.xml
), where you can configure log settings, such as log level and log file location. The ecsfcla-logging.xml
file is located in the same directory as the ECSF Command Line Administration scripts (JDEV_INSTALL
/ecsf/
). To configure log settings, modify the property values in ecsfcla-logging.xml
and save the file.
The location of ecsfcla-logging.xml
can be changed by modifying the ODL_CONFIG
parameter in the ECSF Command Line Administration scripts.
All commands, responses, and error messages in the ECSF Command Line Administration Utility are logged. The generated log files follow the format ecsfCmdLineAdminLog*.txt
, and its default location is JDEV_INSTALL
/ecsf/log/
.
You can set the ECSF Command Line Administration Utility to automatically execute a defined sequence of commands when you run the utility. To automate the ECSF Command Line Administration Utility in this way, you must configure the startup script to take inputs from a text file that you create.
The input file must contain one command per line. Any values that are not passed in with a command and for which you are typically prompted (for example, username and password) must occupy their own lines in the file. You must include a connect
command since this is not passed in during the automated startup, and you must also include the exit
command as the last command in the file to exit the ECSF Command Line Administration Utility. Example 28-1 illustrates a sample list of commands for an input file.
You must know all of the object IDs when you create the input file. Using the input file, you cannot create a new object and then manage it in one automation.
Example 28-1 Sample Input File
connect to database fusionhost123 1566 fh123 fusion fusion manage instance 1 set param "SES_ADMIN_SERVICE"="http://example.com:7777/search/api/admin/AdminService" set param "SES_ADMIN_USERNAME" = "eqsys" exit
While you can use the ECSF Command Line Administration Utility to quickly test and manage the searchable objects, Oracle Enterprise Manager Fusion Applications Control is necessary to manage the life cycle of searchable objects in the production environment.
The ECSF runtime application needs to register its MBean to WebLogic's Domain Runtime MBean server, and the Oracle Enterprise Manager Fusion Applications Control needs to invoke all ECSF runtime operations through the MBean.
To access the Fusion Applications Control, you must install and configure Oracle Enterprise Manager (EM) to work with ECSF. You do not need to set up Oracle Enterprise Manager if you plan to use the ECSF Command Line Administration Utility to administer search.
To set up Oracle Enterprise Manager for ECSF, you must perform the following tasks:
Multiple developers can share one single Oracle Enterprise Manager application with the Fusion Applications Control.
The ECSF runtime application registers an MBean (oracle.ecsf.mbean.SearchRuntimeAdminMXBean
) in WebLogic's Domain Runtime MBean server through a listener class (oracle.ecsf.mbean.RegisterMbeanContextListener
). All ECSF runtime operations are invoked through the MBean.
To register the MBean, do the following:
web.xml
.Registering the ECSF runtime MBean to the Integrated WebLogic Server makes the MBean available to remote clients such as Fusion Applications Control in Oracle Enterprise Manager.
Add the MBean listener by modifying web.xml
to include oracle.ecsf.mbean.RegisterMbeanContextListener
.
To add the MBean listener do the following:
Create the application EAR file to be deployed. Right-click the application name and navigate to Deploy > ECSF application deployment profile
> to EAR file. When the deployment is complete, you can find the generated EAR file in the JDeveloper log message window.
You must configure data sources in Oracle WebLogic Server for MBean integration. Search for a data source with the JNDI name SearchDBDS
. If any exist, make sure to look at the connection and validate that SearchDBDS
is pointing to the correct database. If SearchDBDS
is not listed, you must create a data source with jdbc/SearchDBDS
as the JNDI name and with the connection information to the database against which the Fusion web application is running.
Make the MBean available by deploying the EAR file you created to Integrated WebLogic Server. Make sure that the EAR file is deployed and the application status is active in the final step.
You must install Oracle Enterprise Manager to access the Fusion Applications Control. Installing Enteprise Manager allows you to then enable it to discover the ECSF custom application target in Oracle WebLogic Server.
To use Fusion Applications Control in Oracle Enterprise Manager, you must first enable Oracle Enterprise Manager to discover the ECSF custom application target in Oracle WebLogic Server. When you discover ECSF in Oracle Enterprise Manager, you enable Oracle Enterprise Manager to detect and display the Fusion Applications Control. You only need to discover the ECSF custom application target in Oracle WebLogic Server once. When it is discovered, you can directly launch EM with the following URL:
http://
your machine name
:
port
/em
To discover ECSF in Oracle Enterprise Manager, do the following:
Note:
You only need to discover the ECSF custom application target in Oracle WebLogic Server once. When it is discovered, you can directly launch EM with the following URL:
http://
your machine name
:
port
/em