From d0419554d7adfa48bfedfddf40f6580715765b37 Mon Sep 17 00:00:00 2001 From: Tim Sullivan Date: Mon, 1 Apr 2024 08:02:36 -0700 Subject: [PATCH] [Reporting/Docs] Update Developer API docs (#179723) ## Summary Part of documentation updates required for https://github.com/elastic/kibana-team/issues/720 * Removes outdated info about Angular directives * Remove outdated info about the original CSV export type * Add explanation of what an Export Type is * More detail about the job parameters for each export type * Add tips to debug using POST URLs --- .../development/csv-integration.asciidoc | 67 ++++++++--------- .../architecture/development/index.asciidoc | 61 ++++++++++++--- .../development/pdf-integration.asciidoc | 74 +++++++++---------- 3 files changed, 114 insertions(+), 88 deletions(-) diff --git a/docs/developer/architecture/development/csv-integration.asciidoc b/docs/developer/architecture/development/csv-integration.asciidoc index 45b4e50e06240..1d659f611f04b 100644 --- a/docs/developer/architecture/development/csv-integration.asciidoc +++ b/docs/developer/architecture/development/csv-integration.asciidoc @@ -2,50 +2,43 @@ === CSV [float] -==== Job parameters -If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to -the aforementioned generate job url: +==== Job parameters of CsvSearchSource +The export type to generate CSV reports and is available in Discover uses "search source" objects. This export type is called +`csv_searchsource` in the code. A configuration for a CSV report job is represented with an interface that includes the +`BaseParams` and the following fields. To create a request for a CSV report, these required job parameters are Rison encoded into +a query string variable of the report generation URL: ---- -interface jobParameters { - type: string; - title: string; - searchRequest: { - index: string; - body: object; - }; - fields: string[]; - metaFields: string[]; - conflictedTypesFields: string[]; - indexPatternId: string; -} +interface JobParamsCSV { + searchSource: SerializedSearchSourceFields; <1> + columns?: string[]; <2> +}; ---- - -The `searchRequest.body` should abide by the {ref}/search-search.html[Elasticsearch Search Request Body] syntax +<1> An object of serialized data that internally represents a search object in Kibana. It will contain a reference to a DataView +saved object. +<2> An array of field names to include as columns in the CSV report. [float] -==== `export-config` Directive -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: +==== Job parameters of CsvFromSavedObject +A newer export type to generate CSV reports is available, currently only by API. This export type is called `csv_v2` in the code. ---- -interface sharingData { - searchRequest: { - index: string; - body: object; - }; - fields: string[]; - metaFields: string[]; - conflictedTypesFields: string[]; - indexPatternId: string; -} - -function getSharingData(): sharingData; - -function getSharingType(): string; +interface JobParamsCsvFromSavedObject { + locatorParams: LocatorParams[]; <1> +}; +---- +<1> The `locatorParams` value is controlled by the Discover application and identifies a search loaded in Discover, including the +selection of DataView, columns and filters. Only a single value in the array is permitted in the `createJob` method. -function getSharingTitle() string; +[float] +==== Job payload +After the job parameters are received by the route handler for the report generation URL, an additional field is automatically +added to the fields from job parameters: ---- - -The `sharingData.searchRequest.body` should abide by the {ref}/search-search.html[{es} Search Request Body] syntax \ No newline at end of file +interface TaskPayloadCSV { + pagingStrategy: 'scan' | 'pit' <1> +} +---- +<1> The `pagingStrategy` value is taken from the value of the `xpack.reporting.csv.scroll.strategy` setting in kibana.yml and used +to control how the `runTask` method pages through all of the data. diff --git a/docs/developer/architecture/development/index.asciidoc b/docs/developer/architecture/development/index.asciidoc index 4e86c803bd82d..87f091ce3265d 100644 --- a/docs/developer/architecture/development/index.asciidoc +++ b/docs/developer/architecture/development/index.asciidoc @@ -1,11 +1,8 @@ [role="xpack"] [[reporting-integration]] == Reporting integration -Integrating a {kib} application with the {report-features} 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 -{report-features} use to determine the information that is required to export -CSVs and PDFs. +Applications abide by a contract that {report-features} use to determine the information that is required to request exports of +data from {kib}, and how to generate and store the reports. [IMPORTANT] ============================================== @@ -14,16 +11,56 @@ However, these docs will be kept up-to-date to reflect the current implementatio ============================================== [float] -[[reporting-nav-bar-extensions]] +=== Reporting Export Types +"Export Types" are pieces of code that plug into the {kib} Reporting framework, and are responsible for exporting data on behalf +of a {kib} application. These pieces of code are implemented as TypeScript classes that extend an abstract base class, and +implement methods for controlling the creation of report jobs, and asynchronously generating report contents. Their `createJob` +methods handle requests to create report jobs, by accepting jobParams objects and returning "task payload" objects. Their +`runTask` methods generate the report contents by accepting the task payload object created from the `createJob` function, which +is then stored in a system index in Elasticsearch. + +[float] +[[reporting-share-service-registrations]] === Share menu extensions -X-Pack uses the `share` plugin of the Kibana platform to register actions in the share menu. +X-Pack services, such as the {report-features}, register with the `share` plugin of the Kibana platform to register additional +actions available to make content shareable. + +[float] +=== Generate a report job URL +To generate a new reporting job, different export types require different `jobParams` objects, which are Rison-encoded and used as +a `jobParams` query string variable in the Reporting generation endpoint URL. If you use the aforementioned +<> then this detail will be abstracted away. If your +application does not use the Share menu extensions, you will have to generate the URL and create a POST request to the URL. [float] -=== Generate job URL -To generate a new 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 <> 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. +=== Basic job parameters +Certain fields of Reporting job parameters are required for every type of export. + +---- +interface BaseParams { + title: string; <1> + objectType: string; <2> + browserTimezone: string; <3> + version: string; <4> +}; +---- +<1> The `title` for the report. This is shown in the listing of reports in **Stack Management > Alerts and +Insights > Reporting** and used as the filename when the report is downloaded. +<2> The `objectType` field is automatically added when using internal Reporting APIs. This value used for choosing an icon for the +report job in the listing of reports in {kib}. +<3> The `browserTimezone` field is automatically added when using internal Reporting APIs to craft the job parameters. This is +used to correctly format time-based data in the user's desired timezone. +<4> The `version` field is automatically added when using internal Reporting APIs. This is used in cases where job parameters are +reused after an upgrade of Kibana, and a migration may be needed. include::csv-integration.asciidoc[] include::pdf-integration.asciidoc[] + +=== Using POST URLs for debugging +Developers can capture a POST URL from a reporting-capable application to access the `jobParams` query string variable in the +public API report generation endpoint. The query string variable can be passed through a URL de-encoder and then passed through a +Rison-to-JSON converter to make the job parameters human-readable. + +If attempting to send requests to the POST URL to test generating a report, use a shell script containing the curl command that +POSTs the request. This will avoid any unintentional character escaping that can happen if running the curl command in an +interactive shell. diff --git a/docs/developer/architecture/development/pdf-integration.asciidoc b/docs/developer/architecture/development/pdf-integration.asciidoc index e9f32de41baab..2d0bfbb8e9e2f 100644 --- a/docs/developer/architecture/development/pdf-integration.asciidoc +++ b/docs/developer/architecture/development/pdf-integration.asciidoc @@ -1,53 +1,47 @@ [float] -=== PDF +=== PDF and PNG [float] ==== Job parameters -If integrating with Reporting via a custom UI, the following job parameters must be Rison encoded and posted to -the aforementioned generate job url: +A configuration for a PDF or PNG report job is represented with an interface that includes the `BaseParams` and the following +fields. To create a request for one of these report types, these required job parameters are encoded into a query string variable +of the report generation URL: ---- -interface jobParameters { - objectType: string; - title: string; - browserTimezone: string; - relativeUrls: string[]; +interface BaseParamsPDFV2 { layout: { - id: string; + id: string; <1> dimensions: { height: number; width: number; }; }; + locatorParams: LocatorParams[]; <2> } ----- - -`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" - -[float] -==== `export-config` directive -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; +interface BaseParamsPNGV2 { + layout: { + id: string; <3> + dimensions: { + height: number; + width: number; + }; + }; + locatorParams: LocatorParams; <4> +} ---- - -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. +<1> The available `layout.id` options for PDF exports are `preserve_layout`, `print`, and `canvas`. These control how dashboard +panels are captured and positioned into pages in the PDF file. +<2> The `locatorParams` value is controlled by the application loaded in the browser for which a screenshot will be captured. The +parameters to generate a PDF report allow an array of `locatorParams` to support multi-page PDF reports. +<3> The only available `layout.id` option for PNG exports is `preserve_layout`. +<4> The parameters to generate a PNG report allow a single value for `locatorParams`. [float] -==== Screenshot capturing attributes -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. +==== How applications make themselves screenshot-capable +When generating the PDF, the headless browser launched by the Reporting export type runs a script that 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` @@ -58,10 +52,12 @@ reporting will resize the element with the `data-shared-items-container` to be t 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. +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. -If the reporting job uses multiple URLs, before looking for any of the `data-shared-item` or `data-shared-items-count` attributes, it waits for a `data-shared-page` attribute that specifies which page is being loaded. +If the reporting job uses multiple URLs, before looking for any of the `data-shared-item` or `data-shared-items-count` attributes, +it waits for a `data-shared-page` attribute that specifies which page is being loaded.