Skip to content

Commit

Permalink
[DOCS] Adds docs about custom URLs in DFA jobs.
Browse files Browse the repository at this point in the history
  • Loading branch information
szabosteve committed Sep 29, 2023
1 parent 96f6c88 commit a50a603
Show file tree
Hide file tree
Showing 5 changed files with 86 additions and 0 deletions.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/en/stack/ml/df-analytics/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ include::ml-dfa-classification.asciidoc[leveloffset=+1]
include::ml-dfa-concepts.asciidoc[leveloffset=+1]
include::ml-how-dfa-works.asciidoc[leveloffset=+2]
include::ml-dfa-scale.asciidoc[leveloffset=+2]
include::ml-dfa-custom-urls.asciidoc[leveloffset=+2]
include::ml-feature-encoding.asciidoc[leveloffset=+2]
include::ml-dfa-feature-processors.asciidoc[leveloffset=+2]
include::ml-feature-importance.asciidoc[leveloffset=+2]
Expand Down
1 change: 1 addition & 0 deletions docs/en/stack/ml/df-analytics/ml-dfa-concepts.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ This section explains the more complex concepts of the Elastic {ml}

* <<ml-dfa-phases>>
* <<ml-dfa-scale>>
* <<ml-dfa-custom-urls>>
* <<ml-feature-encoding>>
* <<ml-feature-processors>>
* <<ml-feature-importance>>
Expand Down
84 changes: 84 additions & 0 deletions docs/en/stack/ml/df-analytics/ml-dfa-custom-urls.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
[role="xpack"]
[[ml-dfa-custom-urls]]
= Adding custom URLs to {dfanalytics-jobs}

You can optionally attach one or more custom URLs to your {dfanalytics-jobs}.
These links can direct you to dashboards, the *Discover* app, or
external websites. For example, you can define a custom URL that provides a way
for users to drill down to the source data from a {regression} job. You can
create a custom URL during job creation under **Additional settings** in the
**Job details** step. Alternatively, you can edit or add new custom URLs in the
job list by clicking **Edit** in the **Actions** menu.

[role="screenshot"]
image::images/ml-dfa-custom-url.png["Creating a custom URL during job creation"]

When you create or edit an {dfanalytics-job} in {kib}, it simplifies the
creation of the custom URLs for {kib} dashboards and the *Discover* app and it
enables you to test your URLs. For example:

[role="screenshot"]
image::images/ml-dfa-custom-url-edit.png["Add a custom URL in {kib}",width=75%]

For each custom URL, you must supply a label. You can also optionally supply a
time range. When you link to *Discover* or a {kib} dashboard, you'll have
additional options for specifying the pertinent {data-source} or dashboard name
and query entities.


[discrete]
[[ml-dfa-url-strings]]
== String substitution in custom URLs

You can use dollar sign ($) delimited tokens in a custom URL. These tokens are
substituted for the values of the corresponding fields in the result index. For
example, a custom URL might resolve to
`discover#/?_g=(time:(from:'$earliest$',mode:absolute,to:'$latest$'))&_a=(filters:!(),index:'4b899bcb-fb10-4094-ae70-207d43183ffc',query:(language:kuery,query:'Carrier:"$Carrier$"'))`.
In this case, the pertinent value of the `Carrier` field is passed to the target
page when you click the link.

TIP: When you create your custom URL in {kib}, the *Query entities* option is
shown only when there are appropriate fields in the index.

The `$earliest$` and `$latest$` tokens pass the beginning and end of the time
span of the data to the target page. The tokens are substituted with date-time
strings in ISO-8601 format. For example, the following API updates a job to add
a custom URL that uses `$earliest$` and `$latest$` tokens:

[source,console]
----------------------------------
POST _ml/data_frame/analytics/flight-delay-regression/_update
{
"_meta": {
"custom_urls": [
{
"url_name": "flight-delay-regression-results",
"url_value": "dashboards#/view/7adfa750-4c81-11e8-b3d7-01146121b73d?_g=(filters:!(),time:('$earliest$',mode:absolute,to:'$latest$'))&_a=(filters:!(),query:(language:kuery,query:''))",
"time_range": "1h",
}
]
}
}
----------------------------------
//TEST[skip:setup:sample_job]

When you click this custom URL, it opens up the *Discover* page and displays
source data for the period one hour before and after the date of the default
global settings.

[TIP]
===============================
* The custom URL links use pop-ups. You must configure your web browser so that
it does not block pop-up windows or create an exception for your {kib} URL.
* When creating a link to a {kib} dashboard, the URLs for dashboards can be very
long. Be careful of typos, end of line characters, and URL encoding. Also ensure
you use the appropriate index ID for the target {kib} {data-source}.
* The dates substituted for `$earliest$` and `$latest$` tokens are in
ISO-8601 format and the target system must understand this format.
* If the job performs an analysis against nested JSON fields, the tokens for
string substitution can refer to these fields using dot notation. For example,
`$cpu.total$`.
* {es} source data mappings might make it difficult for the query string to
work. Test the custom URL before saving the job configuration to check that it
works as expected, particularly when using string substitution.
===============================

0 comments on commit a50a603

Please sign in to comment.