Skip to content

Elasticsearch: Anatomy of a Search

Search is becoming more important in PeopleSoft and is often required for applications to work properly. We’ve talked before on how to configure Elasticsearch with PeopleSoft, but what happens when we perform a search? There are a number of moving parts that handle the search query, applying security and displaying the results. Let’s take a look into the anatomy of a search to understand the process.

Overview of the Search Flow

The user creates a search request. Generally, this happens when a user opens the Search Box and enters a term or terms to search on. But this process can also start from a component. A good example is the “Find Learning” page in ELM. When you open the component, it runs sends a query to Elasticsearch for data to populate the page with.

Search Framework Builds the Query

The search request from the user needs to be parsed and formatted so that Elasticsearch understands the query. The app package PT_SEARCH has a number of methods that check for wildcards, partial words, and create a valid JSON request for Elasticsearch.

IB Builds JSON Message

In the app package PTSF_ES, the JSON search query string is converted into an IB Message using the IB_GENERIC message. The app package also builds the HTTP headers for the transaction, such as the content-type: application/json and the Authorization header.

The Integration Broker POSTs the message against the alias for the Search Category. If you deployed the EP_ASSETS search in Finance for the database PSFTDB, the alias is ep_assets_psftdb_orcl_es_alias. When you search, you search against the Search Category instead of the individual indices. The alias is the Elasticsearch mechanism to let you search against the category instead of each index.

Elasticsearch Validates Security

A PeopleSoft plugin running in Elasticsearch verifies the security of the user request before running the query. The orcl_es_auth plugin will validate the Basic Authentication value in the HTTP POST from the IB. The user it is validating is esadmin – the user and password defined on the Search Instance page. In your Elasticsearch logs, you can see the validation happening:

[authentication           ] Authentication plugin : authenticate method
[authentication           ] Authentication type : Base64
[authentication           ] Authentication successful

ES Runs the Query

Next, Elasticsearch will run the query. In the Elasticsearch logs, you can see which indexes are used to perform the search:

[orclacl                  ] Indices/ aliases : [ ep_assets_psftdb_orcl_es_alias ]
[orclacl                  ] Index types retrieved : [ ep_am_asset_psftdb ]

In this example, the EP_ASSETS Search Category has only one index associated with it.

ES Checks the ACL Cache

After Elasticsearch has the search results for the query, the results are filtered based on PeopleSoft security. Search Definitions can implement different security types to lock down search data. There is User/Role security, as well as Document security. If a Search Definition has a security type, the security data is collected when the Search Index is built with PTSF_GENFEED. The security attributes are attached to each row of data sent to Elasticsearch.

If the index has security enabled, Elasticsearch needs to know what security the user running the query has access to. The orcl_es_acl plugin is responsible for managing the user security data inside Elasticsearch. If the user has run a query in the last two hours, the orcl_es_acl plugin uses the existing security data for the user stored in Elasticsearch.

In the Elasticsearch logs, you can see this in action:

[orclacl                  ] Document is secured for the type : ep_am_asset_psftdb
[orclacl                  ] Orcl ACL Plugin method: getAttrValFromCache

ES Performs Callback (if needed)

If the user has not run a query for the index before, the plugin will perform a callback to PeopleSoft. The callback will ask PeopleSoft what security values the user has and stores them in a special index: orcl_es_acl. To perform the callback, Elasticsearch creates a new cURL request to the IB URI /RESTListeningConnector/PSFTDB/getsecurityvalues.v1/. The callback URL and security is stored in Elasticsearch under the index orcl_es_acl

The request includes three parameters as well:

  • ?type=ep_am_asset_psftdb
  • ?user=PS
  • ?attribute=BU_SECURITY_SES

The type parameter is the name of the search index requesting the security data. The user is the name of the user running the search query. And the attribute is the security value configured on the Search Definition page.

PS Runs the Callback Code

When the IB receives the callback request, it hands the request to the Application Package specified on the Search Definition. The App Package inspects the parameters to see what security attribute has been requested. The callback code then runs any appropriate code and SQL to build a list of Roles or Permission Lists assigned to the user.

PS Returns the ID and Security

The Permission Lists or Roles are assembled into an array and have P: or R: appended to the beginning of each item. Once the array is assembled, the values are returned to Elasticsearch in a response message. For example, the response might contain an array that looks like ["P:PTPT1000","P:PTPT1200","P:PTPT3100"] – Permission Lists assigned to that user.

ES Filters the Results

