merge changes from main

.github/linters/metadata.schema.yml

@@ -24,6 +24,7 @@ properties:
         - Performance
         - REST
         - Security
+        - Starter Kit
         - Tools
         - Upgrade
         - Webhooks

src/_includes/project-requirements.md

@@ -1,7 +1,3 @@
 *  Have an Adobe Developer account with System Administrator or Developer Role permissions. [Getting started with Adobe Developer Console](https://developer.adobe.com/developer-console/docs/guides/getting-started/) describes how to enroll in the Adobe developer program.
 
-*  Be familiar with [Adobe I/O Runtime](https://developer.adobe.com/runtime/docs/guides/getting-started/).
-
-*  Install the [`aio CLI`](https://developer.adobe.com/runtime/docs/guides/getting-started/setup/).
-
 *  Have access to an Adobe Commerce on cloud infrastructure or to an on-premises instance.

src/data/navigation/sections/events.js

@@ -39,6 +39,22 @@ module.exports = [
     title: "API reference",
     path: "/events/api.md",
   },
+  {
+    title: "Consume events",
+    path: "/events/consume-events.md",
+    pages: [
+      {
+        title: "Sample Code for Consuming Events",
+        path: "/events/consume-events-examples/index.md",
+        pages: [
+          {
+            title: "Runtime Action with a Callback to Commerce",
+            path: "/events/consume-events-examples/runtime-action-commerce-callback.md"
+          }
+        ]
+      }
+    ]
+  },
   {
     title: "Troubleshooting",
     path: "/events/troubleshooting.md",

src/pages/app-development/index.md

@@ -40,7 +40,9 @@ Adobe Commerce continues to support the [PWA Studio](https://developer.adobe.com
 
 ### Plugins and observers
 
-[Adobe I/O Events for Adobe Commerce](../events/index.md) enables building event-driven Commerce integrations using App Builder. You can define key events, like customer account updates, to be emitted from Commerce and construct apps that listen and react to these events.
+[Adobe I/O Events for Adobe Commerce](../events/index.md) enables building near real-time, event-driven Commerce integrations using App Builder. You can define key events, like customer account updates, to emit from Commerce and construct apps that listen and react to these events.
+
+[Adobe Commerce Webhooks](../webhooks/index.md) enables configuring synchronous logic to execute calls from Commerce to external systems when key events occur. You can use this real-time communication with external systems to validate or modify data in Commerce.
 
 ### Admin development
 

src/pages/events/commands.md

@@ -132,7 +132,13 @@ bin/magento events:registrations:list -vv
 
 ## Create event metadata in Adobe I/O
 
-The `events:metadata:populate` command creates event metadata based on XML and application configurations.
+The `events:metadata:populate` command creates event metadata based on XML and application configurations. This metadata gets linked to the configured event provider.
+
+Event metadata is automatically created for new event subscriptions when you run the [`events:subscribe` command](#subscribe-to-an-event) and synchronize events registered in `io_events.xml` files or `config.php` when the `setup:upgrade` command runs. In the following situations, we recommend creating event metadata using the `events:metadata:populate` command:
+
+* You have configured an event provider after an `io_events.xml` file was pushed to your cloud instance and a redeployment has not occurred since this change.
+* You have not run `setup:upgrade` since adding an `io_events.xml` file to your on-premise instance.
+* You manually edited the event subscriptions configuration in `app/etc/config.php`.
 
 ### Usage
 

src/pages/events/configure-commerce.md

@@ -32,7 +32,7 @@ You must configure Commerce to communicate with your project. Configuration incl
 
 1. Enter a unique identifier in the **Adobe Commerce Instance ID** field. This unique value identifies your Commerce instance, which allows Commerce events to connect to the correct `Event Provider` in Adobe I/O. This ID corresponds to the **Provider** displayed when [subscribing to events](#subscribe-and-register-events).
 
-   **NOTE**: The **Adobe Commerce Instance ID** field only supports alphanumeric characters, hyphens and underscores.
+   **Note**: The **Adobe Commerce Instance ID** field only supports alphanumeric characters, hyphens and underscores.
 
 1. Click **Save Config**, but do not leave the page. The next section creates an event provider, which is necessary to complete the configuration.
 
@@ -89,7 +89,7 @@ You cannot create an event provider until you have configured and saved instance
 
 1. Enter the merchant's company name in the **Merchant ID** and the environment name in **Environment ID** fields. The values of these fields will be combined and added as a `source` attribute to your event data to identify the source of the events. It can be useful for event filtration or other logic if you are using the same event provider for several environments or projects.
 
-   **NOTE**: The **Merchant ID** and **Environment ID** fields only support alphanumeric characters and underscores.
+   **Note**: The **Merchant ID** and **Environment ID** fields only support alphanumeric characters and underscores.
 
 ```javascript
 "source": "<merchant-id>.<environment-id>"
@@ -142,7 +142,9 @@ Commerce provides two sources for events: observers and plugins. You must specif
 
 1. Optionally create a new OAuth or JWT credential. Then click **Next**.
 
-1. Update the **Event registration name** and **Event registration description** fields.
+1. Update the **Event registration name** and **Event registration description** fields. The Journaling API can consume your events by default. You can optionally select other consumption methods during this step. Learn more about your options in [Consuming Events](./consume-events.md).
+
+   ![Select how to receive events](../_images/events/receive-events-options.png)
 
 1. Select **Save configured events**.
 

src/pages/events/consume-events-examples/index.md

@@ -0,0 +1,11 @@
+---
+title: Sample Code for Consuming Events
+description: View sample code demonstrating how to consume Commerce Events sent to Adobe I/O.
+keywords:
+  - Events
+  - Extensibility
+---
+
+# Sample Code for Consuming Events Overview
+
+The sample code in this section demonstrates how to consume Commerce Events sent to Adobe I/O.

src/pages/events/consume-events-examples/runtime-action-commerce-callback.md

@@ -0,0 +1,90 @@
+---
+title: Runtime Action with a Callback to Commerce
+description: Provides details about how a runtime action can consume events and fetch additional details from Commerce.
+keywords:
+  - Events
+  - Extensibility
+---
+
+# Runtime Action with a Callback to Commerce
+
+This example provides sample code for a runtime action that can consume an Adobe Commerce event and make an API call back to Commerce to obtain more information before sending data to a third-party system.
+
+## Runtime action example code
+
+You could use the following JavaScript code sample to create a runtime action for consuming `observer.sales_order_save_after` events.
+
+```js
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse } = require('../utils')
+const { getCommerceOauthClient } = require('../oauth1a')
+const { sendOrderToErpSystem } = require('../erp')
+
+async function main (params) {
+  const logger = Core.Logger('main', { level: params.LOG_LEVEL || 'info' })
+
+  try {
+    event_payload = params.data.value
+    if (!event_payload.hasOwnProperty('extension_attributes')) {
+      // Fetch extension attributes for order and add to order event payload
+      const oauth = getCommerceOauthClient(
+        {
+          url: params.COMMERCE_BASE_URL,
+          consumerKey: params.COMMERCE_CONSUMER_KEY,
+          consumerSecret: params.COMMERCE_CONSUMER_SECRET,
+          accessToken: params.COMMERCE_ACCESS_TOKEN,
+          accessTokenSecret: params.COMMERCE_ACCESS_TOKEN_SECRET
+        },
+        logger
+      )
+      const content = await oauth.get('orders/' + event_payload.entity_id)
+      event_payload.extension_attributes = content.extension_attributes
+    }
+
+    // Send event data to a third-party ERP system
+    await sendOrderToErpSystem(event_payload)
+
+    return {
+      statusCode: 200,
+      body: event_payload
+    }
+  } catch (error) {
+    // log any server errors
+    logger.error(error)
+    // return with 500
+    return errorResponse(500, 'server error', logger)
+  }
+}
+
+exports.main = main
+```
+
+The `main` action first accesses the payload for a received `observer.sales_order_save_after` event:
+
+```js
+event_payload = params.data.value
+```
+
+The event payload for this event could not contain the saved order's extension attributes. If needed, you can fetch the extension attributes for the specific order captured by the event using a Commerce API call:
+
+```js
+  const oauth = getCommerceOauthClient(
+    {
+      url: params.COMMERCE_BASE_URL,
+      consumerKey: params.COMMERCE_CONSUMER_KEY,
+      consumerSecret: params.COMMERCE_CONSUMER_SECRET,
+      accessToken: params.COMMERCE_ACCESS_TOKEN,
+      accessTokenSecret: params.COMMERCE_ACCESS_TOKEN_SECRET
+    },
+    logger
+  )
+  const content = await oauth.get('orders/' + event_payload.entity_id)
+```
+
+This example uses functions from the `oauth1a` module, as defined in the [adobe-commerce-samples repo](https://github.com/adobe/adobe-commerce-samples/blob/main/admin-ui-sdk/menu/custom-menu/actions/oauth1a.js).
+
+You can retrieve the `consumerKey`, `consumerSecret`, `accessToken`, and `accessTokenSecret` provided in the input to the `getCommerceOauthClient` function from Commerce after creating and activating an [Integration](https://experienceleague.adobe.com/en/docs/commerce-admin/systems/integrations) in the Commerce admin. You can configure these values in an App Builder [.env file](https://developer.adobe.com/app-builder/docs/guides/configuration/#env) and then [pass them as inputs to the App Builder action](https://developer.adobe.com/app-builder/docs/guides/configuration/#using-environment-variables-in-runtime-actions) through the action's configuration.
+
+You can now add the order's extension attributes retrieved from Commerce to the order event payload, and send the payload to a third-party Enterprise Resource Planning (ERP) system using a custom module.
+
+After creating a runtime action using this code, you can create an event registration can to subscribe to the `observer.sales_order_save_after` event, and configure the new runtime action to receive the event notifications.

src/pages/events/consume-events.md

@@ -0,0 +1,46 @@
+---
+title: Consume Events
+description: Learn how to consume events sent from Adobe Commerce to Adobe I/O Events.
+keywords:
+  - Events
+  - Extensibility
+---
+
+You can consume events sent from Adobe Commerce to Adobe I/O events in several ways. The following options for consuming events are available when adding events to your App Builder project and creating an event registration:
+
+* [Using the Journaling API](#using-the-journaling-api) (enabled by default)
+* [Using a Webhook URL](#using-a-webhook-url)
+* [Using a Runtime Action](#using-a-runtime-action)
+* [Using Amazon EventBridge](#using-amazon-eventbridge)
+
+## Using the Journaling API
+
+When you create an Adobe I/O event registration, the subscribed events added to an ordered list, referred to as the journal, by default. You can consume these events using a journaling endpoint URL that is unique to the registration. For more information on reading events from the journal, see the [Introduction to Journaling](https://developer.adobe.com/events/docs/guides/journaling_intro/).
+
+You can also consume events from the Journaling API using the [Adobe I/O Events SDK](https://github.com/adobe/aio-lib-events). See [Subscribe to Events Using Journaling](https://developer.adobe.com/events/docs/guides/sdk/sdk_journaling/) for details and sample code.
+
+## Using a Webhook URL
+
+Consuming an event using a webhook URL is useful for cases that do not require App Builder to handle transformations to the event structure or additional API calls, which simplifies forwarding events from Adobe Commerce to a 3rd-party system using App Builder. The destination system must have an endpoint that can receive webhook requests to use this option.
+
+You can register the webhook URL when creating or editing an event registration. If you are setting up the registration through the developer console UI, this option will appear in the final configuration step.
+
+![Webhook registration](../_images/events/register-webhook.png)
+
+See [Introduction to Adobe I/O Events Webhooks](https://developer.adobe.com/events/docs/guides/) for more details.
+
+<InlineAlert variant="warning" slots="text"/>
+
+Be careful not to confuse this method of consuming events with [Runtime Actions as a Webhook](https://developer.adobe.com/events/docs/guides/runtime_webhooks/#benefits-of-using-runtime-action-as-webhook). Runtime Actions as a Webhook is a functionality for creating a URL for App Builder to receive events from a 3rd party system.
+
+## Using a Runtime Action
+
+An [Adobe I/O Runtime Action](https://developer.adobe.com/runtime/docs/guides/overview/entities/#actions) allows you to receive Commerce events in an event registration. You can create actions from JavaScript functions, as described in [Creating Actions](https://developer.adobe.com/runtime/docs/guides/using/creating_actions/). Within an action, you can execute business logic based on the received event payload, make API calls back to Adobe Commerce to update data, access additional information, and send data to another system.
+
+See [Runtime Action with a Callback to Commerce](./consume-events-examples/runtime-action-commerce-callback.md) for an example of how a runtime action can consume an event and make an API call back to Commerce to get more information.
+
+See more examples of end-to-end integrations between Commerce and 3rd party systems like ERPs that use runtime actions in our [Starter Kit](https://developer.adobe.com/commerce/extensibility/starter-kit/send-data/) documentation.
+
+## Using Amazon EventBridge
+
+You can configure an Adobe I/O event registration to forward received Commerce events to Amazon EventBridge. See [Adobe I/O Events and Amazon EventBridge Integration](https://developer.adobe.com/events/docs/guides/amazon_eventbridge/) for more details.

src/pages/starter-kit/best-practices.md

@@ -7,9 +7,10 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 
 # Best practices
 
-This page is under development and will be included with the initial release.
+This page is under development.

src/pages/starter-kit/contact-us.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 

src/pages/starter-kit/create-data-flow.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 

src/pages/starter-kit/create-integration.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 
@@ -246,23 +247,31 @@ You must configure Commerce to communicate with your project. Configuration incl
 
 1. In the Commerce Admin, navigate to **Stores** > Settings > **Configuration** > **Adobe Services** > **Adobe I/O Events** > **General configuration**. The following screen displays.
 
-   ![General configuration](../_images/events/general-configuration.png)
+   ![General configuration](../_images/events/general-configuration-updated.png)
 
 1. Select the server-to-server authorization method you implemented from the **Adobe I/O Authorization Type** menu. Adobe recommends using OAuth. JWT has been deprecated.
 
 1. Copy the contents of the `<workspace-name>.json` file into the **Adobe I/O Workspace Configuration** field.
 
-1. Enter a unique identifier in the **Adobe Commerce Instance ID** field. This value must contain English alphanumeric characters, underscores (_), and hyphens (-) only.
+1. Enter a unique identifier in the **Adobe Commerce Instance ID** field. This unique value identifies your Commerce instance, which allows Commerce events to connect to the correct `Event Provider` in Adobe I/O. This ID corresponds to the **Provider** displayed when [subscribing to events](../events/configure-commerce.md#subscribe-and-register-events).
+
+   **Note**: This value must contain English alphanumeric characters, underscores (_), and hyphens (-) only.
 
 1. Click **Save Config**, but do not leave the page. The next section creates an event provider, which is necessary to complete the configuration.
 
 1. Enable Commerce Eventing by setting **Enabled** to `Yes`.
 
-   **Note**: You must enable cron so that Commerce can send events to the endpoint.
+   ![Commerce events configuration](../_images/events/commerce-events.png)
+
+   **Note**: You must enable cron to allow Commerce to send events to the endpoint.
 
-1. Enter the merchant's company name in the **Merchant ID** field. You must use alphanumeric and underscores only.
+1. Enter the merchant's company name in the **Merchant ID** and the environment name in the **Environment ID** field. The values of these fields will be combined and added as a `source` attribute to your event data to identify the source of the events. It can be useful for event filtration or other logic if you are using the same event provider for several environments or projects.
 
-1. In the **Environment ID** field, enter a temporary name for your workspaces while in development mode. When you are ready for production, change this value to a permanent value, such as Production.
+   **Note**: The **Merchant ID** and **Environment ID** fields only support alphanumeric characters and underscores.
+
+   ```javascript
+   "source": "<merchant-id>.<environment-id>"
+   ```
 
 1. (Optional) By default, if an error occurs when Adobe Commerce attempts to send an event to Adobe I/O, Commerce retries a maximum of seven times. To change this value, uncheck the **Use system value** checkbox and set a new value in the **Maximum retries to send events** field.
 

src/pages/starter-kit/customers.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 

src/pages/starter-kit/data-flows.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 

src/pages/starter-kit/developer-tools.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 

src/pages/starter-kit/events.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---
 

src/pages/starter-kit/launch.md

@@ -7,6 +7,7 @@ keywords:
  - API Mesh
  - Events
  - REST
+ - Starter Kit
  - Tools
 ---