documentation for journal index and templating function

docs/pages/keyconcepts/templating/templating.rst

@@ -94,6 +94,10 @@ Additional data can come from helper methods. These are the ones Hoverfly curren
 +-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
 | Query CSV data source where ID = 3 and return its name    | ``{{csv 'test-csv' 'id' '3' 'name'}}``                    |  John Smith                             |
 +-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
+| Query Journal index where index value = 1 and return Name |                                                           |                                         |
+|  from associated Response body in journal entry.          | ``{{journal "Request.QueryParam.id" "1"                   |                                         |
+|                                                           |     "response" "jsonpath" "$.name"}}                      |  John Smith                             |
++-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
 
 Time offset
 ~~~~~~~~~~~
@@ -230,6 +234,33 @@ Example: Start hoverfly with templating CSV datasource(student-marks.csv) provid
 +-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
 
 
+Journal
+~~~~~~~
+
+Journal Entry can be queried using its index and its extracted value.
+
+Syntax
+.. code-block::
+    journal "index name" "extracted value" "request/response" "xpath/jsonpath" "lookup query"
+
+
+"index name" should be the same key expression you have specified when you enable the journal index.
+"extracted value" is for doing a key lookup for the journal entry from that index.
+"request/response" specify if you want to get data from the request or response.
+"xpath/jsonpath" specify whether you want to extract it from xpath or json path expression.
+"lookup query" either jsonpath or xpath expressions to parse the request/response data.
+
+Example:
+.. code:: json
+
+    {
+        "body": "{\"name\": \"{{{{journal "Request.QueryParam.id" "1" "response" "jsonpath" "$.name"}}\"}"
+    }
+
+In above example, we are querying name from JSON response in the journal entry where index QueryParam.id that has value 1 will be pointing to.
+
+
+
 
 
 

docs/pages/reference/api/api.rst

@@ -785,7 +785,7 @@ GET /api/v2/journal
 """""""""""""""""""
 Gets the journal from Hoverfly. Each journal entry contains both the request Hoverfly received and the response
 it served along with the mode Hoverfly was in, the time the request was received and the time taken for Hoverfly
-to process the request. Latency is in milliseconds.
+to process the request. Latency is in milliseconds.  It also returns its corresponding indexes.
 
 It supports paging using the ``offset`` and ``limit`` query parameters.
 
@@ -840,11 +840,22 @@ Running hoverfly with ``-journal-size=0`` disables logging and 500 response is r
             ]
           }
         },
+        "id":"mOBdPSIIBbjNqBvpZ8H-",
         "mode": "simulate",
         "timeStarted": "2017-07-17T10:41:59.168+01:00",
         "latency": 0.61334
       }
     ],
+    "indexes": [
+    {
+      "name": "Request.destination",
+      "entries": [
+        {
+          "key": "hoverfly.io",
+          "journalEntryId": "mOBdPSIIBbjNqBvpZ8H-"
+        }
+      ]
+    }],
     "offset": 0,
     "limit": 25,
     "total": 1
@@ -877,6 +888,69 @@ Filter and search entries stored in the journal.
         }
     }
 
+-------------------------------------------------------------------------------------------------------------
+
+
+GET /api/v2/journal/index
+"""""""""""""""""""""""""
+Gets all the journal indexes from Hoverfly. Each Index contains key, extracted value for that particular key
+and journal index id to which it is pointing to.
+
+
+**Example response body**
+::
+    [
+      {
+        "name": "Request.QueryParam.id",
+        "entries": [
+          {
+            "key": "100",
+            "journalEntryId": "ZCyiQtamEtwi-NNU9RT1"
+          },
+          {
+            "key": "101",
+            "journalEntryId": "YFU5dm2uDZ4UStX3ldkX"
+          }
+        ]
+      },
+      {
+        "name": "Request.QueryParam.name",
+        "entries": [
+          {
+            "key": "Test1",
+            "journalEntryId": "ZCyiQtamEtwi-NNU9RT1"
+          },
+          {
+            "key": "Test2",
+            "journalEntryId": "YFU5dm2uDZ4UStX3ldkX"
+          }
+        ]
+      },
+    ]
+
+
+-------------------------------------------------------------------------------------------------------------
+
+
+POST /api/v2/journal/index
+""""""""""""""""""""""""""
+
+Allow a user to set journal indexing by specifying index key/name. Index name is "request-query" shares the same syntax as the one for templating, such as Request.QueryParam.myParam or Request.Header.X-Header-Id.[1]
+It’s used for extracting the data from the journal entry to use as a key for that entry.  It returns all the journal indexes that have been set.  It indexes pre-existing or new journal entries.
+
+**Example request body**
+::
+    {
+        "name":"Request.QueryParam.myParam"
+    }
+
+-------------------------------------------------------------------------------------------------------------
+
+
+DELETE /api/v2/journal/index/:index-name
+""""""""""""""""""""""""""""""""""""""""
+
+Deletes journal index from hoverfly.
 
 -------------------------------------------------------------------------------------------------------------
 

docs/pages/reference/hoverctl/hoverctl.output

@@ -11,6 +11,7 @@ Available Commands:
   diff              Manage the diffs for Hoverfly
   export            Export a simulation from Hoverfly
   flush             Flush the internal cache in Hoverfly
+  journal-index     Manage index for journal in Hoverfly
   import            Import a simulation into Hoverfly
   login             Login to Hoverfly
   logs              Get the logs from Hoverfly

docs/pages/reference/hoverfly/hoverfly.output

@@ -49,6 +49,9 @@ Usage of hoverfly:
         Import from file or from URL (i.e. '-import my_service.json' or '-import http://mypage.com/service_x.json'
   -journal-size int
         Set the size of request/response journal (default 1000)
+  -journal-indexing-key string
+        Specify the index key using which you want to index journal. Index shares same syntax as the one for templating, such as Request.QueryParam.myParam or Request.Header.X-Header-Id.[1].
+        It is used for extracting the data from the journal entry to use as a key for that entry.
   -key string
         Private key of the CA used to sign MITM certificates
   -listen-on-host string