Elasticsearch has no concept of the security structures in PeopleSoft, so it uses the data returned from the callback to remove search results that a user has no security to. The callback array from above lists the Permission Lists assigned to a user. Elasticsearch will build a filter query to remove any rows from the search results that do not contain one of those Permission Lists.

Something to keep in mind – Elasticsearch can only filter the search results based on the Permission List stored in each searh result. This means that Permission Lists are attached to each search result when the PTSF_GENFEED process is run. If you change your security dramatically (say, re-implement Business Unit Security), you may need to fun a full build to push your security changes into Elasticsearch.

You can view the permission lists attached to each document with the Elasticsearch API. In your browser you can call the /_search REST method against any URL. If you deployed the PTPORTALREGISTRY search definition with the default settings, you can call the URL to view the data in Elasticsearch. In the document, you will find the list of security attributes like this: ["P:PTPT1000","S:Admin"].

ES Returns the Results

After the filter query completes, Elasticsearch will return the search results as a JSON message back to PeopleSoft. When the message is received, the results are parsed and displayed by the search results component. Depending on the application, you might see the generic search results page, or an application specific page.

12 thoughts on “Elasticsearch: Anatomy of a Search”

  1. Hi Dan,
    Thank for your post.
    it seems the ACL is kept in cache for 2 hours after callback. When I ran some tests (at 2017-10-24 16:44:30,867), I got the following in the ES log file :
    “ORCL_SEC_ATTR_VALUES” : [ “S:Admin” ],
    “CACHE_TIME” : “2017-10-24T18:39:16.512”
    I did not find where the 2 hours duration was set.

    Best regards,

    1. The 2 hour duration is set on the Search Options page (PeopleTools > Search Framework > Administration > Search Options > Cache Interval). The gives the valid timeframe for the cached security attributes.

      The time you are seeing in the log file is the time to clean up the stored cache data in the orcl_es_acl index. In elasticsearch.yaml, the setting acl.cache.delete.interval: 24h controls how often the expired cache data is pruned.

  2. Pingback: #149 – Anatomy of a Search

  3. Pingback: #167 – Troubleshooting Elasticsearch

  4. Nice article,,Is it possible to show the end to end imlpementation steps for a ELM Find Learning Elastic Search.

    The issue at our end is that the ELM Find Learning page is showing Learnings which are closed and Last Enrollment Date is passed. I want to know the setup/connected query/criteria that is fetching this closed class on the search results page.

    1. Are you asking if we can clear the security cache for an individual? Currently, all the users are stored in the orcl_es_acl index as data but each user has their own row. In theory you could write a REST call to update or delete a user, but I don’t know if the orcl_es_acl will like that.

  5. Very detailed and helpful information, Dan. So in the case a user chooses the “All” option on the global search page, the process would then invoke separate search for each of the available deployed searches for that user’s Permission List. Then the result sets would be filtered according to each search’s security setup? Does it do that sequentially, one search definition at a time?

    Is there an option to turn off the “All” option that you are aware of?

    Thank you!

    1. Hi Daniel, yes, the “All” option executes searches for all the indexes. I don’t know of a way to turn that off though.

  6. Hi Dan,

    We are testing ES and ran into a situation with a group of users who get “No results found…” for the Requisition ES while other users from the same Business Units can see search results. I turned on all the trace options at the sign-on page in PeopleSoft but the trace file does not contain anything about ES.

    Our technical person said that another trace file only shows nodes and shards info in the ES server.

    I would think there has a to be a trace file somewhere that shows the users’ Permission List or Business Unit security somehow affecting the search results based on their security profile then finally shows “No results found”, right? Where would this log file be?

    Thank you.

    1. It sounds like you need to capture the callback information between PeopleSoft and ES – where ES makes a call to the Integration Broker and asks which security attributes the user has so that ES can filter out search results. You may be able to see this info in the APPSRV log file by using the Search Instance Options page. There is a “Log ES requests for User ID” field. Add the user in question to this field and have them execute a search. But, remember that ES cache’s a users security attributes for 2 hours, so if they have search recently ES won’t make the callback.

      The second option is to put something like MITM proxy between ES and the IB. Use the MITM proxy as the callback URL and have it capture the callback request and response. You can use that information to see what PS is returning in the response.

      1. Thank you so much Dan. I did get the log file which shows the correct expected Permission List, the attributes/responses PV_REQ_SECURITY_ORCL_ES_ACL and A:ALL for the user, which should have allowed all Requisitions to be seen. But something is still amiss and the user still can’t see any search results. Hmmm!

Leave a Reply

Your email address will not be published. Required fields are marked *