Reporting Integrationedit

Integrating a Kibana application with X-Pack reporting requires a minimum amount of code, and the goal is to not have to modify the Reporting code as we add additional applications. Instead, applications abide by a contract that Reporting uses to determine the information that is required to export CSVs and PDFs.

Important

These pages document internal APIs and are not guaranteed to be supported across future versions of Kibana. However, these docs will be kept up-to-date to reflect the current implementation of Reporting integration in Kibana.

Nav Bar Extensionsedit

X-Pack uses the NavBarExtensionsRegistryProvider to register a navigation bar item for the Dashboard/Discover/Visualize applications. These all use the export-config AngularJS directive to display the Reporting options. Each of the different exportTypes require the AngularJS controller that the contains the export-config directive to implement certain methods/properties that are used when creating the X-Pack reporting job.

If you wish to add Reporting integration via the navigation bar that emulates the way these options are chosen for Dashboards, Visualize and Discover, you can reuse the export-config directive for the time being. Otherwise, you can provide a custom UI that generates the URL that is used to generate the X-Pack reporting job.

This integration will likely be changing in the near future as we move away from AngularJS towards React.

Generate Job URLedit

To generate a new X-Pack reporting job, different export types require different jobParams that are Rison encoded into a URL that abide by the following convention: /api/reporting/generate?jobParams=${rison.encode(jobParams)}. If you use the aforementioned nav bar extensions then this detail will be abstracted away, but if you provide a custom UI for generating the report, you will have to generate the URL and create a POST request to the URL.

CSVedit

Job Parametersedit

If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to the aforementioned generate job url:

interface jobParameters {
  type: string;
  title: string;
  searchRequest: {
    index: string;
    body: object;
  };
  fields: string[];
  metaFields: string[];
  conflictedTypesFields: string[];
  indexPatternId: string;
}

The searchRequest.body should abide by the Elasticsearch Search Request Body syntax

export-config Directiveedit

If integrating with Reporting via the export-config directive, the AngularJS controller that contains the directive should expose the following methods and the export-config directive will POST them to the reporting API:

interface sharingData {
  searchRequest: {
    index: string;
    body: object;
  };
  fields: string[];
  metaFields: string[];
  conflictedTypesFields: string[];
  indexPatternId: string;
}

function getSharingData(): sharingData;

function getSharingType(): string;

function getSharingTitle() string;

The sharingData.searchRequest.body should abide by the Elasticsearch Search Request Body syntax

PDFedit

Job Parametersedit

If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to the aforementioned generate job url:

interface jobParameters {
  objectType: string;
  title: string;
  browserTimezone: string;
  relativeUrls: string[];
  layout: {
    id: string;
    dimensions: {
      height: number;
      width: number;
    };
  };
}

jobParameters.browserTimezone is a string that appears in the tz database jobParameters.layout.id presently only accepts "print" and "preserve_layout" jobParameters.layout.dimensions is only currently used by "preserve_layout"

export-config Directiveedit

If integrating with Reporting via the export-config directive, the AngularJS controller that contains the directive should expose the following methods and the export-config directive will POST them to the reporting API:

function getSharingType(): string;

function getSharingTitle(): string;

The export-config directive will use the browser’s current URL and timezone when generating the job parameters automatically. The export-config directive will also grab the height/width of the element with the data-shared-items-container attribute and use this as the dimensions.

Screenshot capturing attributesedit

When generating the PDF, reporting looks for a number of attributes in the DOM to determine which elements should have their screenshot taken and when the Visualizations are done rendering.

The print layout takes a screenshot of every element with the data-shared-item attribute and includes the individual screenshots in the PDF. The print layout also uses the data-title and data-description attributes on the same HTMLElement as the data-shared-item to specify the title and description that appears right above the individual screenshots.

The preserve layout takes a screenshot of the element with the data-shared-items-container attribute. Additionally, reporting will resize the element with the data-shared-items-container to be the size specified in the layout dimensions. The preserve layout also uses the data-title and data-description attributes on the HTMLElement with the data-shared-items-container attribute to specify the title/description for the entire PDF.

Reporting needs to determine when all of the visualizations have completed rendering, so that it can begin taking screenshots. If there are multiple visualizations, the data-shared-items-count attribute should be specified to let Reporting know how many Visualizations to look for. Reporting will look at every element with the data-shared-item attribute and use the corresponding data-render-complete attribute and renderComplete events to listen for rendering to complete. When rendering is complete for a visualization the data-render-complete attribute should be set to "true" and it should dispatch a custom DOM renderComplete event.