How to use the Elasticsearch tile

About Elasticsearch tiles

You can use Elasticsearch tiles to show data from your Elasticsearch instance. Since Elasticsearch tiles are designed specifically to integrate with Elasticsearch, they offer you a convenient way to access your Elasticsearch indices and enter search queries.

You need to add your Elasticsearch instance as a provider before you can use Elasticsearch tiles (see How to add an Elasticsearch provider in SquaredUp).

How to configure an Elasticsearch tile

Note: If you don't already have an Elasticsearch provider, you need to create one before you can configure an Elasticsearch tile (see How to add an Elasticsearch provider in SquaredUp).

1. Add a new tile to a dashboard and choose the Elasticsearch tile.
   
   
   
2. Select the visualisation for Elasticsearch tile, for example "Scalar", and click next.
   
   
3. Provider:
   Select your Elasticsearch provider from the list of providers and click next.
   Note: The list shows only Elasticsearch providers. If you have added other providers of a different type, you won't see them in the list of providers.
   
   
4. Query:
   Index:
   Click in the field to see a list of all indices that exist in the Elasticsearch provider you chose. Choose the index or indices you want to use for your tile.
   Search type:
   Here you enter the search query for the data you want to display. You can choose between the options lucene, where you need to use Lucene query syntax, and query dsl, where you need to use Query DSL syntax. If a simple lucene query is not sufficient for your data request, switch to query dsl to specify your request. You can find more help about using Query DSL here: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html
   
   Note: For your queries, you need to know the names of the columns in the index you are using. You can find the column names in your Elasticsearch index.
   Tip: You can use the templates button to access search templates you have created in Elasticsearch.
   Tip: If you want to insert a date value, you can use the mustache button to get templates for date values.
   Tip: You can aggregate your search data to summarise the results. For example, if your search data only contains tickets and their state, you can aggregate the search result to get the total number of tickets. You can find more help about how to aggregate search data here: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html
   
   Click next.
   
   
