ORCA-4812: Document The dynamic_route_to action

website/docs/r/event_orchestration_router.html.markdown

@@ -12,15 +12,31 @@ An Orchestration Router allows users to create a set of Event Rules. The Router
 
 ## Example of configuring Router rules for an Orchestration
 
-In this example the user has defined the Router with two rules, each routing to a different service.
-
-This example assumes services used in the `route_to` configuration already exists. So it does not show creation of service resource.
+In this example the user has defined the Router with three rules. The first rule configures a dynamic route: any event containing a value in its `pd_service_id` custom detail will be routed to the Service with the ID specified by that value. The other rules route events matching a condition to specific services.
 
 ```hcl
+data "pagerduty_service" "database" {
+  name = "Primary Data Store"
+}
+
+data "pagerduty_service" "www" {
+  name = "Web Server App"
+}
+
 resource "pagerduty_event_orchestration_router" "router" {
   event_orchestration = pagerduty_event_orchestration.my_monitor.id
   set {
     id = "start"
+    rule {
+      label = "Dynamically route events related to specific PagerDuty services"
+      actions {
+        dynamic_route_to = {
+          lookup_by = "service_id"
+          source = "event.custom_details.pd_service_id"
+          regexp = "(.*)"
+        }
+      }
+    }
     rule {
       label = "Events relating to our relational database"
       condition {
@@ -30,15 +46,15 @@ resource "pagerduty_event_orchestration_router" "router" {
         expression = "event.source matches regex 'db[0-9]+-server'"
       }
       actions {
-        route_to = pagerduty_service.database.id
+        route_to = data.pagerduty_service.database.id
       }
     }
     rule {
       condition {
         expression = "event.summary matches part 'www'"
       }
       actions {
-        route_to = pagerduty_service.www.id
+        route_to = data.pagerduty_service.www.id
       }
     }
   }
@@ -72,6 +88,22 @@ The following arguments are supported:
 * `expression`- (Required) A [PCL condition](https://developer.pagerduty.com/docs/ZG9jOjM1NTE0MDc0-pcl-overview) string.
 
 ### Actions (`actions`) supports the following:
+
+#### Dynamic Routing
+
+Use the contents of an event payload to dynamically route an event to the target service. Note these setting can only be used once in the Router, and only in the first rule. The dynamic routing rule cannot have `conditions` nor a `route_to` action defined.
+
+* `dynamic_route_to` - (Required) supports the following:
+    * `source` - (Required) The path to a field in an event.
+    * `regex` - (Required) The regular expression, used to extract a value from the source field. Must use valid [RE2 regular expression](https://github.com/google/re2/wiki/Syntax) syntax.
+    * `lookup_by` - (Required) Indicates whether the extracted value from the source is a service's name or ID. Allowed values are: `service_name`, `service_id`
+
+If an event has a value at the specified `source`, and if the `regex` successfully matches the value, and if the matching portion is valid Service ID or Name, then the event will be routed to that service. Otherwise the event will be checked against any subsequent router rules.
+
+#### Service Route
+
+If an event matches this rule's conditions, then route it to the specified Service.
+
 * `route_to` - (Required) The ID of the target Service for the resulting alert.
 
 ### Catch All (`catch_all`) supports the following: