Add the documentation for ChangeDownstreamPathTemplate (#991)

docs/features/claimstransformation.rst

@@ -2,22 +2,25 @@ Claims Transformation
 =====================
 
 Ocelot allows the user to access claims and transform them into headers, query string 
-parameters and other claims. This is only available once a user has been authenticated.
+parameters, other claims and change downstream paths. This is only available once a user 
+has been authenticated.
 
 After the user is authenticated we run the claims to claims transformation middleware.
 This allows the user to transform claims before the authorisation middleware is called.
-After the user is authorised first we call the claims to headers middleware and Finally
-the claims to query string parameters middleware.
+After the user is authorised first we call the claims to headers middleware, then
+the claims to query string parameters middleware, and Finally the claims to downstream path
+middleware.
 
 The syntax for performing the transforms is the same for each process. In the ReRoute
 configuration a json dictionary is added with a specific name either AddClaimsToRequest,
-AddHeadersToRequest, AddQueriesToRequest. 
+AddHeadersToRequest, AddQueriesToRequest, or ChangeDownstreamPathTemplate.
 
 Note: I'm not a hotshot programmer so have no idea if this syntax is good...
 
 Within this dictionary the entries specify how Ocelot should transform things! 
 The key to the dictionary is going to become the key of either a claim, header 
-or query parameter.
+or query parameter. In the case of ChangeDownstreamPathTemplate, the key must be 
+also specified in the DownstreamPathTemplate, in order to do the transformation.
 
 The value of the entry is parsed to logic that will perform the transform. First of
 all a dictionary accessor is specified e.g. Claims[CustomerId]. This means we want
@@ -70,3 +73,24 @@ Below is an example configuration that will transforms claims to query string pa
 
 This shows a transform where Ocelot looks at the users LocationId claim and add it as
 a query string parameter to be forwarded onto the downstream service.
+
+Claims to Downstream Path Transformation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Below is an example configuration that will transform claims to downstream path custom placeholders
+
+.. code-block:: json
+
+    "UpstreamPathTemplate": "/api/users/me/{everything}",
+    "DownstreamPathTemplate": "/api/users/{userId}/{everything}",
+    "ChangeDownstreamPathTemplate": {
+        "userId": "Claims[sub] > value[1] > |",
+    }
+
+This shows a transform where Ocelot looks at the users userId claim and substitutes the value
+to the "{userId}" placeholder specified in the DownstreamPathTemplate. Take into account that the
+key specified in the ChangeDownstreamPathTemplate must be the same than the placeholder specified in
+the DownstreamPathTemplate.
+
+Note: if a key specified in the ChangeDownstreamPathTemplate does not exist as a placeholder in DownstreamPathTemplate
+it will fail at runtime returning an error in the response.