[Rules] Updated UI for URL rewrites (#17718)

pedrosousa · Maddy-Cloudflare · web-flow · commit bf0f6a98c5df · 2024-10-23T10:45:17.000Z
---------

Co-authored-by: Maddy &lt;130055405+Maddy-Cloudflare@users.noreply.github.com&gt;
diff --git a/src/assets/images/rules/transform/create-url-rewrite-rule.png b/src/assets/images/rules/transform/create-url-rewrite-rule.png
diff --git a/src/content/changelogs/rules.yaml b/src/content/changelogs/rules.yaml
@@ -5,11 +5,17 @@ productLink: "/rules/"
 productArea: Application performance
 productAreaLink: /fundamentals/reference/changelog/performance/
 entries:
-  - publish_date: "2024-09-20" 
+  - publish_date: "2024-10-23"
+    title: Simplified user interface for URL Rewrites with wildcard support
+    description: |-
+      The new simplified user interface for [URL Rewrites](/rules/transform/url-rewrite/) is now live, making it easier for users to configure URL rewrites with wildcard support. This update streamlines the process by eliminating the need for complex functions in rule creation.
+      The updated user interface is available at **Rules** > **Transform Rules** > **Rewrite URL**. For more information, refer to the [wildcard support documentation](/rules/transform/url-rewrite/reference/parameters/#wildcard-matching-and-replacement).
+
+  - publish_date: "2024-09-20"
     title: Automatic DNS Validation for Cloudflare Rules
-    description: |- 
+    description: |-
       The Cloudflare dashboard now automatically validates [DNS records](/dns/manage-dns-records/reference/proxied-dns-records/) and [Cloudflare for SaaS custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/) for rules targeting specific hostnames or URLs. To prevent misconfigured rules and ensure smoother deployments, you will get proactive warnings for missing or misconfigured DNS records and custom hostnames.
-      
+
   - publish_date: "2024-09-17"
     title: Compression Rules available to all plans with Zstandard support
     description: |-
diff --git a/src/content/docs/rules/transform/url-rewrite/create-dashboard.mdx b/src/content/docs/rules/transform/url-rewrite/create-dashboard.mdx
@@ -6,7 +6,6 @@ sidebar:
 head:
   - tag: title
     content: Create a rewrite URL rule in the dashboard
-
 ---
 
 Refer to the [Rules examples gallery](/rules/transform/examples/?operation=Rewrite+URL) for examples of rule definitions.
@@ -19,29 +18,56 @@ To create a rule:
 
 3. To create a new empty rule, select **Create rule**. To duplicate an existing rule, select the three dots next to it > **Duplicate**.
 
+4. In the rule creation page, enter a descriptive name for the rule in **Rule name**.
+
    ![The rewrite URL rule creation page in the Cloudflare dashboard.](~/assets/images/rules/transform/create-url-rewrite-rule.png)
 
-4. In the rule creation page, enter a descriptive name for the rule in **Rule name**.
+5. Under **If incoming requests match**, select one of the following options:
 
-5. Under **When incoming requests match**, select if you wish to apply the rule to all incoming requests or only to requests that match a custom filter expression.
+   - **Wildcard pattern**: The rule will only apply to traffic matching the wildcard pattern in **Request URL**. Refer to [Wildcard pattern parameters](#wildcard-pattern-parameters) for details.
 
-6. (Optional) To define a custom expression, use the Expression Builder (specifying one or more values for **Field**, **Operator**, and **Value**) or manually enter an expression using the Expression Editor. For more information, refer to [Edit expressions in the dashboard](/ruleset-engine/rules-language/expressions/edit-expressions/).
+   - **Custom filter expression**: The rule will only apply to traffic matching a custom expression. Define the [rule expression](/ruleset-engine/rules-language/expressions/edit-expressions/) to configure which requests should be rewritten. Use either the Expression Builder or the Expression Editor to define the custom expression. For more information, refer to [Edit expressions in the dashboard](/ruleset-engine/rules-language/expressions/edit-expressions/).
 
-   :::note
+     :::note
+     Check the [fields and functions](/rules/transform/url-rewrite/reference/fields-functions/) you can use in filter expressions of rewrite URL rules.
+     :::
 
-   Check the [available fields and functions](/rules/transform/url-rewrite/reference/fields-functions/). 
-   :::
+   - **All incoming requests**: The rule will apply to all traffic.
 
-7. Define the action for your rewrite URL rule by selecting one of the available options displayed as radio buttons, and then a value from the drop-down list, depending on the action:
+6. (Optional) Define the action for your rewrite URL rule by selecting one of the available options displayed as radio buttons, and then a value from the drop-down list, depending on the action:
 
-   * If you select **Rewrite to** > *Static*, enter the string that will replace the original URL path (or query string). For example, enter `welcome-gb.html` to rewrite the original URL path to `/welcome-gb.html`.
+   - If you select **Rewrite to** > _Static_, enter the string that will replace the original URL path (or query string). For example, enter `welcome-gb.html` to rewrite the original URL path to `/welcome-gb.html`.
 
-   * If you select **Rewrite to** > *Dynamic*, enter a [rewrite expression](/rules/transform/url-rewrite/reference/fields-functions/#rewrite-expressions) that defines the dynamic URL rewrite to perform.
+   - If you select **Rewrite to** > _Dynamic_, enter a [rewrite expression](/rules/transform/url-rewrite/reference/fields-functions/#rewrite-expressions) that defines the dynamic URL rewrite to perform.
 
-   * If you do not want to change the value of a component of the original request (the URL path or the URL query string), choose the *Preserve* action for that component.
+   - If you do not want to change the value of a component of the original request (the URL path or the URL query string), choose the _Preserve_ action for that component.
 
    For more information, refer to [URL rewrite parameters](/rules/transform/url-rewrite/reference/parameters/).
 
+7. Under **Place at**, define where to place the rule in the rules list: first rule in the list, last rule in the list, or in a custom position (after a given rule).
+
 8. To save and deploy your rule, select **Deploy**. If you are not ready to deploy your rule, select **Save as Draft**.
 
 If you choose to deploy your rewrite URL rule, the new rule will be enabled. If you save the rule as a draft, the new rule will be disabled.
+
+## Wildcard pattern parameters
+
+The Cloudflare dashboard offers a simplified user interface for creating URL rewrites based on wildcard matching and replacement. When you select **Wildcard pattern**, you will have the following parameters available:
+
+- **Request URL**: Enter the [wildcard pattern](/ruleset-engine/rules-language/operators/#wildcard-matching) using the asterisk (`*`) character to match multiple requests. For example, `https://*.example.com/*`.
+
+- **Then rewrite the path and/or query**: Define the [URL rewrite settings](/rules/transform/url-rewrite/reference/parameters/) including:
+  - **Path** > **Target path**: Enter the URI path to match, which can include wildcards (for example, `/oldpath/*`).
+  - **Path** > **Rewrite to**: Enter the new URI path. You can use [wildcard replacement](/ruleset-engine/rules-language/functions/#wildcard_replace) such as `${1}` and `${2}` to define a dynamic target path (for example, `/newpath/${1}`). Leave this field empty to remove the URI path.
+  - **Query** > **Target query**: Enter the query string to match, which can include wildcards (for example, `?sort=*`).
+  - **Query** > **Rewrite to**: Enter the new query string. You can use [wildcard replacement](/ruleset-engine/rules-language/functions/#wildcard_replace) such as `${1}` and `${2}` to define a dynamic query string (for example, `?order=${1}`). Leave this field empty to remove the query string.
+
+Refer to [URL rewrite parameters](/rules/transform/url-rewrite/reference/parameters/#wildcard-matching-and-replacement) for the equivalent rule configuration when using the API.
+
+:::note[Notes]
+
+The **Request URL** value is only used to match the incoming request with a rule. It will not be used for capturing URL patterns for rewrites. If you are matching the URL path or query string in **Target path** or **Target query**, respectively, make sure that the **Request URL** pattern also matches the incoming request, or else the rule will not trigger.
+
+To validate rewrite URL rule matches, use [Cloudflare Trace](/fundamentals/basic-tasks/trace-request/). To validate rewritten URLs, check your origin server.
+
+:::
diff --git a/src/content/docs/rules/transform/url-rewrite/reference/parameters.mdx b/src/content/docs/rules/transform/url-rewrite/reference/parameters.mdx
@@ -3,13 +3,14 @@ title: URL rewrite parameters
 pcx_content_type: reference
 sidebar:
   order: 2
-
 ---
 
 Static and dynamic URL rewrites have different parameters:
 
-* A static URL rewrite requires a static value for the target URL.
-* A dynamic URL rewrite requires an expression that, when evaluated, will define the target URL.
+- A static URL rewrite requires a static value for the target URL.
+- A dynamic URL rewrite requires an expression that, when evaluated, will define the target URL.
+
+A URL rewrite with wildcard patterns is a simplified interface in the Cloudflare dashboard for creating dynamic URL rewrites with [wildcard matching and replacement](#wildcard-matching-and-replacement).
 
 The maximum length of all parameter values in a URL rewrite (combined) is 4,096 characters. For example, you could provide a static value (or an expression) for the URI path with 2,048 characters and a static value (or expression) for the query string with 2,048 characters.
 
@@ -53,6 +54,34 @@ The full syntax of the `action_parameters` field for a dynamic rewrite URL rule
 
 If you are only rewriting the URI path or the query string, omit the `query` or `path` parameter, respectively.
 
+#### Wildcard matching and replacement
+
+The syntax of a dynamic rewrite URL rule that rewrites both the URI path and the query string based on wildcard matching and replacement is the following:
+
+```json
+{
+	"expression": "(http.request.full_uri wildcard r\"<REQUEST_URL>\")",
+	"action_parameters": {
+		"uri": {
+			"path": {
+				"expression": "wildcard_replace(http.request.uri.path, r\"<PATH_TARGET_PATH>\", r\"<PATH_REWRITE_TO>\")"
+			},
+			"query": {
+				"expression": "wildcard_replace(http.request.uri.query, r\"<QUERY_TARGET_QUERY>\", r\"<QUERY_REWRITE_TO>\")"
+			}
+		}
+	},
+	"action": "rewrite"
+	// ...
+}
+```
+
+The `<REQUEST_URL>`, `<PATH_TARGET_PATH>`, `<PATH_REWRITE_TO>`, `<QUERY_TARGET_QUERY>`, and `<QUERY_REWRITE_TO>` value placeholders correspond to the fields available in the Cloudflare dashboard when you select the **Wildcard pattern** option. For more information, refer to [Wildcard pattern parameters](/rules/transform/url-rewrite/create-dashboard/#wildcard-pattern-parameters).
+
+:::note
+The `http.request.uri.query` field does not include the `?` delimiter at the beginning, which means that your `<QUERY_TARGET_QUERY>` value should not try to match an initial `?`.
+:::
+
 ### Different URL rewrite types in the same rule
 
 The same rule can have different types of URL rewrites for the URI path and the query string. For example, a single rule can perform a **dynamic** URL rewrite of the URI path and a **static** URL rewrite of the query string. The syntax of such a rule would be the following:
