Edit in GitHubLog an issue

Integrate runtime actions

The create, update, and delete runtime actions in the Adobe Commerce Extensibility Starter Kit perform one of the following functions:

  • Notify the external application - Notifies an external back-office application when an <object> 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/<object>/commerce folder.
  • Notify Commerce - Notifies Adobe Commerce when an <object> 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/<object>/external folder.

starter kit diagram

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 <object> is created, updated, or deleted in Adobe Commerce.

Incoming event payload

The incoming event payload specified during event registration determines the incoming information.

The order runtime action requires the created_at and updated_at fields.

Copied to your clipboard
{
   "id": 1,
   "created_at":"2000-12-31 16:52:40",
   "updated_at":"2000-12-31 16:48:40"
}

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/<object>/commerce/actions.config.yaml under created -> inputs, updated -> inputs, or deleted -> inputs as follows:

Copied to your clipboard
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

Notify Adobe Commerce

This runtime action is responsible for notifying Adobe Commerce when an <object> is created, updated, or deleted in the external back-office application.

Incoming information

The incoming information depends on the external API. The following sample implementation can be modified to accommodate your specific integration needs:


Copied to your clipboard
{
  "email": "sample@email.com",
  "name": "John",
  "lastname": "Doe"
}

Data validation

The incoming data is validated against a JSON schema defined in the schema.json file.


Copied to your clipboard
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "lastname": {"type":  "string"},
    "email": {"type":  "string"}
  },
  "required": ["name", "lastname", "email"],
  "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.

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
  • shipment
    • createShipment - actions/order/commerceShipmentApiClient.js
    • updateShipment - actions/order/commerceShipmentApiClient.js
  • stock
    • updateStock - actions/stock/commerceStockApiClient.js

Parameters from the environment can be accessed from params. Add the necessary parameters in the actions/<object>/external/actions.config.yaml under created -> inputs, updated -> inputs, or deleted -> inputs as follows:

Copied to your clipboard
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

Expected responses

If the runtime action works correctly, a 200 response indicates the event is complete.

Copied to your clipboard
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.

Copied to your clipboard
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.

Copied to your clipboard
return {
    statusCode: 500,
    error: errors
}

stock runtime action best practices

The stock synchronization that connects a third-party system and Adobe Commerce uses the Adobe Commerce inventory/source-items 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 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 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 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 for consuming events.
Jared HooverKevin Harper
Last updated 4/9/2024
Was this helpful?

Community

Support

Adobe Developer

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2024 Adobe. All rights reserved.