Skip to main content

 

SILK UI Framework

 

OutSystems

Elasticsearch Web Component

Elasticsearch is a search engine that centrally stores data in an integrated way. It provides a distributed search mechanism that lets you combine many types of full-text searches and returns results instantly. The Elasticsearch Web component allows you to integrate an Elasticsearch engine into your application.

elasticsearch-web-explanation.png

How to Use the Elasticsearch Web Component

The component contains a block with an input to search a query in the Elasticsearch provider, that then matches and returns a list of results. It also includes an API to control the results and a sample that shows you how to use the component.

  1. In your Application Module, click the Manage Dependencies button.
  2. Select the component and all its actions, blocks and entities.

image_2.png

3. Configure the Elasticsearch server in your provider.
We recommend using either Elastic Cloud or AWS.

Using the Component

After adding references to the component, you need to add configurations. Follow the sections below to start searching.

Establish the Request URL

Your application needs to send requests and receive responses from an Elasticsearch provider. In order to do so, you need to obtain an ElasticsearchURL.

  1. In your application, create a new site property:
    a. Name it ElasticsearchURL (type Text).
    b. As a default value, use the URL of your Elasticsearch provider. This URL is obtained when you configure your chosen provider (see step 3 in the previous section). 
     
  2. Create a new server action and name it ConfigureElasticsearch.
    a. Add one output parameter: ElasticsearchURL (type Text).
    b. Assign the ElasticsearchURL site property to the output parameter ElasticsearchURL.
    Whenever you need an ElasticsearchURL, call this action and use its output parameter.

elasticsearch url.png

Configure BasicAuthentication

Follow these steps to configure BasicAuthentication to ensure security if you're using the Elastic Cloud as your provider or another provider that supports Basic Authentication.

  1. In your application, create two new site properties:
    - ElasticsearchAuthUsernameElasticsearchAuthUsername (type Text)
    - ElasticsearchAuthPassword (type Text)
  2. Open the previously created action ConfigureElasticsearch and add the BasicAuthentication action from the ElasticsearchCore API.
  3. Enter the input parameters with the corresponding site properties: ElasticsearchAuthUsernameElasticsearchAuthUsername and ElasticsearchAuthPassword.
  4. Call this action before any interaction with the Elasticsearch component.

configure basic auth.png

Use the DynamicResults UI Block to Search

1. Drag the DynamicResults block and drop it inside your web screen.

image_3.png

2. In the screen where you are using the block:
    - Add a local variable ElasticsearchURL (type Text).
    - Create a new Preparation action.

image_4.png

3. Inside the Preparation action, use the ConfigureElasticsearch action created in the section above to retrieve the ElasticsearchURL.
    - Set its output to the local variable created in step 2.

4. Set the local variable ElasticsearchURL as the value for the component input.

5. Fill in the other parameters in the DynamicResult according to your scenario and requirements.DynamicResult according to your scenario and requirements.

UI block_4.png

Using the API

Regardless of the selected provider, you need to add results to your search. In order to do that, there are a set of actions to manipulate your provider.
We encourage you to follow these steps to improve the performance and usability of the API.

Register New Records

  1. Create a new server action and name it NewRecord.

    a. Add three input parameters:
        - Index (type Text)
        - Type (type Text)
        - ElasticsearchRecord (type ElasticsearchRecord)

    b. Add three output parameters:
        - RecordId (type Text)
        - Success (type Boolean)
        - ErrorMessage (type Text)

2. Inside NewRecord, add the ConfigureElasticsearch action and the InsertRecord action from the Elasticsearch API.
    - Set the input parameters of the InsertRecord action with the input parameters created in the previous step and the output parameters from the ConfigureElasticsearch action.
    - Set the output parameters created in the previous step with the output parameters from the InsertRecord action.

register new records_new image.png

3. This action is now available in your application for you to insert new records in your Elasticsearch provider. You can either use the sample approach we provide with the application - which inserts records based on a form - or:
    a. Create records based on your data model.
    b. Use it inside a timer.

