Skip to main content

Inputs & Tokens

I've gotta say we've got a pretty good looking dashboard coming along so far, but there is more of the journey left still my apprentice.

What if I told you that you can actually make dashboards dynamic?! There are many who aren't as trained in The Force Cribl Search as you are. Creating dynamic dashboards is a great way to give those users access to the analytics they need, and even allow them to manipulate the data presented, without knowledge of the Cribl Search language. This is done using inputs and tokens.

Inputs​

Inputs help constrain the view of visualization panels in a dashboard by linking them to specific data sources. When you save an input, a new input box at the top of your dashboard displays values related to the input you created. Selecting options in the input box changes the display of data in any linked visualizations. There are several types of inputs available to you.

Dropdown inputs allow users to choose from a list of values you’ve specified to constrain linked visualization panels to those values. The list of values can be static (where you type all options available to the user), or dynamic (where the results of a search provide the values of the dropdown).

Time Range​

The Time Range input allow users to limit any visualization in a dashboard to a specific time period. In essence this is a time picker for your dashboard. Changing the time in the time input only affects the panels configured to reference the input. All other panels will continue to use the time range configured within their panels.

Text​

The Text input enables users to enter freeform text so that linked visualization panels display only data with that text value. Think of this as a fancy free-text search box.

Number​

The Number input allows users to enter a number. Optionally, you can enter a default value and minimum and maximum values.

Adding Inputs​

It's time to supercharge this dashboard with a few inputs.

important
  1. While in Edit mode, click the Add dropdown.
  2. Click Input.
  3. For Type ensure Dropdown is selected.
  4. For the Title enter Provider Types.
  5. For input_ID enter provider_type.
    tip

    The input_ID is how you will reference this input when linking panels to the input. Every input must have an input_ID. By default, a generic input_ID is populated, but using a descriptive input_ID (containing alphanumeric characters, underscores, and hyphens only) is highly recommended as it makes it easier to know what each input is used for.

  6. For the HOW TO POPULATE THE DROPDOWN option select Run a Search.
  7. In the query box enter: 
    dataset="$vt_datasets"
    | project provider.type
    | distinct provider_type
    | sort by provider_type asc
  8. For the Field name type provider_type.
  9. For the Default value field enter *.
  10. Toggle Multiselect to Yes.
  11. Click Search.
  12. Close the Edit modal.
  13. Click Save.

At this point, the input will have been added to the top of your dashboard. You can click the dropdown on your input to see if results are showing up as expected. For this input, we are using a query that lists all of our datasets and telling our dropdown input to use the id field from our query as the list of values for the input. If configured correctly we should be able to see a list of datasets when we expand the dropdown.

Tokens​

Once the input is configured it must be linked to the panels that you would like to have leverage the input's value. This is where tokens come into play. The token is essentially a variable that stores the input value. Anywhere the token is placed in a query will be replaced with the actual value of the input that corresponds to that token. If the input value changes, so does the token value.

The format of a token in the input's ID surrounded by the $ character. For example, the token that we would need to use for the provider_type input that we created would be $provider_type$.

To make use of our new input let's add the token to a couple of panels.

important
  1. Click the edit edit icon icon at the top right of the Datasets per Provider panel.
  2. Replace the query with: 
    dataset="$vt_datasets" id in ("cribl*", "default*") provider.type in($provider_type$)
    | summarize datasets=dcount(id) by provider.type
    note

    The change that we've made here is we've added provider.type in($provider_type$) after our id filter. This will replace our token of $provider_type$ with whatever we select from our input, effectively filtering our entire result set to our input's value.

  3. Click Search.
  4. Close the Edit modal.
  5. Click Save.
  6. Click the edit edit icon icon at the top right of the Datasets panel.
  7. Replace the query with: 
    dataset="$vt_datasets" id in ("cribl*", "default*") provider.type in($provider_type$)
    | project dataset=id, description
  8. Click Search.
  9. Close the Edit modal.
  10. Click Save.

Let's see how we did!

important
  1. Clear the contents of the Provider Types dropdown.
  2. Select 2-3 provider types.
  3. Click Apply.

And voila! Both panels should now show updated results that only apply to the selected provider types.

Adding a Time Range Input​

Using the time range input type has a slightly different workflow.

important
  1. While in Edit mode, click the Add dropdown.
  2. Click Input.
  3. For Type select Time Range.
  4. For the Title enter Time Range.
  5. For the input_ID enter timepicker.
  6. Close the Edit modal.

Now we've added a Time Range input to our dashboard. To visually show it's functionality we'll create a new panel that is better suited for showing data over time.

important
  1. While in Edit mode, click the Add dropdown.
  2. Click Visualization.
  3. For the Title enter Searches by Dataset.
  4. In the query box enter: 
    dataset="$vt_jobs"
    | project _time, id, dataset=resolvedDatasets
    | mv-expand dataset
    | timestats searches=dcount(id) by dataset
  5. Click Search.
  6. For the Type select Area.
  7. Above the query box, click the time unit (ie. hour ago, days ago, etc.).
  8. Click the Link tab.
  9. For Time range input select Time Range (this is the input we just created).
  10. Click Apply.
  11. Close the Edit modal.
  12. Click Save.

Awesome job. Let's take it for a spin.

important
  1. Click the Time Range input.
  2. Change the time from 1 hour ago to 6 hours ago.
  3. Click Apply.

You can see our Searches by Dataset panel has magically updated to reflect the longer time period.