[DOCS] Add skip_time to Flush Jobs API (elastic/x-pack-elasticsearch#1955)

Original commit: elastic/x-pack-elasticsearch@352bd336d8

docs/build.gradle

@@ -65,7 +65,6 @@ buildRestTests.expectedUnconvertedCandidates = [
         'en/watcher/troubleshooting.asciidoc',
         'en/ml/api-quickref.asciidoc',
         'en/rest-api/ml/delete-snapshot.asciidoc',
-        'en/rest-api/ml/flush-job.asciidoc',
         'en/rest-api/ml/forecast.asciidoc',
         'en/rest-api/ml/get-bucket.asciidoc',
         'en/rest-api/ml/get-overall-buckets.asciidoc',

docs/en/rest-api/ml/flush-job.asciidoc

@@ -35,15 +35,21 @@ opened again before analyzing further data.
 ==== Query Parameters
 
 `advance_time`::
-  (string) Specifies that no data prior to the date `advance_time` is expected.
+  (string) Specifies to advance to a particular time value. Results are
+  generated and the model is updated for data from the specified time interval.
+
+`calc_interim`::
+  (boolean) If true, calculates the interim results for the most recent bucket
+  or all buckets within the latency period.
 
 `end`::
   (string) When used in conjunction with `calc_interim`, specifies the range
   of buckets on which to calculate interim results.
 
-`calc_interim`::
+`skip_time`::
-  (boolean) If true, calculates the interim results for the most recent bucket
+  (string) Specifies to skip to a particular time value. Results are not
-  or all buckets within the latency period.
+  generated and the model is not updated for data from the specified time
+  interval.
 
 `start`::
   (string) When used in conjunction with `calc_interim`, specifies the range of
@@ -54,27 +60,55 @@ opened again before analyzing further data.
 
 You must have `manage_ml`, or `manage` cluster privileges to use this API.
 For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
-//<<privileges-list-cluster>>.
 
 
 ==== Examples
 
-The following example flushes the `farequote` job:
+The following example flushes the `total-requests` job:
 
 [source,js]
 --------------------------------------------------
-POST _xpack/ml/anomaly_detectors/farequote/_flush
+POST _xpack/ml/anomaly_detectors/total-requests/_flush
 {
   "calc_interim": true
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[skip:todo]
+// TEST[setup:server_metrics_openjob]
 
 When the operation succeeds, you receive the following results:
 [source,js]
 ----
 {
-  "flushed": true
+  "flushed": true,
+  "last_finalized_bucket_end": 1455234900000
 }
 ----
+// TESTRESPONSE[s/"last_finalized_bucket_end": 1455234900000/"last_finalized_bucket_end": $body.last_finalized_bucket_end/]
+
+The `last_finalized_bucket_end` provides the timestamp (in
+milliseconds-since-the-epoch) of the end of the last bucket that was processed.
+
+If you want to flush the job to a specific timestamp, you can use the
+`advance_time` or `skip_time` parameters.  For example, to advance to 11 AM GMT
+on January 1, 2018:
+
+[source,js]
+--------------------------------------------------
+POST _xpack/ml/anomaly_detectors/total-requests/_flush
+{
+  "advance_time": "1514804400"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:server_metrics_openjob]
+
+When the operation succeeds, you receive the following results:
+[source,js]
+----
+{
+  "flushed": true,
+  "last_finalized_bucket_end": 1514804400000
+}
+----
+// TESTRESPONSE