Update Records

  1. Create a new server action and name it UpdateRecord.

    a. Add two input parameters:
        - RecordId (type Text)
        - ElasticsearchRecord (type ElasticsearchRecord)

    b. Add two output parameters:
        - Success (type Boolean)
        - ErrorMessage (type Text)
     
  2. Inside UpdateRecord, add the ConfigureElasticsearch action and the UpdateRecord action from the Elasticsearch API.

    a. Set the input parameters of the UpdateRecord action with the input parameters created in the previous step, and the output parameters from the ConfigureElasticsearch action.
    b. Set the output parameters created in the previous step with the output parameters from the UpdateRecord action.
        

update_records_new.png

3. This action is now available in your application for you to update records in your Elasticsearch provider. You can either use the sample approach we provide with the application - which uses a form inside a screen - or:
    a. Update records based on your data model.
    b. Use it inside a timer.

Get a Specific Record

1. Create a new server action and name it GetRecord.

    a. Add an input parameter: RecordId (type Text).
    b. Add three output parameters:
        - ElasticsearchRecord (type ElasticsearchRecord
        - Success (type Boolean)
        - ErrorMessage (type Text)

2. Inside GetRecord, add the ConfigureElasticsearch action and the GetRecordById action from the Elasticsearch API.
    a. Set the input parameters of the GetRecordById action with the input parameter created in the previous step, and the output parameters of the the ConfigureElasticsearch action.
    b. Set the output parameters created in the previous step, with the output parameters of the GetRecordbyId action.

get specific record.png

3. This action is now available in your application for you to get a specific record from your Elasticsearch provider. You can either use the sample approach we provide with the application - which fetches each record's details from a list of results - or:
    a. Use it inside a timer.

Get Records

  1. Create a new server action and name it GetRecords.

        a. Add the following input parameters:
            - Index (type Text)
            - Type (type Text)
            - SearchQuery (type Text)
            - CharacterConverter (type Boolean)
            - ScoreLimit (type Decimal)
            - AscendingRankResult (type Boolean)
            - StartingIndex (type Integer)
            - NumberOfResults (type Integer)

        b. Add three output parameters
            - ListOfElasticsearchRecords (type HitItem List)
            - Success (type Boolean)
            - ErrorMessage (type Text)

2. Inside GetRecords, add the ConfigureElasticsearch action and the GetRecords action from the Elasticsearch API.
    a. Set the input parameters of the GetRecordById action with the input parameter created in the previous step and the output parameters of the ConfigureElasticsearch action.
    b. Set the output parameters created in the previous step with the output parameters from the GetRecords action.

get records_new.png

3. This action is now available in your application for you to get records from your Elasticsearch provider. You can either use the sample approach we provide with the application - which uses a list inside a screen - or:
    a. Set a timer that calls this action.

Delete Records

1. Create a new server action and name it DeleteRecord.

    a. Add an input parameter:
        - RecordId (type text)

    b. Add two output parameters:
        - Success (type Boolean)
        - ErrorMessage (type Text)

2. Inside DeleteRecord, add the ConfigureElasticsearch action and the DeleteRecordById action from the Elasticsearch API.
    a. Set the input parameters of the DeleteRecordById action with the input parameter created in the previous step and the output parameters of the ConfigureElasticsearch action.
    b. Set the output parameters created in the previous step with the output parameters of the DeleteRecordById action.

delete records_new.png

3. This action is now available in your application for you to delete records from your Elasticsearch provider. You can follow the sample approach we provide with the application - which uses a list inside a screen - or:
    a. Delete records based on your data model’s needs.
    b. Set a timer that calls this action.

Parameters and Actions

See below the main actions and parameters required to have the Elasticsearch Web component working as expected.

Configure Basic Authentication
elastic-search-actions;security.png BasicAuthentication (Server Action) Connect with the Elasticsearch provider using Basic Authentication. The provider must be prepared for it. Not every provider accepts Basic Authentication.
Input.png Username (Text) Username to connect to your Elasticsearch provider.
Input.png Password (Text) Password to connect to your Elasticsearch provider.
Register New Records
Server_action.png InsertRecord (Server Action) Inserts a new record.
Input.png ElasticsearchURL (Text) URL to access the Elasticsearch provider.
Input.png Index (Text) First level of indexation.
Input.png Type (Text) Second level of indexation.
Input.png ElasticsearchRecord (ElasticsearchRecord structure) Records values that will be stored in the Elasticsearch provider.
Output.png Success (Boolean) Returns False whenever an error occurs.
Output.png ResultId (Text) Returns the Id of the created record.
Output.png ErrorMessage (Text) Returns the error message when an error occurs.
Get Records
Server_action.png GetRecords (Server Action) Gets a list of Elasticsearch records from a query.
Input.png ElasticsearchURL (Text) URL to access the Elasticsearch provider.
Input.png Index (Text) First level of indexation. Leave it empty if you want to search inside all types. Be careful, Kibana creates a set of records to store its configuration.
Input.png Type (Text) Second level of indexation. Leave it empty if you want to search inside all types.
Input.png  SearchQuery (Text) The value to be searched. By default, the list is limited to 20 records.
Input.png  CharacterConverter (Boolean) Tries to convert unicode characters into a simpler ASCII representation. For example, ß becomes ss.
Input.png  ScoreLimit (Decimal) Limits the score of the returning records. The default value is 0.
Input.png AscendingRankSort (Boolean)  Indicates if the elements are sorted ascending or descending. The default value is False (descending).
Input.png  StartingIndex (Integer) Sets a starting position in the list. The default value is 0.
Input.png  LimitOfRecords (Integer) Sets a limit of records that the list will return. The default value is 20.
Output.png ListOfElasticSearchRecords (List of records) Displays the list of results that match the query.
Output.png Success (Boolean) Returns False whenever an error occurs.
Output.png ErrorMessage (Text) Returns the error message when an error occurs.
Update Records
Server_action.png UpdateRecord (Server Action) Gets an Elasticsearch record by Id.
Input.png ElasticsearchURL (Text) URL to access the Elasticsearch provider.
Input.png RecordId (Text) Id of the record that you want to match.
Input.png ElasticsearchRecord (ElasticsearchRecord structure) Records values that will be stored in the Elasticsearch provider.
Output.png Success (Boolean) Returns False whenever an error occurs.
Output.png ErrorMessage (Text) Returns the error message when an error occurs.
DynamicResults Block
dynamic block.png DynamicResults (Block) Searches for results stored in the Elasticsearch provider and returns a ranked list.
OnFocus: Search for the typed value.
OnInput: Search for the typed value.
OnBlur: Hide the results.
Input.png ElasticsearchURL (Text) URL to access the Elasticsearch provider.
Input.png Index (Type) First level of indexation. Leave it empty if you want to search inside all types. Be careful, Kibana creates a set of records to store its configuration.
Input.png Type (Text) Second level of indexation. Leave it empty if you want to search inside all types.
Input.png  CharacterConverter (Boolean) Tries to convert unicode characters into a simpler ASCII representation. For example, ß becomes ss.
Input.png PartialMatching (Boolean) Decides if the query will check a portion of the term when True or the complete term when False. The default value is False.
Input.png NumberOfCharsBeforeSearch (Boolean) Sets a number of characters typed before the search happens. The default value is 3.
Input.png ScoreLimit (Decimal) Limits the score of the returning records. The default value 0.
Input.png ShowIcon (Boolean) Set to False to show only the title. The image won't appear if the PhotoURL of the result is not defined. The default value is True.
Input.png IconSize (Size identifier) Sets the size of the con. The default value is Small.
Input.png IconColor (Color Identifier) Sets the background color of the icon. The default value is Grey.
Input.png OpenLinkInBlankPage (Boolean) Set to True if you want to open the result in a blank page. The default value is False.
Input.png NumberOfResults (Integer) Sets the number of returned results. The default value is 20.
Input.png Prompt (Text) The hint that describes the expected value for the input. It disappears when the field has focus or is no longer empty.
Input.png NoResultsMessage (Text) Enter a custom error message. The default value is "No results found."

Advanced Scenarios

Refer to the list of actions and parameters for advanced use cases, when using the Elasticsearch Web component.

  • Was this article helpful?