5. Response data (not for grid visualisation):
   Here you can see the response data from the query in the response data field. For most use cases, you need to limit the query response to the specific property you want to use for your data. You pick the property you want to use by entering the key path to the property in the key path field. If you don't need to limit the query result and can use the entire response (for example, if the response data returns the array you want to use at the root of the response), you can leave the key path field empty.
   
   The structure of the response data tells you where to find the property you want to use.
   Example:
   

    },
   "hits": {
      "total": {
         "value": 8157,
         "relation": "eq"
   },

   If your response data looks like the example above and you want to display the "value" of "hits", you need to enter hits.total.value in the key path field.
   If you want to use the whole array of "hits", you need to enter hits in the key path field.
   
   
   
   Click next.
   
   
6. Data mapping (not for grid or scalar visualisations):
   

   Grouping:

   Here you define what "things" you want the graph to represent. For example, if you want to see the response time of different servers, the grouping would be servers. If you want to see the amount of tickets, your grouping would be tickets.

   To enter your grouping, you have to find the property that contains it. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the grouping you want your graph to show.

   Note: If your grouping needs more than one property, you can combine multiple properties. For example, if you want to see the disk space on the C: drive of different computers, your grouping needs to be c: drive and computer. You can combine them in one mustache {{PropertyForComputer + PropertyForC:Drive}} or keep them in separate mustaches {{PropertyForComputer} {{PropertyForC:Drive}}.

   Info (except for status blocks and icons) : The property you pick will automatically be used as a label for your bar graphs. You can change the label in the label settings. If you use the grouping as the label, you can add add text or separators to make the label easier to read, for example This is the {{PropertyForC:Drive}} on computer {{PropertyForComputer}}.

   Metric:

   Here you define which value the graph will show. For example, if you want to see the response time of different servers, your metric would be response time. If you want to see the amount of tickets, your metric would be amount (of tickets).

   To enter your metric value, you have to find the property that contains that value. You can use the mustache picker to see every property returned from the response data. Pick the property that contains the value you want your graph to show. 

   Note: The metric value must be a numeric object. If an API returns values as strings, you can convert them from a string to a numeric object with the parseFloat() function.

   Info: You can manipulate the value by adding operators to add, substract, divide or multiply. You can pick additional properties from the response data or insert plain text for those functions. For example, if you want to multiply two properties you can do that by entering {{PropertyForMetricValue*PropertyForOtherMetricValue2}} . If you want to change Kb in Gb you can divide the value by 1024: {{PropertyForMetricValue/1024}}. You can also use more elaborate functions according to JavaScript syntax.

   Extract multiple metrics: If you want to see more than one value for your grouping, you can tick the "Extract multiple metrics" checkbox. You can manipulate those metrics exactly like the first metric you chose. The metrics won't affect each other, they are all treated as separate metrics for your grouping. For example, if you want to see the metrics response time and amount of tickets in a bar graph, you will see two bars in your graph for tickets. One bar will show you value for the response time, the other bar will show you the value for the amount.

7. Configure the settings for the visualisation you chose. See Settings for different visualisations
8. Click done to save the tile.
   The tile now shows data according to your settings.

Settings for different visualisations

Bar Graph

Data range

Data Range option allows you to choose the range of the y-axis:

• percentage: Shows 0 to 100.
• fit to data: Shows the data minimum to data maximum.
• fit to data (from zero): Shows from 0 to the data maximum.
• custom: Allows you to specify the min and max.
• custom fit: Allows you to specify the min and max limits, so that data outside your settings will not be shown. If all the data falls within your specified ranges then the y-axis range will fit to the data rather than your caps.

Sort

Here you can choose how you want to sort the graph. You can sort by value (ascending or descending) or label (alphabetically ascending or descending)

Label

Allows you to change the label of the results.

auto: The label is created from the data mapping - grouping field.

custom: Using the custom option you can create your own advanced label to specify exactly how you want the results to be displayed (using both static text and dynamic properties) to ensure that the results always make sense.

Custom labels use Mustache syntax to insert properties. If you're familiar with mustache, you can specify advanced labels that can transform properties prior to displaying them (such as showing only a portion of text, converting a number or reformatting a date).

For example you can use the JavaScript split method to separate properties into substrings to make the result more readable.

Color

Here you can turn graph colour matching on and off, see How to enable graph colour matching.

Donut

Display

size mode: Allows you to change from the default to a fill mode where the donut will fit the space available.

show legend: Allows you to display a key to the colours on the donut, and the legend size slider will change the size of the legend text.

color palette: Gives you a choice of several colour selections suited towards different data sets such as priorities and health.

Scalar

Font size:
Allows you to set the font size of the value in the tile.

Unit:
Allows you to add a unit to the value displayed in the Scalar tile. For example, if your value shows a time in milliseconds, you can enter "ms" or if your value shows pageviews, you can enter "pageviews".

Value formatter:
Allows you to format the value by using the mustache picker. For example, you can round the value up or down or convert it.

Grid

Grid columns

Grid columns opens the grid designer, where you can show or hide columns, change the order of columns, edit column names or add custom columns, see How to use the Grid Designer.

Grid options

Row link: Allows you to turn the rows of the grid into hyperlinks that lead you to more information about the object in this row. For example, when you create a grid with ServiceNow tickets, you can link each row to the corresponding ticket. A click on the row then opens the ticket in ServiceNow. To find out how the URL has to look like, take the URL to a specific ticket (or any other object you want to link to) as a template. Find the object ID in the URL and replace it with the value from the object ID column. You can use the moustache picker to select the column that contains the object ID.
Example:
The URL to a specific ticket is: https://my-ticket-system.com/ticketID-123456 The column that contains the ticket ID is called sys_id
In this case, the URL would look like this: https://my-ticket-system.com/ticketID-{{sys_id}}

Show column headers: You can choose between showing or hiding the header for all columns.

Status (Blocks or Icons)

How to use the Status Icons and Status Blocks tiles

Link options

item link: Allows you to turn the icons or blocks into hyperlinks that lead you to more information about the object each icon or block represents. For example, when you create a status tile for ServiceNow tickets, you can link each icon or block to the corresponding ticket. A click on the icon or block then opens the ticket in ServiceNow. To find out how the URL has to look like, take the URL to a specific ticket (or any other object you want to link to) as a template. Find the object ID in the URL and replace it with the value from the object ID column. You can use the moustache picker to select the object that contains the object ID.
Example:
The URL to a specific ticket is: https://my-ticket-system.com/ticketID-123456 The column that contains the ticket ID is called sys_id
In this case, the URL would look like this: https://my-ticket-system.com/ticketID-{{sys_id}}

Sort

Sort allows you to change the order of the results displayed, and group them by characteristics.

default: By default, the sorting of the blocks or icons depends on the data source. This can be alphabetical sorting or the order in which data comes back from an API request.

sort by: label or health state, ascending or descending

group by: label or health state, ascending or descending

Blocks (only available for Block Status tiles)

Here you can set the number of columns for the blocks, their height and the font size within the blocks.

Label

Allows you to change the label of the results.

name: The default label is name.

custom: Using the custom option you can create your own advanced label to specify exactly how you want the results to be displayed (using both static text and dynamic properties) to ensure that the results always make sense.

Custom labels use Mustache syntax to insert properties. If you're familiar with mustache, you can specify advanced labels that can transform properties prior to displaying them (such as showing only a portion of text, converting a number or reformatting a date).

For example you can use the JavaScript split method to separate properties into substrings to make the result more readable.

How to use Custom Labels

Sublabel

Allows you to add a sublabel of the results.

custom: Using the custom option you can create your own advanced label to specify exactly how you want the results to be displayed (using both static text and dynamic properties) to ensure that the results always make sense.

Custom labels use Mustache syntax to insert properties. If you're familiar with mustache, you can specify advanced labels that can transform properties prior to displaying them (such as showing only a portion of text, converting a number or reformatting a date).

For example you can use the JavaScript split method to separate properties into substrings to make the result more readable.

none: By default, no sublabels are shown.

How to use Custom Labels