Skip to main content

SILK UI Framework

 

OutSystems

Elasticsearch Mobile 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 Mobile component allows you to integrate an Elasticsearch engine into your application.

elasticsearch-mobile.jpg

How to Use the Elasticsearch Mobile 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.

manage dependencies_new.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:
    - ElasticsearchAuthUsername (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: ElasticsearchAuthUsername 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 the HeaderRight placeholder of the Common\Layout of your screen. This block can only be used inside this placeholder.

UI block_1.png

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

UI block_2.png

3. Inside the OnInitialize 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.

UI block_3.png

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 fromthe 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 uses a form inside a screen - 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 Mobile 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 (Type) 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 (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  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 IconColor (Color Identifier) Sets the background color of the icon. The default value is the Primary color.
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."
Input.png OverlayColor (Color Identifier) Sets the background overlay color. The default value is the Primary color.
Input.png ClearResultsOnClose (Boolean) Clears the search results when the Close button is pressed. The default value is True.

Advanced Scenarios

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

  • Was this article helpful?