23 October 2018

Kibana Plugin API Changes in 6.5

By Jin Mu

Kibana Plugin API Changes in 6.5 include changes to visualizations response handler, sample data schema, and aggregations.

Visualization Request/Response Handlers

Visualization request and response handlers have been refactored. Changes are required for plugins that provide custom visualizations, whether they use a custom request or response handler or not.

Related PRs: #19061, #22583

New tabify format

The default tabify format (tabular representation of data) has changed to the following structure:

{
  columns: [
    {
      aggConfig: AggConfig,
      id: 'column1',
      title: 'column title',
    },
    //...
  ],
  rows: [
    {
      column1: 10,
      column2: 'sample',
    },
    //...
  ]
}

The main difference is that each row is no longer an array of values, but an object where the key is the column id and the value is the value for that column.

Request handlers

The default (courier) request handler now returns the new tabify format, instead of a raw Elasticsearch response.

If your plugin provides a custom request handler, we recommend that you return the tabified format too. This is not currently required, but will make it easier for your plugin to adjust to upcoming changes.

Response handlers

The old tabify response handler has been removed because the default request handler now returns the tabified format. The default response handler is none, which passes through the request handler’s result.

Also, the response handler doesn’t receive a vis parameter anymore, but rather a single parameter that holds the tabified data.

Legacy response handler

For an easier conversion, you can still use the old tabify format by setting responseHandler: 'legacy' in your visualization type registration. This response handler converts the new tabify format to the old format.

The legacy response handler is deprecated! Only use this if you can’t immediately update your visualization to the new tabify format. We plan to remove the legacy response handler in 7.0.

Basic response handler

The basic response handler has been renamed vislib.

Do NOT use this response handler outside of Kibana.

PR #24396

Sample data now allows multiple indices

The implementation of the 6.4.0 sample data only allowed creation of a single Elasticsearch index. We now allow a sample data set to install one or multiple Elasticsearch indices. Following changes are backward-compatible.

Sample data schema

The sample data schema has been updated to support multiple indices.

// old schema
{
    id: 'flights',
    name: 'Sample flight data',
    description: 'Sample data, visualizations, and dashboards for monitoring flight routes.',
    previewImagePath: '/plugins/kibana/home/sample_data_resources/flights/dashboard.png',
    overviewDashboard: '7adfa750-4c81-11e8-b3d7-01146121b73d',
    defaultIndex: 'd3d7af60-4c81-11e8-b3d7-01146121b73d',
    dataPath: path.join(__dirname, './flights.json.gz'),
    fields: fieldMappings,
    timeFields: ['timestamp'],
    currentTimeMarker: '2018-01-09T00:00:00',
    preserveDayOfWeekTimeOfDay: true,
    savedObjects: savedObjects,
}
// new schema
{
    id: 'flights',
    name: 'Sample flight data',
    description: 'Sample data, visualizations, and dashboards for monitoring flight routes.',
    previewImagePath: '/plugins/kibana/home/sample_data_resources/flights/dashboard.png',
    overviewDashboard: '7adfa750-4c81-11e8-b3d7-01146121b73d',
    defaultIndex: 'd3d7af60-4c81-11e8-b3d7-01146121b73d',
    savedObjects: savedObjects,
    dataIndices: [
        {
            id: 'flights',
            dataPath: path.join(__dirname, './flights.json.gz'),
            fields: fieldMappings,
            timeFields: ['timestamp'],
            currentTimeMarker: '2018-01-09T00:00:00',
            preserveDayOfWeekTimeOfDay: true,
        }
    ]
}

Install response

The response from POST /api/sample_data/{id} has been modified.

// old response
{
  docsLoaded: 13059, 
  kibanaSavedObjectsLoaded: 21
}
//new response
{
  elasticsearchIndicesCreated: {
    kibana_sample_data_flights: 13059
  }, 
  kibanaSavedObjectsLoaded: 21
}

PR #23230

AggConfig field param

Every aggregation (AggConfig) with field parameter type must now set the type to field. Previously, setting the name to field was sufficient.

We don’t recommend writing your own aggregations. We don’t consider this to be a public API, and it’s very likely this API will change in the future. Because we know that a couple of plugins use this, we are announcing this change here.

PR #22756

Visualization icons

The icon property, used for registering a visualization type that accepts a class name (for example, to set a Font Awesome icon), has been renamed to legacyIcon and will be removed in 7.0.0.

The icon property now expects a valid EUI icon type. As an alternate to using an EUI icon, you can use the image property, which is set to the src attribute of an img. Thus, you can also use the image property to set an image as a data URI (for example, by importing it via Webpack).

PR #22679

Time zone in application plugins

If you are using import 'ui/autoload/all'; in your application plugin (or import 'ui/autoload/settings'; directly), the timezone and start of the week configured in Kibana will now correctly be set to moment and thus be used by Kibana core services, such as the visualize loader API, to embed visualizations.

PR #22623

exportTypesRegistry removed

exportTypesRegistry was removed from the client-side. exportTypesRegistry was used for registering Reporting export types for the UI. exportTypesRegistry still exists for registering export types with the server.

PR #22596

Visualize loader

The visualize loader for embedding visualizations will now set display: flex on the element you pass in, so that all visualizations are rendered correctly.

The embedVisualizationWithSavedObject method is now deprecated. Instead, use embedVisualizationWithId and load a visualization by its id.

PR #22595

Custom no data screen

By default, Kibana will show “No data” to the user if no data was retrieved for a visualization. You can disable this behavior by specifying useCustomNoDataScreen: true in your visualization type registration. This flag replaces the earlier handleNoData flag due to its confusing name. The handleNoData flag no longer has an effect.

PR #19061