How to set up Search Blueprints to be used with Search headless API

Issue

You do not find a suitable headless API or is not still developed by Liferay so you would like to create your own search blueprint and invoke it easily from Search API.
- For example, retrieve draft or pending web content articles based on a structure field ( Feature Request ).

Environment

Quarterly Releases from 2024.Q3+

Resolution

Starting from 2024.Q3, you can enable the release feature flag feature.flag.LPD-11232=true and feature.flag.LPS-179669=true in portal-ext.properties to be able to invoke your custom search blueprints from headless API.
Create your custom search blueprint with any kind of search, and save the external reference code (ERC).
Access the search API and execute GET /v1.0/search (getSearchPage) adding, at least, this parameters:
- blueprintExternalReferenceCode : <ERC> - Custom Blueprint reference.
- emptySearch: true - Enables empty search.
- nestedFields: embedded - Get additional data of the result item.

Example - Obtain web contents of a given site in any status based on a custom text structure field 'fieldSample=sample'

Verify feature flags are added to portal-ext.properties
Create a custom structure and add some web contents having fieldSample with value 'sample'

Create a new Blueprint:

Query Settings
- Set "Web Content Article" as searchable type.
- Disable all search query contributors.

Query Elements

Paste a 'MUST' elasticsearch query to filter web contents having fieldSample=sample. Could be similar to the following json (verify elasticsearch index to check the IDs and field name/value and adapt this code to your specific environment configuration):

{
   "nested":{
      "path":"ddmFieldArray",
      "query":{
         "bool":{
            "must":[{
               "term":{
                  "ddmFieldArray.ddmFieldName":"ddm__keyword__12345__fieldSample_en_US"
               }
            },
            {
               "term":{
                  "ddmFieldArray.ddmFieldValueKeyword_en_US":{
                     "value": "sample"
                  }
               }
            }]
         }
      }
   }
}

Add a "Limit Search to These Sites" element and select a site.

(Optional) Modify the ERC to 'custom-erc' and save.

Test it with search API

How to set up Search Blueprints to be used with Search headless API

Issue

Environment

Resolution

Example - Obtain web contents of a given site in any status based on a custom text structure field 'fieldSample=sample'

Additional Information