-
Notifications
You must be signed in to change notification settings - Fork 7
Documentation
This documentation is in an early state and work in progress. Once completed, this page will be deleted and the documentation moved to experienceleague.adobe.com
- Follow steps 1-3 from https://developer.adobe.com/app-builder/docs/getting_started/first_app/ to setup a new AppBuilder project in the Adobe Developer console, until you are signed in from the CLI.
- Instead of creating a new project, you can re-use the existing project as a starting point. Go to https://github.com/adobe-rnd/aem-commerce-ssg and create a fork in your GitHub organisation.
- Clone your fork and open it in your favourite code editor.
- Go to the repository settings and under "Secrets and variables → Actions" add the following secrets:
- AIO_RUNTIME_AUTH_PROD
- AIO_RUNTIME_NAMESPACE_PROD
- AIO_RUNTIME_AUTH_STAGE
- AIO_RUNTIME_NAMESPACE_STAGE
- You can retrieve the values for these environment variables from the AppBuilder project in the developer console. Select the corresponding workspace (Production and Stage) and click on "Download all". Namespace name and auth string can be found in the downloaded JSON files.
- Make sure you activate the GitHub actions. By default, any commit to the main branch of your project will be deployed to the staging workspace of your AppBuilder project. Any release will trigger an deployment to the production workspace. We recommend to stick to this workflow.
- Go to the repository settings and under "Secrets and variables → Actions" add the following secrets:
- Open the "app.config.yaml" file and adjust the following configuration parameters:
- LOG_LEVEL: Keep it on debug during development. For production deployment, lower it to info or error.
- HLX_CONTENT_URL: The aem.live URL of your project, e.g. https://main--aem-boilerplate-commerce--hlxsites.aem.live
- HLX_PRODUCTS_TEMPLATE (optional): Path to an optional Edge Delivery page which will be used as template. The page needs to include a product-details block which will be filled by the renderer. If no template is selected a page with only a product-details block is rendered.
- HLX_ORG_NAME: GitHub Org owning the repo
- HLX_SITE_NAME: Name of the site, either repo-backed or repoless; in the first case, it's the repository name.
- HLX_STORE_URL: The public facing URL of your project.
- HLX_CONFIG_NAME: Name of the config json file/spreadsheet acting as config.
- HLX_PATH_FORMAT: URL format for PDP URLs. This is used for parsing and generating product URLs.
- For the default format as used in the boilerplate, you can use "/products/{urlKey}/{sku}".
- A locale can be added like this: "/{locale}/products/{urlKey}/{sku}".
- Using only an url key is possible as well: "/{urlKey}"
- HLX_LOCALES: comma-separated list of locales, which prefix store URLs (i.e. in case of us, "/us/products/product-1234"). If null, no prefix will be considered in building URLs.
- Un-comment the triggers and rules section.
- Look through the project code and search for the "TODO" keyword. Adjust these parts of the code to your project. In particular make sure that:
- Structured data contains correct gtin values.
- Variant axes correspond to schema.org types.
- Additional structured data is added (e.g. ratings and reviews).
- We recommend to also update the E2E tests accordingly.
- Implementation of mapLocale method was adjusted for your multi store use case.
- Example implementation:
function mapLocale(locale, context) {
// Compare the locale against the list of available locales from HLX_LOCALES
if (!locale || !context.allowedLocales.includes(locale)) {
// If the locale is not allowed, the action should fail so that the page is not published to Edge Delivery
throw new Error('Unsupported locale')
}
// If you're using a dedicated config file per locale:
return {
locale,
configName: [locale, context.configName].join('/'),
}
// Otherwise, if you keep the same config file for all locales, but only overwrite the store code:
return {
locale,
configOverrides: {
'commerce.headers.cs.Magento-Store-Code': locale,
}
}
}- Additionally we recommend that you setup log forwarding according to the documentation to store and track all log messages of your actions within your own infrastructure.
- Download the stage configuration JSON from your project in Developer Console and run "aio app use {configurationFileName}" in your project folder. You're now set to run CLI commands like "aio app dev" to run the project locally or "aio app deploy" to deploy it on your staging namespace.
-
To add server-side rendered product detail pages to your Edge Delivery project, you need to configure an overlay content source.
- As this feature is only available on Helix 5, please ensure that you have followed https://www.aem.live/developer/upgrade to update your project before continuing with the setup.
- An overlay content source is used in addition to your normal content source (documents, AEM or DA). When performing previewing and publishing operations, the Edge Delivery pipeline will request the content first from the overlay content source. If the overlay content source provides an HTTP 200 response, the content is taken from the overlay. In any other case the content is requested from your original content source.
-
The polling service requires a list of published products to re-publish and unpublish product paged. Please create an 'published-products-index' index by adding the following index definition to the config service using the admin API.
index-published-products:
# adjust paths based on your specific requirements (i.e. locale, routes, ...)
target: s3://published-products-index.json
include:
- 'products/**'
properties:
sku:
select: head > meta[name="sku"]
value: attribute(el, "content")
last-modified:
select: none
value: parseTimestamp(headers["last-modified"], "ddd, DD MMM YYYY hh:mm:ss GMT")
# for benchmarking in the AppBuilder action
product-last-modified:
select: head > meta[name="x-cs-lastModifiedAt"]
value: parseTimestamp(attribute(el, "content"), "YYYY-MM-DDTHH:mm:ss.SSSZ")-
The API to interact with the config bus is documented in https://www.aem.live/docs/admin.html#tag/siteConfig. You can either use a terminal tool of your choice (e.g. curl) or https://labs.aem.live/tools/admin-edit to interact with the API.
- When using https://labs.aem.live/tools/admin-edit please make sure that your account has admin access to your project and you're logged in with the sidekick extension.
- For curl, login using the API first to retrieve an authentication token.
-
After deploying the AppBuilder project, assuming the env vars have been exported/expanded correctly, execute
aio rt action invoke aem-commerce-ssg/get-overlay-url -r -
Update the following section to your configuration, and copy and paste the generated URL in the "url" field below:
"content": {
"source": {
// Keep your existing content source
},
"overlay": {
"type": "markup",
"url": "https://firefly.azureedge.net/{bucket_id_as_above}-public/public/pdps",
"suffix": ".html"
}
}- After configuring the overlay, you can disable folder mapping for product pages by removing the corresponding folder mapping configuration. NOTE: If you have a very large catalog, we recommend to keep folder mapping enabled for product pages that will not be rendered by this service.
- After you completed the setup steps, you can deploy the AppBuilder project by creating a release in GitHub (recommended) or running the aio app deploy command with your production configuration.
- You can validate successful deployment of your action, by accessing "https://{namespace}.adobeioruntime.net/api/v1/web/aem-commerce-ssg/pdp-renderer/products/{urlKey}/{sku". You should be able to see a rendered version of your product detail page.
- The rollout of PDPs might be required after the storefront is live and running, for example in order to refresh the pages to reflect changes that by design are not considered as a change in the Product model. See Test, Monitoring and Ops for details.
- The indexing process usually takes between 10-30 minutes, but in the first cold start it should be faster. You can check if the index was created by simply navigating to https://store-base-url/published-product-index.json. Once it's ready, you can proceed with the next steps.
This section is related to the specific tools to test and monitor the polling and rendering flow as well as to debug any issues. All the tools depend on a pair of common environment variables in order to connect to AppBuilder:
Either the ones generated by aio app use command as above:
AIO_runtime_namespace=...
AIO_runtime_auth=...or uppercase
AIO_RUNTIME_NAMESPACE=...
AIO_RUNTIME_AUTH=...
- Storage Bucket Explorer (Alpha): this is a tool to explore what's inside the storage bucket where the rendered markup is persisted and from where its served to the Helix infrastructure (that picks it up during the preview phase). Usage: just provide the Namespace and Auth params (from the Env vars/Adobe I/O project json file) and hit "Connect". You will find csv files with the list of crawled products (from Catalog Service) and .html files with the actual markup.
In the tools/ folder, there are scripts for troubleshooting and monitoring the polling and change detection activity, specifically:
-
Roll back PDPs (disaster recovery scenario) In case the poller has published pages that should not be accessible (nor indexed), it is important to act promptly in order to get them removed and prevent indexing by search engines, by triggering a bulk unpublish job in the AEM Admin API. It's possible to generate the request body for the job with a one-line command (requires the cli util
jq):curl "https://www.mystorefront.com/us/products-index.json" -s | jq '{ "delete": true, "paths": [.data[].path]}' > delete-req-body.json
The path
/products-index.jsonmay vary depending on your indexing setup. Then, use the JSON as the request body to make a REST call according to: https://www.aem.live/docs/admin.html#tag/publish/operation/bulkPublish (please note: the "delete": true param turns the publish operation into a "delete publish" job). You can follow the job status following the semantic links in the JSON response. -
refresh-pdps.js This tool cleans up the internal list of tracked products and forces restart of the product change detector: this way all the products in the catalog will be republished.
-
download-poller-stats.js This script is used to download and display poller statistics from Adobe I/O Runtime. It can extract time series of the statistics and generate charts.
-
Usage: Ensure you have the required environment variables set in your .env file.
Usage: `node download-poller-stats.js [options]` Options: -d, --date <YYYY-MM-DD> Select data for a specific day. If not provided, defaults to today's date -c, --chart <chart_filename.svg> Generate a chart from the data, showing latency distribution and correlation with other factors. In addition, generate a JSON file with corresponding data series. -h, --help Display help for cli tool -f, --file <records_filename.{csv,json}> The filename to save the records to; JSON and CSV formats are supported.
-
-
check-products-count.js This script checks the product count consistency between the
published-products-indexand the Adobe Commerce store. The products count is retrieved in Adobe Commerce via a Live Search query. This script is a starting point to investigate issues in PDP publishing or rendering.-
Usage: Ensure you have the required env vars configured (in .env file):
COMMERCE_STORE_CODE=<your_store_code> COMMERCE_STORE_URL=<your_store_url> COMMERCE_CONFIG_NAME=<your_config_name>
Then, run the script using Node.js:
node check-products-count.js -
The script will throw an error if the product counts do not match, indicating the expected and actual product counts. PLEASE NOTE: the number of products listed is just an indication to check for "macroscopic" failures, slight differences might be due to specific Commerce configs/attributes for certain products which might not show up in the query results.
-
In case of a mismatch, it is advised to check the logs and statistics of the service, by using Adobe I/O cli tool and looking at the invocation results - which are quite descriptive, as well as
download-poller-stats.js, to have more specific insights on the nature of the issue (whether it's a failed publish task, for example).
-
"result": {
"elapsed": 13001,
"state": "completed",
"status": {
"failed": 29,
"ignored": 4572,
"published": 0,
"unpublished": 0
},
"timings": {
"fetchedLastModifiedDates": {
"avg": 5710,
"max": 5710,
"min": 5710,
"n": 1
},
"fetchedSkus": {
"avg": 0,
"max": 0,
"min": 0,
"n": 1
},
"loadedState": {
"avg": 47,
"max": 47,
"min": 47,
"n": 1
},
"previewDuration": {
"avg": 1677.2758620689656,
"max": 3180,
"min": 1037,
"n": 29
},
"publishedPaths": {
"avg": 7075,
"max": 7075,
"min": 7075,
"n": 1
},
"unpublishedPaths": {
"avg": 143,
"max": 143,
"min": 143,
"n": 1
}
}
664C
}[TBD]
Once all the actions are ready and Edge Delivery configs are all done, you might want to set up cron jobs in App Builder that automate the execution of your action, including:
Product scraper: fetching the latest products from Live Search and make them available in App Builder Files Storage. Recommended interval: 60 minutes
PDP poller: checking product updates, comparing the output HTML and re-preview and publish the updated pages. Recommended interval: 1 minute
You can put the triggers and rules in app.config.yaml file, and run "aio app deploy" to deploy them in App Builder.
triggers:
productPollerTrigger:
feed: /whisk.system/alarms/interval
inputs:
minutes: 5
productScraperTrigger:
feed: /whisk.system/alarms/interval
inputs:
minutes: 60
rules:
productPollerRule:
trigger: productPollerTrigger
action: check-product-changes
productScraperRule:
trigger: productScraperTrigger
action: fetch-all-productsThis documentation is in an early state and work in progress. Once completed, this page will be deleted and the documentation moved to experienceleague.adobe.com