Add Admin configuraiton details

src/pages/events/commands.md

@@ -381,7 +381,7 @@ If the depth value of `2` was specified, the response would also include details
 
 ## Generate a Commerce module based on a list of subscribed events
 
-The `events:generate:module` command generates a module with plugins based on your configuration and places it into the Commerce `app/code/Magento/AdobeCommerceEvents` directory.
+The `events:generate:module` command generates a module with plugins based on your configuration and places it into the Commerce `app/code/Magento/AdobeCommerceEvents` directory.  This command is applicable for on-premises deployments only.
 
 ### Usage
 

src/pages/webhooks/admin-configuration.md

@@ -21,11 +21,65 @@ The rows of this grid show configuration settings for all registered hooks, both
 
 ## Create a new hook
 
-Click **Add New Webhook** from the grid page to display the form for creating a new hook. If the plugin for the webhook method and type entered into the form has not been generated for the Commerce instance, a warning to run the `webhooks:generate:module` command will appear upon clicking **Save**.
+Click **Add New Webhook** from the grid page to display the form for creating a new hook.
 
 <InlineAlert variant="warning" slots="text" />
 
-On Cloud instances, due to the read-only file system, the `webhooks:generate:module` command cannot be run. If a plugin-type webhook is added through the Admin, the method name and type should be declared in a `webhooks.xml` file so that the required plugin is generated during the build phase of the deployment process.
+If the plugin for the webhook method and type entered into the form have not been generated for the Commerce instance, a warning to run the `webhooks:generate:module` command will appear upon clicking **Save**. You cannot run the `webhooks:generate:module` command on Cloud instances, due to its read-only file system. If you add a plugin-type webhook through the Admin, declare the method name and type in a `webhooks.xml` file.
+
+![New webhook](../_images/webhooks/new-hook-settings.png)
+
+The **Hook Settings** configuration panel contains the following fields:
+
+Field | Description
+--- | ---
+**Webhook Method** | The internal name of a webhook. The value must be in the form `<type>.<webhook_name>`, where `type` is either `observer` or `plugin`, and `webhook_name` matches a valid Commerce event name. Use the [`bin/magento webhooks:list:all`](commands.md#return-a-list-of-supported-webhook-event-names) command to display a list of possible webhooks.
+**Webhook Type** | Select whether to run the webhook `before` or `after` the original action.
+**Batch Name** | A unique name for the batch. Use a descriptive name that encompasses all the hooks in the batch. The name must contain English alphanumeric characters and underscores (_) only.
+**Hook Name** |  A name that must be unique within a batch. The name must contain English alphanumeric characters and underscores (_) only.
+**URL** | The HTTP endpoint to send the request for processing.
+**Timeout** | A hard timeout limit (milliseconds) for the request. Requests exceeding this timeout are aborted and logged. The default value of 0 indicates there is no timeout limit.
+**Soft timeout** | A soft timeout limit (milliseconds) for the request. Requests exceeding this timeout are logged for debugging purposes.
+**Cache TTL** | The cache time-to-live (in seconds) for requests with the same URL, body, and headers. If this attribute is not specified, or if the value set to `0`, the response is not cached.
+**Fallback error message** | The error message to display when the hook fails.
+**Required** | Specifies whether hook execution is required or optional. When set to `Optional`, if the hook fails to execute, the failure is logged and subsequent hooks continue to be processed. When set to `Required`, a failure terminates the process.
+**Active** | Indicates whether to skip a removed hook during the batch execution.
+**Method** | The HTTP method (POST, PUT, GET, or DELETE) used to invoke the hook.
+
+You must define at least one hook field, and you will usually need to define request headers. You can also optionally define rules that allow the webhook to run in limited situations. Continue defining these entities and click **Save** when you have fully defined a new webhook.
+
+### Configure hook fields
+
+The **Hook Fields** configuration panel defines the payload of a webhook request. [Define the hook body](hooks.md#define-the-hook-body) describes how to construct the payload.
+
+Field | Description
+--- | ---
+**Name** | The path to the field to include in the transmitted webhook, such as `product.sku`.
+**Source** | The path to the value in the default webhook. If not set, the **Name** value is used.
+**Converter** |  A class that transforms the value of a field, such as from integer to string.
+**Active** | Indicates whether to include the field in the payload.
+
+### Configure hook headers
+
+The **Configure Hook Headers** configuration panel defines the headers of a webhook request. [Define request headers](hooks.md#define-request-headers) describes how to send authorization tokens and other connection parameters.
+
+Field | Description
+--- | ---
+**Name** | The header name, in the same form as it will be sent. For example, `Authorization`.
+**Value** | The value of the header, such as `Bearer: <token>`.
+**Resolver** | The resolver class that appends headers dynamically.
+**Active** | Set to **No** to remove the header from the request.
+
+### Configure hook rules
+
+The **Configure Hook rules** configuration panel allows you to define rules that trigger a webhook when certain conditions are met. [Create conditional webhooks](./conditional-webhooks.md) describes how to configure hook rules.
+
+Field | Description
+--- | ---
+**Field** | The event field to be evaluated. For nested fields, use the dot-separated format, such as `data.order.product.id`.
+**Value** | The value to be compared.
+**Operator** | Defines which comparison operator to use. Examples include `equal`, `notEqual`, and `regex`.
+**Active** | Set to **No** to remove the rule from the request.
 
 ## Edit an existing hook
 

src/pages/webhooks/commands.md

@@ -261,7 +261,7 @@ ok | 10:25:24 AM
 
 ## Generate plugins
 
-The `webhooks:generate:module` command generates the `AdobeCommerceWebhookPlugins` module with plugins based on webhook registrations and places it into the Commerce `app/code/Magento` directory.
+The `webhooks:generate:module` command generates the `AdobeCommerceWebhookPlugins` module with plugins based on webhook registrations and places it into the Commerce `app/code/Magento` directory. This command is applicable for on-premises deployments only.
 
 ### Usage
 
@@ -289,9 +289,9 @@ The `webhooks:dev:run` command is used for development and testing purposes only
 
 ### Arguments
 
-<webhook-name:type> Required. The combination of webhook name and type. The name must begin with either `observer.` or `plugin.`. The `type` must be either `before` or `after`. Example: `observer.checkout_cart_product_add_before:before`
+`<webhook-name:type>` Required. The combination of webhook name and type. The name must begin with either `observer.` or `plugin.`. The `type` must be either `before` or `after`. Example: `observer.checkout_cart_product_add_before:before`
 
-&lt;webhook-arguments-payload> Required. The webhook arguments payload in JSON format. The payload will be filtered according to the `fields` rules defined in a `webhooks.xml` file before being sent to the webhook endpoint. This emulates how the real arguments will be filtered in the generated plugin for the webhook.
+`<webhook-arguments-payload>` Required. The webhook arguments payload in JSON format. The payload will be filtered according to the `fields` rules defined in a `webhooks.xml` file before being sent to the webhook endpoint. This emulates how the real arguments will be filtered in the generated plugin for the webhook.
 
 ### Example
 

src/pages/webhooks/conditional-webhooks.md

@@ -37,13 +37,13 @@ Conditional webhooks can have one or more rules. Each rule contains the followin
 
 The following example creates and registers a conditional webhook for the event `plugin.magento.tax.api.tax_calculation.calculate_tax`. The webhook will be only triggered when all of the conditions are true:
 
-*  The value of `.quoteDetails.shipping_address.country_id` must be equal to `US`.
+*  The value of `quoteDetails.shipping_address.country_id` must be equal to `US`.
 *  The `quoteDetails.billing_address.postcode` must begin with `123`.
 
 ```xml
 <method name="plugin.magento.tax.api.tax_calculation.calculate_tax" type="after">
    <hooks>
-      <batch>
+      <batch name="Order_Updates">
          <hook name="update_order" url="{env:APP_URL}/calculate-taxes" method="POST" timeout="5000" softTimeout="1000" priority="300" required="false" fallbackErrorMessage="The taxes can not be calculated">
             <fields>
                <field name="quoteDetails" />
@@ -64,7 +64,7 @@ The following example sends a webhook to a third-party service when the product
 ```xml
        <method name="observer.catalog_product_save_before" type="before">
        <hooks>
-           <batch>
+           <batch name ="Product_Updates">
                <hook name="generate_description" url="{env:APP_URL}/generate-product-description" timeout="5000" softTimeout="1000" priority="300" required="true" fallbackErrorMessage="The product could not be updated">
                    <fields>
                        <field name="product.name" source="data.product.name" />

src/pages/webhooks/release-notes.md

@@ -25,6 +25,10 @@ February 7, 2024
 
  The `AdobeCommerceWebhooksAdminUi` module provides this support.
 
+### Backward-incompatible changes
+
+To support managing webhooks from the Admin, we introduced the `method.hooks.batch.name` field. This field is required and helps track changes made in the Admin. You must update all existing `webhooks.xml` files to include batch names. All new webhooks, whether created from a file or from the Admin, must define a batch name.
+
 ## Version 1.1.0
 
 ### Release date

src/pages/webhooks/testing.md

@@ -14,7 +14,7 @@ In this example, the `webhooks.xml` file registered the following webhook:
 ```xml
     <method name="observer.checkout_cart_product_add_before" type="before">
         <hooks>
-            <batch>
+            <batch name="Update_Cart">
                 <hook name="validate_stock" url="{env:APP_BUILDER_PROJECT_URL}/product-validate-stock" timeout="2000" softTimeout="200" fallbackErrorMessage="The product stock validation failed">
                     <fields>
                         <field name='product.name' source='data.product.name' />

src/pages/webhooks/xml-schema.md

@@ -22,10 +22,12 @@ A maximal `webhooks.xml` file has the following structure:
                     |__ headers
                     |   |__ header
                     |__ fields
-                        |__ field
+                    |   |__ field
+                    |__ rules
+                        |__ rule
 ```
 
-[Configure hooks](hooks.md) provides examples of fully-defined hooks.
+[Configure hooks](hooks.md) and [Create conditional webhooks](./conditional-webhooks.md) contain examples of fully-defined hooks.
 
 ## `config` attributes
 
@@ -40,23 +42,24 @@ xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_AdobeCommerceWebhooks:
 
 ## `method` element
 
-The `method` element must define the webhook `name` and `type`. The combination of method name and type must be unique across the system.
+The `method` element must define the webhook `name` and `type`. The combination of method `name` and `type` must be unique across the system.
 
 | Attribute | Type  | Description | Is required | Default |
 |---|---|---|---|
-| `name`    | String | The webhook code name. The value must be in the form `<type>.<webhook_name>`, where `type` is either `observer` or `plugin`, and `webhook_name` matches a valid Commerce event name. Use the `bin/magento webhooks:list:all` command to display a list of possible webhooks. | true        | Not applicable     |
-| `type`    | String | Specifies whether the webhook should be executed `before` or `after` the original action.  | true        | Not applicable     |
+| `name` | String | The webhook code name. The value must be in the form `<type>.<webhook_name>`, where `type` is either `observer` or `plugin`, and `webhook_name` matches a valid Commerce event name. Use the `bin/magento webhooks:list:all` command to display a list of possible webhooks. | true | Not applicable |
+| `type` | String | Specifies whether the webhook should be executed `before` or `after` the original action. | true | Not applicable |
 
 ## `hooks` element
 
 The `hooks` element is required. It does not contain any attributes, but it must contain one or more `batch` elements.
 
 ## `batch` element
 
-The `batch` element sets the order in which multiple webhooks are executed. All hooks within a batch are sent in parallel.
+The `batch` element sets the order in which multiple webhooks are executed. All hooks within a batch are sent in parallel. Therefore, as you add hooks to a batch, keep in mind what task each hook will perform. For example, since the hooks are executed in parallel, you should not place a hook that relies on a response from another hook in the same batch.
 
 | Attribute | Type | Description                     | Is required | Default |
 |-----------|------|---------------------------------|-------------|---------|
+| `name` | String | A unique name for the batch. This value must contain English alphanumeric characters and underscores (_) only.| true | Not applicable |
 | `order`   | Int  | Sort order for batch execution. | false        | Not applicable     |
 
 ## `hook` element
@@ -70,7 +73,7 @@ The `hook` element defines the HTTP request to the remote server.
 | `method` | String | The HTTP method, such as POST or PUT, that invokes the hook. | false       | POST    |
 | `priority` | Int    | The priority of the merging hook results in the batch.  | false       | 0       |
 | `required` | Boolean   | Specifies whether hook execution is required or optional. When set to `false` (optional), if the hook fails to execute, the failure is logged and subsequent hooks continue to be processed. When `true`, a failure terminates the process. | false       | true    |
-| `timeout` | Int    | A hard timeout limit (milliseconds) for the request. Requests exceeding this timeout are aborted and logged. | false       | 0       |
+| `timeout` | Int    | A hard timeout limit (milliseconds) for the request. Requests exceeding this timeout are aborted and logged. The default value of 0 indicates there is no timeout limit. | false       | 0       |
 | `softTimeout`| Int    | A soft timeout limit (milliseconds) for the request. Requests exceeding this timeout are logged for debugging purposes. | false       | Not applicable     |
 | `fallbackErrorMessage` | Int    | The error message to return when the hook fails. | false       | Not applicable     |
 | `remove` | Boolean   | Indicates whether to skip a removed hook during the batch execution. | false       | false   |
@@ -95,6 +98,17 @@ A `fields` element is optional and can contain one or more `field` elements. The
 | Attribute | Type   | Description  | Is required | Default |
 |---|---|---|---|---|
 | `name` | String  | The path to the field to include in the transmitted webhook, such as `product.sku`.  | true        | Not applicable     |
-| `source` | String  | The path to the value in the default webhook. If not set, the `name` is used as source. | false       | Not applicable     |
+| `source` | String  | The path to the value in the default webhook. If not set, the value of `name` is used. | false       | Not applicable     |
 | `converter` | String  | A class that transforms the value of a field, such as from integer to string. | false       | Not applicable     |
 | `remove` | Boolean | Set to `true` to remove the field from the payload. | false | false   |
+
+## `rules` and `rule` elements
+
+A `rules` element is optional and can contain one or more `rule` elements. Each `rule` element defines a conditional webhook, which configures the conditions that cause the webhook to be triggered when all conditions evaluate to `true`. [Create conditional webhooks](./conditional-webhooks.md) provides example rules and fully describes the possible operator values.
+
+| Attribute | Type   | Description  | Is required | Default |
+|---|---|---|---|---|
+| `field` | String | The event field to be evaluated. For nested fields, use the dot-separated format, such as `data.order.product.id`. | true | Not applicable
+| `operator` | String | A string that defines which comparison operator to use. Examples include `equal`, `notEqual`, and `regex`. | true | Not applicable
+| `value` | String | The value to be compared. | true | Not applicable
+| `remove` | Boolean | Indicates whether the rule is active. The default value of `true` indicates the rule is active. | false | false