From 606b9c46c81e34fe13871c45830e91ef0fac4eb6 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Wed, 17 Apr 2024 16:26:22 -0500 Subject: [PATCH] links --- .../app-development/starter-kit/consumer.md | 68 ------------------- .../app-development/starter-kit/events.md | 47 ++++++++++++- .../starter-kit/receive-data.md | 6 +- .../app-development/starter-kit/send-data.md | 8 +-- .../app-development/starter-kit/structure.md | 2 +- .../app-development/starter-kit/webhooks.md | 2 +- 6 files changed, 54 insertions(+), 79 deletions(-) delete mode 100644 src/pages/app-development/starter-kit/consumer.md diff --git a/src/pages/app-development/starter-kit/consumer.md b/src/pages/app-development/starter-kit/consumer.md deleted file mode 100644 index cbb9d396..00000000 --- a/src/pages/app-development/starter-kit/consumer.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: consumer action -description: Learn how the consumer actions work in Starter Kit. -keywords: - - Extensibility - - App Builder - - API Mesh - - Events - - REST - - Tools ---- - -import BetaNote from '/src/_includes/starter-kit-beta.md' - - - -# `consumer` action - -The `consumer` and `event handler` actions implement the business logic needed to synchronize data between Commerce and the external systems being integrated. - -Additionally, boilerplate code, responses, and samples for event ingestion and synchronous webhook actions are provided. - - - -The synchronous webhook responses for each action are configured for the [Commerce webhook module](https://developer.adobe.com/commerce/extensibility/webhooks/). To customize the responses for other implementations, modify the `responses.js` file. - -## `consumer` action - -The main purpose of this action is to route events to the [`event handler` action](#event-handler-action). Normally, this routing is determined by the name of the event received. - -The `consumer` action is subscribed to a set of events. In many cases, all the events originate from the same entity, such as the `product` entity. However, there are examples where a consumer receives events from multiple entities belonging to the same "domain", such as `order` and `shipment`. When the event provider receives an event, this runtime action will be automatically activated. - -The response returned by a `consumer` action is expected to be consistent with the response received from the activation of the subsequent `event handler` action. For example, if the `event handler` action returns an `HTTP/400` status, the consumer action is expected to respond with the same status. This ensures that the event processing is appropriately retried based on the event handler action response. - -When it receives an event that it does not know how to route, it is expected to return HTTP/400 status. This will prevent the event handling from being retried. - -By default, `consumer` actions have the following response: - - - -### Success - -```js -// ./actions/responses.js#successResponse -return { - statusCode: 200, - body: { - type: 'EVENT TYPE', - response: { - // Response returned by the event handler action - } - } -} -``` - -### Failure - -```js -// ./actions/responses.js#errorResponse -return { - error: { - statusCode: 400, // 404, 500, etc, - body : { - error: 'YOUR ERROR MESSAGE' - } - } -} -``` diff --git a/src/pages/app-development/starter-kit/events.md b/src/pages/app-development/starter-kit/events.md index 8bbf0707..ce1c97c9 100644 --- a/src/pages/app-development/starter-kit/events.md +++ b/src/pages/app-development/starter-kit/events.md @@ -115,6 +115,49 @@ webhook: final: true ``` +## `consumer` action + +The main purpose of this action is to route events to the [`event handler` action](#event-handler-action). Normally, this routing is determined by the name of the event received. + +The `consumer` action is subscribed to a set of events. In many cases, all the events originate from the same entity, such as the `product` entity. However, there are examples where a consumer receives events from multiple entities belonging to the same "domain", such as `order` and `shipment`. When the event provider receives an event, this runtime action will be automatically activated. + +The response returned by a `consumer` action is expected to be consistent with the response received from the activation of the subsequent `event handler` action. For example, if the `event handler` action returns an `HTTP/400` status, the consumer action is expected to respond with the same status. This ensures that the event processing is appropriately retried based on the event handler action response. + +When it receives an event that it does not know how to route, it is expected to return HTTP/400 status. This will prevent the event handling from being retried. + +By default, `consumer` actions have the following response: + + + +### Success + +```js +// ./actions/responses.js#successResponse +return { + statusCode: 200, + body: { + type: 'EVENT TYPE', + response: { + // Response returned by the event handler action + } + } +} +``` + +### Failure + +```js +// ./actions/responses.js#errorResponse +return { + error: { + statusCode: 400, // 404, 500, etc, + body : { + error: 'YOUR ERROR MESSAGE' + } + } +} +``` + ## `event handler` action The main purpose of this action is to manage an event that notifies you about a change in one of the integrated systems. Typically, its business logic includes an API call to propagate the changes to the other system being integrated. @@ -155,9 +198,9 @@ return { ## event ingestion action -The main purpose of this runtime action is to provide an alternative method to deliver events to the integration, if the 3rd-party, back-office application cannot fulfill the [Events Publishing API's](https://developer.adobe.com/events/docs/guides/api/eventsingress_api/) requirements. +The main purpose of this runtime action is to provide an alternative method to deliver events to the integration, if the 3rd-party, backoffice application cannot fulfill the [Events Publishing API's](https://developer.adobe.com/events/docs/guides/api/eventsingress_api/) requirements. -For more information, see [Ingestion webhooks](./ingestion-webhook.md). +For more information, see [Ingestion webhooks](#ingestion-webhook). To get the URL of the webhook, run the following command: diff --git a/src/pages/app-development/starter-kit/receive-data.md b/src/pages/app-development/starter-kit/receive-data.md index dc329869..f5a30042 100644 --- a/src/pages/app-development/starter-kit/receive-data.md +++ b/src/pages/app-development/starter-kit/receive-data.md @@ -1,6 +1,6 @@ --- title: Receive data from external sources -description: Something +description: Learn about how to receive data from the external backoffice application. keywords: - Extensibility - App Builder @@ -29,7 +29,7 @@ import integration from '/src/_includes/integration.md' # Receive data from external sources -This runtime action is responsible for notifying Adobe Commerce when an `` is created, updated, or deleted in the external back-office application. +This runtime action is responsible for notifying Adobe Commerce when an `` is created, updated, or deleted in the external backoffice application. @@ -99,7 +99,7 @@ The incoming data is validated against a JSON schema defined in the `schema.json ## Payload transformation -If necessary, make any transformation changes necessary for the external back-office application's formatting in the `transformData` function in the `transformer.js` file. +If necessary, make any transformation changes necessary for the external backoffice application's formatting in the `transformData` function in the `transformer.js` file. ## Interact with the Adobe Commerce API diff --git a/src/pages/app-development/starter-kit/send-data.md b/src/pages/app-development/starter-kit/send-data.md index b05ea233..f328011b 100644 --- a/src/pages/app-development/starter-kit/send-data.md +++ b/src/pages/app-development/starter-kit/send-data.md @@ -1,6 +1,6 @@ --- title: Send Commerce data -description: Learn about the runtime action responsible for notifying the external back-office application when data is modified in Adobe Commerce. +description: Learn about the runtime action responsible for notifying the external backoffice application when data is modified in Adobe Commerce. keywords: - Extensibility - App Builder @@ -17,7 +17,7 @@ import integration from '/src/_includes/integration.md' # Send Commerce data -This runtime action is responsible for notifying the external back-office application when an `` is created, updated, or deleted in Adobe Commerce. +This runtime action is responsible for notifying the external backoffice application when an `` is created, updated, or deleted in Adobe Commerce. @@ -86,9 +86,9 @@ The `params` also specify the `event_code` and `event_id`. ## Payload transformation -If necessary, make any transformation changes necessary for the external back-office application's formatting in the `transformData` function in the `transformer.js` file. +If necessary, make any transformation changes necessary for the external backoffice application's formatting in the `transformData` function in the `transformer.js` file. -## Connect to the back-office application +## Connect to the backoffice application Define the connection information in the `sendData` function in the `sender.js` file. Include all the authentication and connection information in the `sender.js` file or an extracted file outside `index.js`. diff --git a/src/pages/app-development/starter-kit/structure.md b/src/pages/app-development/starter-kit/structure.md index 6b9b5fae..a1ef6535 100644 --- a/src/pages/app-development/starter-kit/structure.md +++ b/src/pages/app-development/starter-kit/structure.md @@ -21,7 +21,7 @@ The Adobe Commerce Extensibility Starter Kit provides boilerplate code to synchr - Shipment - Stock -By default, object synchronization is bi-directional. Changes in Commerce are propagated to the external back-office application and vice versa. +By default, object synchronization is bi-directional. Changes in Commerce are propagated to the external backoffice application and vice versa. The source code follows the [file structure](https://developer.adobe.com/app-builder/docs/guides/extensions/extension_migration_guide/#old-file-structure) of a typical App Builder application. Most importantly, the `actions` directory contains the source code for all the serverless actions. diff --git a/src/pages/app-development/starter-kit/webhooks.md b/src/pages/app-development/starter-kit/webhooks.md index e3a49594..589efca7 100644 --- a/src/pages/app-development/starter-kit/webhooks.md +++ b/src/pages/app-development/starter-kit/webhooks.md @@ -25,7 +25,7 @@ The following sections demonstrate all the real-time integrations that Adobe Com The contents of the `./actions/webhook` directory expose a webhook that can be invoked synchronously from Commerce to affect the behavior of a particular business flow. -The `./actions/webhook/check-stock` folder provides a [reference implementation](./webhooks-example.md) of a synchronous webhook action. +The `./actions/webhook/check-stock` folder provides a [reference implementation](#webhooks-example) of a synchronous webhook action. To get the URL of the webhook, run the following command: