From 53ac4d410f86cc28147a9349b6553c27fd118271 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Tue, 6 Feb 2024 17:11:15 -0600 Subject: [PATCH 01/13] runtime actions --- .../navigation/sections/app-development.js | 10 + .../app-development/starter-kit/index.md | 11 + .../starter-kit/integration.md | 547 ++++++++++++++++++ 3 files changed, 568 insertions(+) create mode 100644 src/pages/app-development/starter-kit/index.md create mode 100644 src/pages/app-development/starter-kit/integration.md diff --git a/src/data/navigation/sections/app-development.js b/src/data/navigation/sections/app-development.js index facbd6a1..1970517c 100644 --- a/src/data/navigation/sections/app-development.js +++ b/src/data/navigation/sections/app-development.js @@ -56,5 +56,15 @@ module.exports = [ path: "/app-development/amazon-sales-channel/release-notes.md" } ] + }, + { + title: "Starter kit", + path: "/app-development/starter-kit/index.md", + pages: [ + { + title: "Integrate runtime actions", + path: "/app-development/starter-kit/integration.md", + } + ] } ]; \ No newline at end of file diff --git a/src/pages/app-development/starter-kit/index.md b/src/pages/app-development/starter-kit/index.md new file mode 100644 index 00000000..e81921c2 --- /dev/null +++ b/src/pages/app-development/starter-kit/index.md @@ -0,0 +1,11 @@ +--- +title: Starter kit overview +description: Learn how to use the starter kit to expedite setting up out-of-process extensions for Adobe Commerce. +keywords: + - Extensibility + - App Builder + - API Mesh + - Events + - REST + - Tools +--- diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md new file mode 100644 index 00000000..3056b15c --- /dev/null +++ b/src/pages/app-development/starter-kit/integration.md @@ -0,0 +1,547 @@ +--- +title: Integrate runtime actions +description: Learn how to use runtime actions with Adobe Commerce's Starter Kit. +keywords: + - Extensibility + - App Builder + - API Mesh + - Events + - REST + - Tools +--- + +# Integrate runtime actions + +The `create`, `update`, and `delete` runtime actions perform one of the following functions: + +- [Notify the external application](#notify-the-external-application) - Notifies an external back-office application when an `` is created, updated, or deleted in Adobe Commerce +- [Notify Commerce](#notify-adobe-commerce) - Notifies Adobe Commerce when an `` is created, updated, or deleted in an external back-office application + +## Notify the external application + +This runtime action is responsible for notifying the external back-office application when an `` is created, updated, or deleted in Adobe Commerce. + +### Incoming information + +The information specified during [event registration](../../events/configure-commerce.md#subscribe-and-register-events) determines the incoming information. + +The `order` runtime action requires the `created_at` and `updated_at` fields. + + + +#### `customer` + +```json +{ + "id": 1, + "created_at":"2000-12-31 16:52:40", + "updated_at":"2000-12-31 16:48:40" +} +``` + +#### `customer_group` + +```json +{ + "customer_group_id": 6, + "customer_group_code": "Group name code", + "tax_class_id": 4, + "tax_class_name": "Tax class name", + "extension_attributes": { + "exclude_website_ids":[] + } +} +``` + +#### `order` + +```json +{ + "real_order_id": "ORDER_ID", + "increment_id": "ORDER_INCREMENTAL_ID", + "items": [ + { + "item_id": "ITEM_ID" + } + ], + "created_at": "2000-01-01", + "updated_at": "2000-01-01" +} +``` + +#### `product` + +```json +{ + "created_at":"2023-11-24 16:52:40", + "name":"Test product name", + "sku":"2_4_7_TestProduct", + "updated_at":"2023-11-29 16:48:55" +} +``` + +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. + +### Connect to the back-office 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`. + +Parameters from the environment can be accessed from `params`. Add the necessary parameters in the `actions//commerce/actions.config.yaml` under `commerce-created -> inputs`, `commerce-updated -> inputs`, or `commerce-deleted -> inputs` as follows: + + + +#### create + +```yaml +created: + function: commerce/created/index.js + web: 'no' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + HERE_YOUR_PARAM: $HERE_YOUR_PARAM_ENV + annotations: + require-adobe-auth: true + final: true +``` + +#### update + +```yaml +updated: + function: commerce/updated/index.js + web: 'no' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + HERE_YOUR_PARAM: $HERE_YOUR_PARAM_ENV + annotations: + require-adobe-auth: true + final: true +``` + +#### delete + +```yaml +deleted: + function: commerce/deleted/index.js + web: 'no' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + HERE_YOUR_PARAM: $HERE_YOUR_PARAM_ENV + annotations: + require-adobe-auth: true + final: true +``` + +## Notify Adobe Commerce + +This runtime action is responsible for notifying Adobe Commerce when an `` is created, updated, or deleted in the external back-office application. + +### Incoming information + +The incoming information depends on the external API. + +#### `customer` + + + +#### create + +```json +{ + "email": "sample@email.com", + "name": "John", + "lastname": "Doe" +} +``` + +#### update + +```json +{ + "id": 1234, + "email": "sample@email.com", + "name": "John", + "lastname": "Doe" +} +``` + +#### delete + +```json +{ + "id": 1234 +} +``` + +#### `customer_group` + + + +#### create + +```json +{ + "name": "A Group Name", + "taxClassId": 25 +} +``` + +#### update + +```json +{ + "id": 8, + "name": "A Group Name", + "taxClassId": 25 +} +``` + +#### delete + +```json +{ + "id": 8 +} +``` + +#### `order` + + + +#### update + +```json +{ + "id": 99, + "status": "shipped", + "notifyCustomer": false +} +``` + +#### `product` + + + +#### create + +```json +{ + "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6", + "name": "A Product Name", + "description": "A product description" +} +``` + +#### update + +```json +{ + "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6", + "name": "A Product Name", + "price": 99.99, + "description": "A product description" +} +``` + +#### delete + +```json +{ + "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6" +} +``` + +### Data validation + +The incoming data is validated against a JSON schema defined in the `schema.json` file. + +#### `customer` + + + +#### create + +```json +{ + "type": "object", + "properties": { + "name": { "type": "string" }, + "lastname": {"type": "string"}, + "email": {"type": "string"} + }, + "required": ["name", "lastname", "email"], + "additionalProperties": true +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "id": {"type": "number"}, + "name": { "type": "string" }, + "lastname": {"type": "string"}, + "email": {"type": "string"} + }, + "required": ["id", "name", "lastname", "email"], + "additionalProperties": true +} +``` + +#### delete + +```json +{ + "type": "object", + "properties": { + "id": { "type": "number" } + }, + "required": ["id"], + "additionalProperties": false +} +``` + +#### `customer_group` + + + +#### create + +```json +{ + "type": "object", + "properties": { + "name": { "type": "string" }, + "taxClassId": { "type": "number" } + }, + "required": ["name", "taxClassId"], + "additionalProperties": true +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" }, + "name": { "type": "string" }, + "price": {"type": "number"}, + "description": {"type": "string"} + }, + "required": ["sku", "name", "price", "description"], + "additionalProperties": true +} +``` + +#### delete + +```json +{ + "customer_group_id": 6, + "customer_group_code": "Group name code", + "tax_class_id": 4, + "tax_class_name": "Tax class name", + "extension_attributes": { + "exclude_website_ids":[] + } +} +``` + +#### `order` + + + +#### update + +```json +{ + "type": "object", + "properties": { + "id": { "type": "integer" }, + "status": { "type": "string" }, + "notifyCustomer": { "type": "boolean"} + }, + "required": ["id", "status"], + "additionalProperties": true +} +``` + +#### `product` + + + +#### create + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" }, + "name": { "type": "string" }, + "price": {"type": "number"}, + "description": {"type": "string"} + }, + "required": ["sku", "name", "description"], + "additionalProperties": true +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" }, + "name": { "type": "string" }, + "price": {"type": "number"}, + "description": {"type": "string"} + }, + "required": ["sku", "name", "price", "description"], + "additionalProperties": true +} +``` + +#### delete + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" } + }, + "required": ["sku"], + "additionalProperties": false +} +``` + +### 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. + +### Preprocessing data + +Any preprocessing needed before calling the Adobe Commerce API can be implemented in the `preProcess` function in the `pre.js` file. + +### Interact with the Adobe Commerce API + +The interaction with the Adobe Commerce API is defined in the `sendData` function in the `sender.js` file. This function delegates to the following methods and locations: + +- `customer` + - `createCustomer` - `actions/customer/commerceCustomerApiClient.js` + - `updateCustomer` - `actions/customer/commerceCustomerApiClient.js` + - `deleteCustomer` - `actions/customer/commerceCustomerApiClient.js` +- `customer_group` + - `createCustomerGroup` - `actions/customer-group/commerceCustomerGroupApiClient.js` + - `updateCustomerGroup` - `actions/customer-group/commerceCustomerGroupApiClient.js` + - `deleteCustomerGroup` - `actions/customer-group/commerceCustomerGroupApiClient.js` +- `order` + - `addComment` - `actions/order/commerceOrderApiClient.js` +- `product` + - `createProduct` - `actions/product/commerceProductApiClient.js` + - `updateProduct` - `actions/product/commerceProductApiClient.js` + - `deleteProduct` - `actions/product/commerceProductApiClient.js` + +Parameters from the environment can be accessed from `params`. Add the necessary parameters in the `actions//external/actions.config.yaml` under `created -> inputs`, `updated -> inputs`, or `deleted -> inputs` as follows: + + + +#### create + +```yaml +created: + function: created/index.js + web: 'no' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + COMMERCE_BASE_URL: $COMMERCE_BASE_URL + COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY + COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET + COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN + COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET + annotations: + require-adobe-auth: true + final: true +``` + +#### update + +```yaml +updated: + function: updated/index.js + web: 'no' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + COMMERCE_BASE_URL: $COMMERCE_BASE_URL + COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY + COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET + COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN + COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET + annotations: + require-adobe-auth: true + final: true +``` + +#### delete + +```yaml +deleted: + function: deleted/index.js + web: 'no' + runtime: nodejs:16 + inputs: + LOG_LEVEL: debug + COMMERCE_BASE_URL: $COMMERCE_BASE_URL + COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY + COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET + COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN + COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET + annotations: + require-adobe-auth: true + final: true +``` + +### Postprocess data + +Any postprocessing needed after calling the Adobe Commerce API can be implemented in the `postProcess` function in the `post.js` file. + +## Expected responses + +If the runtime action works correctly, a `200` response indicates the event is complete. + +```javascript +return { + statusCode: 200 +} +``` + +If the validation fails, the runtime action will respond with a `400` error, which prevents message processing from being retried by Adobe I/O. + +```javascript +return { + statusCode: 400, + error: errors +} +``` + +The runtime action will respond with a `500` error if there is an issue with the application integration. You can send an array of errors, so the consumer can log the information and trigger the retry mechanism. + +```javascript +return { + statusCode: 500, + error: errors +} +``` From 7a81e17b0ddd3a5b7a7aba03b5b7558fdc13ac1d Mon Sep 17 00:00:00 2001 From: jhadobe Date: Tue, 6 Feb 2024 17:22:36 -0600 Subject: [PATCH 02/13] linting --- src/pages/app-development/starter-kit/integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 3056b15c..cf36b919 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -440,7 +440,7 @@ The interaction with the Adobe Commerce API is defined in the `sendData` functio - `customer` - `createCustomer` - `actions/customer/commerceCustomerApiClient.js` - - `updateCustomer` - `actions/customer/commerceCustomerApiClient.js` + - `updateCustomer` - `actions/customer/commerceCustomerApiClient.js` - `deleteCustomer` - `actions/customer/commerceCustomerApiClient.js` - `customer_group` - `createCustomerGroup` - `actions/customer-group/commerceCustomerGroupApiClient.js` From 317a40f4e05a76246ec686a7a4383de98d43e3e7 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Wed, 7 Feb 2024 14:15:09 -0600 Subject: [PATCH 03/13] resolve display error, add image --- src/pages/app-development/starter-kit/index.md | 4 ++-- src/pages/app-development/starter-kit/integration.md | 12 +++++++----- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/src/pages/app-development/starter-kit/index.md b/src/pages/app-development/starter-kit/index.md index e81921c2..8a489c55 100644 --- a/src/pages/app-development/starter-kit/index.md +++ b/src/pages/app-development/starter-kit/index.md @@ -1,6 +1,6 @@ --- -title: Starter kit overview -description: Learn how to use the starter kit to expedite setting up out-of-process extensions for Adobe Commerce. +title: Adobe Commerce Extensibility Starter Kit +description: Learn how to use the Adobe Commerce Extensibility Starter Kit to expedite setting up out-of-process extensions for Adobe Commerce. keywords: - Extensibility - App Builder diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index cf36b919..6d916cb8 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -1,6 +1,6 @@ --- title: Integrate runtime actions -description: Learn how to use runtime actions with Adobe Commerce's Starter Kit. +description: Learn how to use runtime actions with Adobe Commerce Extensibility Starter Kit. keywords: - Extensibility - App Builder @@ -17,6 +17,8 @@ The `create`, `update`, and `delete` runtime actions perform one of the followin - [Notify the external application](#notify-the-external-application) - Notifies an external back-office application when an `` is created, updated, or deleted in Adobe Commerce - [Notify Commerce](#notify-adobe-commerce) - Notifies Adobe Commerce when an `` is created, updated, or deleted in an external back-office application +![starter kit diagram](../../_images/starter-kit.png) + ## Notify the external application This runtime action is responsible for notifying the external back-office application when an `` is created, updated, or deleted in Adobe Commerce. @@ -29,7 +31,7 @@ The `order` runtime action requires the `created_at` and `updated_at` fields. -#### `customer` +#### customer ```json { @@ -39,7 +41,7 @@ The `order` runtime action requires the `created_at` and `updated_at` fields. } ``` -#### `customer_group` +#### customer_group ```json { @@ -53,7 +55,7 @@ The `order` runtime action requires the `created_at` and `updated_at` fields. } ``` -#### `order` +#### order ```json { @@ -69,7 +71,7 @@ The `order` runtime action requires the `created_at` and `updated_at` fields. } ``` -#### `product` +#### product ```json { From 939f5a9ac78d649697060ad5864c0dc4eee60728 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Wed, 7 Feb 2024 14:28:20 -0600 Subject: [PATCH 04/13] adding info for ASCP-151 --- .../starter-kit/integration.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 6d916cb8..f5cee9d5 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -260,6 +260,31 @@ The incoming information depends on the external API. } ``` +#### `stock` + + + +#### update + +```json +{ + "sourceItems": [ + { + "sku": "sku-one", + "source": "source-one", + "quantity": 0, + "outOfStock": true + }, + { + "sku": "sku-two", + "source": "source-two", + "quantity": 66, + "outOfStock": false + } + ] +} +``` + ### Data validation The incoming data is validated against a JSON schema defined in the `schema.json` file. @@ -428,6 +453,28 @@ The incoming data is validated against a JSON schema defined in the `schema.json } ``` +#### `stock` + + + +#### update + +```json +{ + "type": "array", + "items": { + "properties": { + "sku": { "type": "string" }, + "source": { "type": "string" }, + "quantity": { "type": "number" }, + "outOfStock": { "type": "boolean" } + }, + "required": [ "sku", "source", "quantity", "outOfStock" ], + "additionalProperties": true + } +} +``` + ### 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. @@ -454,6 +501,8 @@ The interaction with the Adobe Commerce API is defined in the `sendData` functio - `createProduct` - `actions/product/commerceProductApiClient.js` - `updateProduct` - `actions/product/commerceProductApiClient.js` - `deleteProduct` - `actions/product/commerceProductApiClient.js` +- `stock` + - `updateStock` - `actions/stock/commerceStockApiClient.js` Parameters from the environment can be accessed from `params`. Add the necessary parameters in the `actions//external/actions.config.yaml` under `created -> inputs`, `updated -> inputs`, or `deleted -> inputs` as follows: From 8cf2e09e9ecfef8f26b91c20d083085259bbf13e Mon Sep 17 00:00:00 2001 From: jhadobe Date: Wed, 7 Feb 2024 16:28:30 -0600 Subject: [PATCH 05/13] adding tab blocks --- .../code-samples/data-customer-group.md | 45 +++ .../starter-kit/code-samples/data-customer.md | 45 +++ .../starter-kit/code-samples/data-order.md | 16 + .../starter-kit/code-samples/data-product.md | 46 +++ .../starter-kit/code-samples/data-stock.md | 19 ++ .../code-samples/incoming-customer-group.md | 28 ++ .../code-samples/incoming-customer.md | 30 ++ .../code-samples/incoming-order.md | 11 + .../code-samples/incoming-product.md | 30 ++ .../code-samples/incoming-stock.md | 22 ++ .../starter-kit/integration.md | 319 ++---------------- 11 files changed, 319 insertions(+), 292 deletions(-) create mode 100644 src/pages/app-development/starter-kit/code-samples/data-customer-group.md create mode 100644 src/pages/app-development/starter-kit/code-samples/data-customer.md create mode 100644 src/pages/app-development/starter-kit/code-samples/data-order.md create mode 100644 src/pages/app-development/starter-kit/code-samples/data-product.md create mode 100644 src/pages/app-development/starter-kit/code-samples/data-stock.md create mode 100644 src/pages/app-development/starter-kit/code-samples/incoming-customer-group.md create mode 100644 src/pages/app-development/starter-kit/code-samples/incoming-customer.md create mode 100644 src/pages/app-development/starter-kit/code-samples/incoming-order.md create mode 100644 src/pages/app-development/starter-kit/code-samples/incoming-product.md create mode 100644 src/pages/app-development/starter-kit/code-samples/incoming-stock.md diff --git a/src/pages/app-development/starter-kit/code-samples/data-customer-group.md b/src/pages/app-development/starter-kit/code-samples/data-customer-group.md new file mode 100644 index 00000000..3cad18b5 --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/data-customer-group.md @@ -0,0 +1,45 @@ + + +#### create + +```json +{ + "type": "object", + "properties": { + "name": { "type": "string" }, + "taxClassId": { "type": "number" } + }, + "required": ["name", "taxClassId"], + "additionalProperties": true +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" }, + "name": { "type": "string" }, + "price": {"type": "number"}, + "description": {"type": "string"} + }, + "required": ["sku", "name", "price", "description"], + "additionalProperties": true +} +``` + +#### delete + +```json +{ + "customer_group_id": 6, + "customer_group_code": "Group name code", + "tax_class_id": 4, + "tax_class_name": "Tax class name", + "extension_attributes": { + "exclude_website_ids":[] + } +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/data-customer.md b/src/pages/app-development/starter-kit/code-samples/data-customer.md new file mode 100644 index 00000000..35a0c923 --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/data-customer.md @@ -0,0 +1,45 @@ + + +#### create + +```json +{ + "type": "object", + "properties": { + "name": { "type": "string" }, + "lastname": {"type": "string"}, + "email": {"type": "string"} + }, + "required": ["name", "lastname", "email"], + "additionalProperties": true +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "id": {"type": "number"}, + "name": { "type": "string" }, + "lastname": {"type": "string"}, + "email": {"type": "string"} + }, + "required": ["id", "name", "lastname", "email"], + "additionalProperties": true +} +``` + +#### delete + +```json +{ + "type": "object", + "properties": { + "id": { "type": "number" } + }, + "required": ["id"], + "additionalProperties": false +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/data-order.md b/src/pages/app-development/starter-kit/code-samples/data-order.md new file mode 100644 index 00000000..3c25ec8f --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/data-order.md @@ -0,0 +1,16 @@ + + +#### update + +```json +{ + "type": "object", + "properties": { + "id": { "type": "integer" }, + "status": { "type": "string" }, + "notifyCustomer": { "type": "boolean"} + }, + "required": ["id", "status"], + "additionalProperties": true +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/data-product.md b/src/pages/app-development/starter-kit/code-samples/data-product.md new file mode 100644 index 00000000..4890bb1a --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/data-product.md @@ -0,0 +1,46 @@ + + +#### create + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" }, + "name": { "type": "string" }, + "price": {"type": "number"}, + "description": {"type": "string"} + }, + "required": ["sku", "name", "description"], + "additionalProperties": true +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" }, + "name": { "type": "string" }, + "price": {"type": "number"}, + "description": {"type": "string"} + }, + "required": ["sku", "name", "price", "description"], + "additionalProperties": true +} +``` + +#### delete + +```json +{ + "type": "object", + "properties": { + "sku": { "type": "string" } + }, + "required": ["sku"], + "additionalProperties": false +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/data-stock.md b/src/pages/app-development/starter-kit/code-samples/data-stock.md new file mode 100644 index 00000000..00fdbbba --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/data-stock.md @@ -0,0 +1,19 @@ + + +#### update + +```json +{ + "type": "array", + "items": { + "properties": { + "sku": { "type": "string" }, + "source": { "type": "string" }, + "quantity": { "type": "number" }, + "outOfStock": { "type": "boolean" } + }, + "required": [ "sku", "source", "quantity", "outOfStock" ], + "additionalProperties": true + } +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/incoming-customer-group.md b/src/pages/app-development/starter-kit/code-samples/incoming-customer-group.md new file mode 100644 index 00000000..a48afcf8 --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/incoming-customer-group.md @@ -0,0 +1,28 @@ + + +#### create + +```json +{ + "name": "A Group Name", + "taxClassId": 25 +} +``` + +#### update + +```json +{ + "id": 8, + "name": "A Group Name", + "taxClassId": 25 +} +``` + +#### delete + +```json +{ + "id": 8 +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/incoming-customer.md b/src/pages/app-development/starter-kit/code-samples/incoming-customer.md new file mode 100644 index 00000000..f9ad59cd --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/incoming-customer.md @@ -0,0 +1,30 @@ + + +#### create + +```json +{ + "email": "sample@email.com", + "name": "John", + "lastname": "Doe" +} +``` + +#### update + +```json +{ + "id": 1234, + "email": "sample@email.com", + "name": "John", + "lastname": "Doe" +} +``` + +#### delete + +```json +{ + "id": 1234 +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/incoming-order.md b/src/pages/app-development/starter-kit/code-samples/incoming-order.md new file mode 100644 index 00000000..f7c72507 --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/incoming-order.md @@ -0,0 +1,11 @@ + + +#### update + +```json +{ + "id": 99, + "status": "shipped", + "notifyCustomer": false +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/incoming-product.md b/src/pages/app-development/starter-kit/code-samples/incoming-product.md new file mode 100644 index 00000000..957782c1 --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/incoming-product.md @@ -0,0 +1,30 @@ + + +#### create + +```json +{ + "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6", + "name": "A Product Name", + "description": "A product description" +} +``` + +#### update + +```json +{ + "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6", + "name": "A Product Name", + "price": 99.99, + "description": "A product description" +} +``` + +#### delete + +```json +{ + "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6" +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/incoming-stock.md b/src/pages/app-development/starter-kit/code-samples/incoming-stock.md new file mode 100644 index 00000000..0aec273e --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/incoming-stock.md @@ -0,0 +1,22 @@ + + +#### update + +```json +{ + "sourceItems": [ + { + "sku": "sku-one", + "source": "source-one", + "quantity": 0, + "outOfStock": true + }, + { + "sku": "sku-two", + "source": "source-two", + "quantity": 66, + "outOfStock": false + } + ] +} +``` diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index f5cee9d5..29c76597 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -10,6 +10,17 @@ keywords: - Tools --- +import IncomingCustomer from './code-samples/incoming-customer.md'; +import IncomingCustomerGroup from './code-samples/incoming-customer-group.md'; +import IncomingOrder from './code-samples/incoming-order.md'; +import IncomingProduct from './code-samples/incoming-product.md'; +import IncomingStock from './code-samples/incoming-stock.md'; +import DataCustomer from './code-samples/data-customer.md'; +import DataCustomerGroup from './code-samples/data-customer-group.md'; +import DataOrder from './code-samples/data-order.md'; +import DataProduct from './code-samples/data-product.md'; +import DataStock from './code-samples/data-stock.md'; + # Integrate runtime actions The `create`, `update`, and `delete` runtime actions perform one of the following functions: @@ -149,331 +160,55 @@ This runtime action is responsible for notifying Adobe Commerce when an ` - -#### create - -```json -{ - "email": "sample@email.com", - "name": "John", - "lastname": "Doe" -} -``` - -#### update +

+ -```json -{ - "id": 1234, - "email": "sample@email.com", - "name": "John", - "lastname": "Doe" -} -``` - -#### delete +#### `customer` -```json -{ - "id": 1234 -} -``` + #### `customer_group` - - -#### create - -```json -{ - "name": "A Group Name", - "taxClassId": 25 -} -``` - -#### update - -```json -{ - "id": 8, - "name": "A Group Name", - "taxClassId": 25 -} -``` - -#### delete - -```json -{ - "id": 8 -} -``` + #### `order` - - -#### update - -```json -{ - "id": 99, - "status": "shipped", - "notifyCustomer": false -} -``` + #### `product` - - -#### create - -```json -{ - "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6", - "name": "A Product Name", - "description": "A product description" -} -``` - -#### update - -```json -{ - "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6", - "name": "A Product Name", - "price": 99.99, - "description": "A product description" -} -``` - -#### delete - -```json -{ - "sku": "b7757d8a-3f3a-4ffd-932a-28cb07debef6" -} -``` + #### `stock` - - -#### update - -```json -{ - "sourceItems": [ - { - "sku": "sku-one", - "source": "source-one", - "quantity": 0, - "outOfStock": true - }, - { - "sku": "sku-two", - "source": "source-two", - "quantity": 66, - "outOfStock": false - } - ] -} -``` + ### Data validation The incoming data is validated against a JSON schema defined in the `schema.json` file. -#### `customer` - - - -#### create - -```json -{ - "type": "object", - "properties": { - "name": { "type": "string" }, - "lastname": {"type": "string"}, - "email": {"type": "string"} - }, - "required": ["name", "lastname", "email"], - "additionalProperties": true -} -``` - -#### update - -```json -{ - "type": "object", - "properties": { - "id": {"type": "number"}, - "name": { "type": "string" }, - "lastname": {"type": "string"}, - "email": {"type": "string"} - }, - "required": ["id", "name", "lastname", "email"], - "additionalProperties": true -} -``` +

+ -#### delete +#### `customer` -```json -{ - "type": "object", - "properties": { - "id": { "type": "number" } - }, - "required": ["id"], - "additionalProperties": false -} -``` + #### `customer_group` - - -#### create - -```json -{ - "type": "object", - "properties": { - "name": { "type": "string" }, - "taxClassId": { "type": "number" } - }, - "required": ["name", "taxClassId"], - "additionalProperties": true -} -``` - -#### update - -```json -{ - "type": "object", - "properties": { - "sku": { "type": "string" }, - "name": { "type": "string" }, - "price": {"type": "number"}, - "description": {"type": "string"} - }, - "required": ["sku", "name", "price", "description"], - "additionalProperties": true -} -``` - -#### delete - -```json -{ - "customer_group_id": 6, - "customer_group_code": "Group name code", - "tax_class_id": 4, - "tax_class_name": "Tax class name", - "extension_attributes": { - "exclude_website_ids":[] - } -} -``` + #### `order` - - -#### update - -```json -{ - "type": "object", - "properties": { - "id": { "type": "integer" }, - "status": { "type": "string" }, - "notifyCustomer": { "type": "boolean"} - }, - "required": ["id", "status"], - "additionalProperties": true -} -``` + #### `product` - - -#### create - -```json -{ - "type": "object", - "properties": { - "sku": { "type": "string" }, - "name": { "type": "string" }, - "price": {"type": "number"}, - "description": {"type": "string"} - }, - "required": ["sku", "name", "description"], - "additionalProperties": true -} -``` - -#### update - -```json -{ - "type": "object", - "properties": { - "sku": { "type": "string" }, - "name": { "type": "string" }, - "price": {"type": "number"}, - "description": {"type": "string"} - }, - "required": ["sku", "name", "price", "description"], - "additionalProperties": true -} -``` - -#### delete - -```json -{ - "type": "object", - "properties": { - "sku": { "type": "string" } - }, - "required": ["sku"], - "additionalProperties": false -} -``` + #### `stock` - - -#### update - -```json -{ - "type": "array", - "items": { - "properties": { - "sku": { "type": "string" }, - "source": { "type": "string" }, - "quantity": { "type": "number" }, - "outOfStock": { "type": "boolean" } - }, - "required": [ "sku", "source", "quantity", "outOfStock" ], - "additionalProperties": true - } -} -``` + ### Payload transformation From e85775b75884aef3809c471e53ec88512a516d24 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Wed, 14 Feb 2024 16:06:01 -0600 Subject: [PATCH 06/13] Adding stock notes and shipment info --- .../starter-kit/code-samples/data-shipment.md | 109 ++++++++++++++++++ .../code-samples/incoming-shipment.md | 63 ++++++++++ .../starter-kit/integration.md | 24 ++++ 3 files changed, 196 insertions(+) create mode 100644 src/pages/app-development/starter-kit/code-samples/data-shipment.md create mode 100644 src/pages/app-development/starter-kit/code-samples/incoming-shipment.md diff --git a/src/pages/app-development/starter-kit/code-samples/data-shipment.md b/src/pages/app-development/starter-kit/code-samples/data-shipment.md new file mode 100644 index 00000000..276362df --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/data-shipment.md @@ -0,0 +1,109 @@ + + +#### create + +```json +{ + "type": "object", + "properties": { + "orderId": { "type": "string" }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "orderItemId": { "type": "number" }, + "qty": { "type": "number" } + }, + "required": ["orderItemId", "qty"], + "additionalProperties": false + } + }, + "tracks": { + "type": "array", + "items": { + "type": "object", + "properties": { + "trackNumber": { "type": "string" }, + "title": { "type": "string" }, + "carrierCode": { "type": "string" } + }, + "required": ["trackNumber", "title", "carrierCode"], + "additionalProperties": false + } + }, + "comments" : { + "type": "array", + "items": { + "type": "object", + "properties": { + "notifyCustomer": { "type": "boolean" }, + "comment": { "type": "string" }, + "visibleOnFront": { "type": "boolean" } + }, + "required": ["notifyCustomer", "comment", "visibleOnFront"], + "additionalProperties": false + } + }, + "stockSourceCode": { "type": "string" } + }, + "required": ["orderId", "items", "tracks", "comments", "stockSourceCode"], + "additionalProperties": false +} +``` + +#### update + +```json +{ + "type": "object", + "properties": { + "id": { "type": "number" }, + "orderId": { "type": "number" }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { "type": "number" }, + "orderItemId": { "type": "number" }, + "qty": { "type": "number" } + }, + "required": ["entityId", "orderItemId", "qty"], + "additionalProperties": false + } + }, + "tracks": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { "type": "number" }, + "trackNumber": { "type": "string" }, + "title": { "type": "string" }, + "carrierCode": { "type": "string" } + }, + "required": ["entityId", "trackNumber", "title", "carrierCode"], + "additionalProperties": false + } + }, + "comments" : { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { "type": "number" }, + "notifyCustomer": { "type": "boolean" }, + "comment": { "type": "string" }, + "visibleOnFront": { "type": "boolean" } + }, + "required": ["entityId", "notifyCustomer", "comment", "visibleOnFront"], + "additionalProperties": false + } + }, + "stockSourceCode": { "type": "string" } + }, + "required": ["id", "orderId", "items", "tracks", "comments", "stockSourceCode"], + "additionalProperties": false +} +``` diff --git a/src/pages/app-development/starter-kit/code-samples/incoming-shipment.md b/src/pages/app-development/starter-kit/code-samples/incoming-shipment.md new file mode 100644 index 00000000..c991d203 --- /dev/null +++ b/src/pages/app-development/starter-kit/code-samples/incoming-shipment.md @@ -0,0 +1,63 @@ + + +#### create + +```json +{ + "orderId": 6, + "items": [ + { + "orderItemId": 7, + "qty": 1 + } + ], + "tracks": [ + { + "trackNumber": "Custom Value", + "title": "Custom Title", + "carrierCode": "custom" + } + ], + "comments": [ + { + "notifyCustomer": false, + "comment": "Order Shipped from API", + "visibleOnFront": true + } + ], + "stockSourceCode": "default" +} +``` + +#### update + +```json +{ + "id": 32, + "orderId": 7, + "items": [ + { + "entityId": 18, + "orderItemId": 7, + "qty": 1 + } + ], + "tracks": [ + { + "entityId": 18, + "trackNumber": "Custom Value", + "title": "Custom Title", + "carrierCode": "custom" + } + ], + "comments": [ + { + "entityId": 18, + "notifyCustomer": false, + "comment": "Order Shipped from API", + "visibleOnFront": true + } + ], + "stockSourceCode": "default" +} +``` diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 29c76597..4a607564 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -14,11 +14,13 @@ import IncomingCustomer from './code-samples/incoming-customer.md'; import IncomingCustomerGroup from './code-samples/incoming-customer-group.md'; import IncomingOrder from './code-samples/incoming-order.md'; import IncomingProduct from './code-samples/incoming-product.md'; +import IncomingShipment from './code-samples/incoming-shipment.md'; import IncomingStock from './code-samples/incoming-stock.md'; import DataCustomer from './code-samples/data-customer.md'; import DataCustomerGroup from './code-samples/data-customer-group.md'; import DataOrder from './code-samples/data-order.md'; import DataProduct from './code-samples/data-product.md'; +import DataShipment from './code-samples/data-shipment.md'; import DataStock from './code-samples/data-stock.md'; # Integrate runtime actions @@ -179,6 +181,10 @@ The incoming information depends on the external API. +#### `shipment` + + + #### `stock` @@ -206,6 +212,10 @@ The incoming data is validated against a JSON schema defined in the `schema.json +#### `shipment` + + + #### `stock` @@ -236,6 +246,9 @@ The interaction with the Adobe Commerce API is defined in the `sendData` functio - `createProduct` - `actions/product/commerceProductApiClient.js` - `updateProduct` - `actions/product/commerceProductApiClient.js` - `deleteProduct` - `actions/product/commerceProductApiClient.js` +- `shipment` + - `createShipment` - `actions/order/commerceShipmentApiClient.js` + - `updateShipment` - `actions/order/commerceShipmentApiClient.js` - `stock` - `updateStock` - `actions/stock/commerceStockApiClient.js` @@ -331,3 +344,14 @@ return { error: errors } ``` + +## `stock` runtime action sample code limitations + +The `stock` synchronization that connects a third-party system and Adobe Commerce uses the Adobe Commerce [inventory/source-items](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/inventorysource-items/#operation/PostV1InventorySourceitems) REST endpoint to process the stock updates. The REST endpoint is included in the Starter Kit as an example implementation and depending on the integration's nonfunctional requirements, it may have the following limitations: + +- Payload size limit enforced by Adobe I/O Runtime - The [maximum `payload` size](https://developer.adobe.com/runtime/docs/guides/using/system_settings/) in Adobe I/O Runtime is not configurable. If an event carries a payload above the limit, for example, when dealing with a full stock synchronization event, it will cause an error. To prevent this situation, we recommend modifying the third-party system to generate event payloads within the `payload` limits. + +- Timeouts during the event processing - The [execution time range](https://developer.adobe.com/runtime/docs/guides/using/system_settings/) for a runtime action in Adobe I/O Runtime differs for `blocking` and `non-blocking` calls, with the limit being higher for `non-blocking` calls. + - You can resolve timeouts in runtime action executions depending on their cause: + - If the timeout is caused by a slow or busy Adobe Commerce REST API call, try using the (https://developer.adobe.com/commerce/webapi/rest/use-rest/asynchronous-web-endpoints/). This approach will cause the Commerce API to respond quickly because the data is processing asynchronously. + - If the timeout is caused by a long-running runtime action, for example, an action that interacts with multiple APIs sequentially and the total processing time exceeds the limits, we recommend using the [journaling approach](https://developer.adobe.com/app-builder/docs/resources/journaling-events/) for consuming events. From bd96f6ccbda8160a13a16ff94e4a1412f5ff92e8 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Wed, 14 Feb 2024 16:23:07 -0600 Subject: [PATCH 07/13] updating pre and post processing info --- .../app-development/starter-kit/integration.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 4a607564..c9d2d913 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -32,6 +32,11 @@ The `create`, `update`, and `delete` runtime actions perform one of the followin ![starter kit diagram](../../_images/starter-kit.png) +## Preprocessing and postprocessing + +- Preprocessing data - Any preprocessing needed before calling the Adobe Commerce API can be implemented in the `preProcess` function in the `pre.js` file. +- Postprocess data - Any postprocessing needed after calling the Adobe Commerce API can be implemented in the `postProcess` function in the `post.js` file. + ## Notify the external application This runtime action is responsible for notifying the external back-office application when an `` is created, updated, or deleted in Adobe Commerce. @@ -101,6 +106,10 @@ The `params` also specify the `event_code` and `event_id`. If necessary, make any transformation changes necessary for the external back-office application's formatting in the `transformData` function in the `transformer.js` file. +### Preprocess data + +Any preprocessing needed before calling the external back-office application API can be implemented in the `preProcess` function in the `pre.js` file. + ### Connect to the back-office 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`. @@ -224,10 +233,6 @@ The incoming data is validated against a JSON schema defined in the `schema.json If necessary, make any transformation changes necessary for the external back-office application's formatting in the `transformData` function in the `transformer.js` file. -### Preprocessing data - -Any preprocessing needed before calling the Adobe Commerce API can be implemented in the `preProcess` function in the `pre.js` file. - ### Interact with the Adobe Commerce API The interaction with the Adobe Commerce API is defined in the `sendData` function in the `sender.js` file. This function delegates to the following methods and locations: @@ -313,10 +318,6 @@ deleted: final: true ``` -### Postprocess data - -Any postprocessing needed after calling the Adobe Commerce API can be implemented in the `postProcess` function in the `post.js` file. - ## Expected responses If the runtime action works correctly, a `200` response indicates the event is complete. From 74adb4ef7ec7ce16bf41bea4dde4c8fae26ff572 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Fri, 16 Feb 2024 12:54:36 -0600 Subject: [PATCH 08/13] code review --- .../navigation/sections/app-development.js | 20 +++++++++---------- .../starter-kit/integration.md | 4 ++-- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/data/navigation/sections/app-development.js b/src/data/navigation/sections/app-development.js index 1970517c..95b3c2ca 100644 --- a/src/data/navigation/sections/app-development.js +++ b/src/data/navigation/sections/app-development.js @@ -35,6 +35,16 @@ module.exports = [ } ] }, + { + title: "Starter kit", + path: "/app-development/starter-kit/index.md", + pages: [ + { + title: "Integrate runtime actions", + path: "/app-development/starter-kit/integration.md", + } + ] + }, { title: "Reference App", path: "/app-development/amazon-sales-channel/index.md", @@ -56,15 +66,5 @@ module.exports = [ path: "/app-development/amazon-sales-channel/release-notes.md" } ] - }, - { - title: "Starter kit", - path: "/app-development/starter-kit/index.md", - pages: [ - { - title: "Integrate runtime actions", - path: "/app-development/starter-kit/integration.md", - } - ] } ]; \ No newline at end of file diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index c9d2d913..ea32fd63 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -346,9 +346,9 @@ return { } ``` -## `stock` runtime action sample code limitations +## `stock` runtime action best practices -The `stock` synchronization that connects a third-party system and Adobe Commerce uses the Adobe Commerce [inventory/source-items](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/inventorysource-items/#operation/PostV1InventorySourceitems) REST endpoint to process the stock updates. The REST endpoint is included in the Starter Kit as an example implementation and depending on the integration's nonfunctional requirements, it may have the following limitations: +The `stock` synchronization that connects a third-party system and Adobe Commerce uses the Adobe Commerce [inventory/source-items](https://adobe-commerce.redoc.ly/2.4.6-admin/tag/inventorysource-items/#operation/PostV1InventorySourceitems) REST endpoint to process the stock updates. The REST endpoint is included in the Starter Kit as an example implementation and depending on the integration's nonfunctional requirements, we suggest the following best practices: - Payload size limit enforced by Adobe I/O Runtime - The [maximum `payload` size](https://developer.adobe.com/runtime/docs/guides/using/system_settings/) in Adobe I/O Runtime is not configurable. If an event carries a payload above the limit, for example, when dealing with a full stock synchronization event, it will cause an error. To prevent this situation, we recommend modifying the third-party system to generate event payloads within the `payload` limits. From d2a2badcc69634a48a7bc4798ca179c5637ea9bf Mon Sep 17 00:00:00 2001 From: jhadobe Date: Fri, 16 Feb 2024 13:33:26 -0600 Subject: [PATCH 09/13] change block number --- src/pages/app-development/starter-kit/integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index ea32fd63..76c89ea3 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -203,7 +203,7 @@ The incoming information depends on the external API. The incoming data is validated against a JSON schema defined in the `schema.json` file.

- + #### `customer` From 3ac3d6ab9fc2b536c12e95a0fa56c71da22e6397 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Fri, 16 Feb 2024 13:45:24 -0600 Subject: [PATCH 10/13] updating other block --- src/pages/app-development/starter-kit/integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 76c89ea3..786f097f 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -172,7 +172,7 @@ This runtime action is responsible for notifying Adobe Commerce when an `
- + #### `customer` From 6e3716a58741518f527fb2270cf3493d3a58fa6b Mon Sep 17 00:00:00 2001 From: Jared Hoover <98363870+jhadobe@users.noreply.github.com> Date: Tue, 20 Feb 2024 10:41:22 -0600 Subject: [PATCH 11/13] Apply suggestions from code review Co-authored-by: Angel Rojo --- src/pages/app-development/starter-kit/integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 786f097f..761901f1 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -114,7 +114,7 @@ Any preprocessing needed before calling the external back-office application API 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`. -Parameters from the environment can be accessed from `params`. Add the necessary parameters in the `actions//commerce/actions.config.yaml` under `commerce-created -> inputs`, `commerce-updated -> inputs`, or `commerce-deleted -> inputs` as follows: +Parameters from the environment can be accessed from `params`. Add the necessary parameters in the `actions//commerce/actions.config.yaml` under `created -> inputs`, `updated -> inputs`, or `deleted -> inputs` as follows: @@ -354,5 +354,5 @@ The `stock` synchronization that connects a third-party system and Adobe Commerc - Timeouts during the event processing - The [execution time range](https://developer.adobe.com/runtime/docs/guides/using/system_settings/) for a runtime action in Adobe I/O Runtime differs for `blocking` and `non-blocking` calls, with the limit being higher for `non-blocking` calls. - You can resolve timeouts in runtime action executions depending on their cause: - - If the timeout is caused by a slow or busy Adobe Commerce REST API call, try using the (https://developer.adobe.com/commerce/webapi/rest/use-rest/asynchronous-web-endpoints/). This approach will cause the Commerce API to respond quickly because the data is processing asynchronously. + - If the timeout is caused by a slow or busy Adobe Commerce REST API call, try using the [asynchronous web endpoints](https://developer.adobe.com/commerce/webapi/rest/use-rest/asynchronous-web-endpoints/). This approach will cause the Commerce API to respond quickly because the data is processing asynchronously. - If the timeout is caused by a long-running runtime action, for example, an action that interacts with multiple APIs sequentially and the total processing time exceeds the limits, we recommend using the [journaling approach](https://developer.adobe.com/app-builder/docs/resources/journaling-events/) for consuming events. From 75cc6463f3da94eed2d1cdf09b431d02d9885622 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Tue, 20 Feb 2024 11:08:09 -0600 Subject: [PATCH 12/13] dev feedback --- src/pages/app-development/starter-kit/integration.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index 761901f1..fa5ed69e 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -27,8 +27,8 @@ import DataStock from './code-samples/data-stock.md'; The `create`, `update`, and `delete` runtime actions perform one of the following functions: -- [Notify the external application](#notify-the-external-application) - Notifies an external back-office application when an `` is created, updated, or deleted in Adobe Commerce -- [Notify Commerce](#notify-adobe-commerce) - Notifies Adobe Commerce when an `` is created, updated, or deleted in an external back-office application +- [Notify the external application](#notify-the-external-application) - Notifies an external back-office application when an `` is created, updated, or deleted in Adobe Commerce. Actions that react to Adobe Commerce events and notify the external back-office application are located in the `actions//commerce` folder. +- [Notify Commerce](#notify-adobe-commerce) - Notifies Adobe Commerce when an `` is created, updated, or deleted in an external back-office application. Actions that react to back-office application events and notify Adobe Commerce are located in the `actions//external` folder. ![starter kit diagram](../../_images/starter-kit.png) @@ -106,10 +106,6 @@ The `params` also specify the `event_code` and `event_id`. If necessary, make any transformation changes necessary for the external back-office application's formatting in the `transformData` function in the `transformer.js` file. -### Preprocess data - -Any preprocessing needed before calling the external back-office application API can be implemented in the `preProcess` function in the `pre.js` file. - ### Connect to the back-office 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`. @@ -169,7 +165,7 @@ This runtime action is responsible for notifying Adobe Commerce when an `
From 4721343e04d6c3f1839a2843b7930d6e8954caa3 Mon Sep 17 00:00:00 2001 From: jhadobe Date: Tue, 20 Feb 2024 11:46:14 -0600 Subject: [PATCH 13/13] developer feedback --- src/pages/app-development/starter-kit/integration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/app-development/starter-kit/integration.md b/src/pages/app-development/starter-kit/integration.md index fa5ed69e..434ede0f 100644 --- a/src/pages/app-development/starter-kit/integration.md +++ b/src/pages/app-development/starter-kit/integration.md @@ -41,9 +41,9 @@ The `create`, `update`, and `delete` runtime actions perform one of the followin This runtime action is responsible for notifying the external back-office application when an `` is created, updated, or deleted in Adobe Commerce. -### Incoming information +### Incoming event payload -The information specified during [event registration](../../events/configure-commerce.md#subscribe-and-register-events) determines the incoming information. +The incoming event payload specified during [event registration](../../events/configure-commerce.md#subscribe-and-register-events) determines the incoming information. The `order` runtime action requires the `created_at` and `updated_at` fields.