Merge pull request #2 from comwrap/review-25-09

Review 25 09

Author: nuzil

.gitignore

@@ -41,4 +41,7 @@ coverage
 # logs folder for aio-run-detached
 logs
 
-adobe-api/mesh/mesh.json
+server.js
+test-placeholder-handler.js
+key.pem
+cert.pem

INSTALL.md

@@ -4,50 +4,79 @@
 
 - Node.js 18+
 - Adobe I/O CLI
+- For PaaS integration with Admin UI: Adobe Commerce Admin UI SDK v3+ (see [Installation Guide](https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/installation/))
 
 ## Adobe Console preparation
 
 ### Create a new project
 
-Go to console.adobe.io and create a new project from template: "App Builder"
+Go to https://developer.adobe.com/console and create a new project from template: "App Builder"
 
 To required environment add: 
 
 * I/O Management API with OAuth Server-to-Server
 * I/O Events
+* Adobe Commerce as a Cloud Service (SaaS) - is required to manage authorization between the application and your Adobe Commerce instance.
 
+## Installation
 
-### Adobe Api Mesh (Optional)
+1. Clone the repository
+2. Run `npm install` to install the dependencies
+3. Copy the env.dist file into .env file: `cp env.dist .env`
+4. Configure the project environment using one of the following methods:
 
-1. Add "Api Mesh" service to your environment.
-2. Rename file `adobe-api/mesh/mesh.json.dist` into `adobe-api/mesh/mesh.json`.
-3. Change required options inside `adobe-api/mesh/mesh.json`.
-    * AC-URL (This should be your Adobe Commerce system's base URL to GQL Endpoint)
+**Option A: Download configuration from Console**
 
-3. Provision Mesh by using this file with `aio api-mesh create adobe-api/mesh/mesh.json`.
+   - Go to [Adobe Developer Console](https://developer.adobe.com/console), select your Project and Environment
+   - Click on "Download All" button
+   - Execute `aio app use <path-to-downloaded-file>` (Merge files if you already have .env file)
 
-## Installation
+**Option B: Configure via CLI**
+
+   ```bash
+   aio login
+   aio console org select
+   aio console project select
+   aio console workspace select
+   aio app use
+   ```
 
-1. Clone the repository
-2. Run `npm install` to install the dependencies
-3. Go to [Project](https://developer.adobe.com/console), select Environment and click on "Download All" button.
-4. Execute `aio app use <path-to-file>` with file you just downloaded. (Merge files if you already have .env file)
 5. Edit `.env` file with your project details.
 Set following variables: 
 
 ```
 AC_GRAPHQL_URL= // Your GraphQL URL 
 AC_DEFAULT_STORE_CODE= // Default Adobe Commerce Store Code
 AC_ENVIRONMENT_ID= // Your Environment ID for Catalog Service if used (optional)
+COMMERCE_BASE_URL= // Commerce instance REST API Url
 ```
 
+> [!NOTE]
+> When configuring the `COMMERCE_BASE_URL` environment variable, the format differs between PaaS and SaaS:
+>
+> For PaaS (On-Premise/Cloud):
+>
+> - Must include your base site URL + `/rest/` suffix
+> - Example: `https://[environment-name].us-4.magentosite.cloud/rest/`
+>
+> For SaaS:
+>
+> - Must be the REST API endpoint provided by Adobe Commerce
+> - Example: `https://na1-sandbox.api.commerce.adobe.com/[tenant-id]/`
+>
+> Make sure to use your actual environment name or tenant ID in the URL. The examples above use placeholder values.
+
+
 6. Configure Adobe Commerce Authorization
 
 In env.dist file you will find set of Auth parameters.
 
-**For Adobe Commerce PaaS:**
+**For Adobe Commerce (PaaS Only):**
+
+> [!NOTE]
+> For SaaS Installation those values are not needed and can be skipped.
 
-These values can be copied from the Integration Details under System > Integrations in your Adobe Commerce backend
+These values can be copied from the Integration Details under System > Integrations in your Adobe Commerce backend.
 
 ```
 COMMERCE_CONSUMER_KEY=
@@ -56,7 +85,7 @@ COMMERCE_ACCESS_TOKEN=
 COMMERCE_ACCESS_TOKEN_SECRET=
 ```
 
-**For Adobe Commerce SaaS:**
+**For Adobe Commerce (SaaS & PaaS):**
 
 Documentation how to get these values is available here: https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/implementation
 
@@ -72,11 +101,53 @@ OAUTH_SCOPES=AdobeID, openid, read_organizations, additional_info.projectedProdu
 7. Create Event Provider for Feed Generator. Run `aio event provider create` and define name. Copy `id` from output.
 Add to `.env` line `FEED_GENERATOR_PROVIDER_ID=<id>`
 
-8. Create Event Metadata for Feed Generator. Run `aio event eventmetadata create PROVIDERID`. Define event code as `feed.generate` and define description as `Generate Feed`.
+8. Create Event Metadata for Feed Generator. Run:
+   ```bash
+   aio event eventmetadata create <FEED_GENERATOR_PROVIDER_ID>
+   ```
+   Replace `<FEED_GENERATOR_PROVIDER_ID>` with the `id` generated in the previous step. Define event code as `feed.generate` and define description as `Generate Feed`.
 
 9. Run `aio app deploy` to deploy the app.
 
-10. Go To your application environment via Browser. Click on "Add Service" -> Event -> 3rd Party Custom Events -> And select your provider and event subscription. In Receiver define "Runtime action" as `processGeneration` action.
+10. Go to Developer console via Browser. Open your application. Click on "Add Service" -> Event -> 3rd Party Custom Events -> And select your provider and event subscription. In Receiver define "Runtime action" as `processGeneration` action.
 
 11. The app is ready to use. Please save the link to your application environment. Additionally, you can replicate all steps in your production environment and publish the application, so it will be available on your exchange dashboard.
 
+## Adding to Adobe Admin UI (SaaS)
+
+For Adobe Commerce SaaS, follow the steps below to add the deployed application to the Commerce Admin
+
+1. Go to Stores -> Configuration in your Adobe Commerce Admin
+2. Go to Adobe Services -> Admin UI SDK
+3. Click "Configure extensions" and choose respective Environment and Application.
+4. Save changes.
+
+For more information and troubleshooting please go to: https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/configuration/
+
+## Adding to Adobe Admin UI (PaaS)
+
+For Adobe Commerce PaaS (On-Premise/Cloud), you need to install and configure the Admin UI SDK module.
+
+### Install the Admin UI SDK Module
+
+1. Install the module via Composer:
+
+```bash
+composer require "magento/commerce-backend-sdk": ">=3.0"
+```
+
+2. Enable the module (for On-premises installation):
+
+```bash
+bin/magento module:enable Magento_AdminUiSdk
+bin/magento setup:upgrade
+bin/magento cache:clean
+```
+
+### Configure the Admin UI SDK
+
+Follow the official Adobe documentation for configuration steps:
+- [Admin UI SDK Configuration](https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/configuration/)
+
+For detailed installation instructions, please refer to:
+- [Admin UI SDK Installation](https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/installation/)

README.md

@@ -4,15 +4,20 @@ Feed Generator is a service that simplifies the process of generating product fe
 
 ## Installation
 
-Module compartible with both Adobe Commerce SaaS and PaaS.
+Module compatible with both Adobe Commerce SaaS and PaaS.
 
 Please see [INSTALL.md](INSTALL.md) for more details.
 
+> [!IMPORTANT]
+> This application is designed to run within the Adobe Experience Cloud Shell or Adobe Commerce Admin UI. 
+> Viewing the deployed application directly via its URL outside of these environments will result in the UI not loading correctly.
+> Always access the application through the Experience Cloud Shell or via the Adobe Commerce Admin panel.
+
 ## Home page / Grid
 
 On the application home page you will see list of the feeds:
 
-![Home page](./docs/images/a6b730f0-513e-4c80-ab0a-460cc80d4efd.png)
+![Home page](./docs/images/home-page.png)
 
 For each feed you can: 
 
@@ -42,7 +47,7 @@ If during feed generation an error occurs, you can see an error in the grid.
 
 On a Grid page you can click on a Feed name, and you will be landed on Edit page of selected feed: 
 
-![Edit Feed](./docs/images/c6960caf-13fb-4d76-a42b-e43d86b802bd.png)
+![Edit Feed](./docs/images/edit-feed.png)
 
 Here you can change the following elements: 
 
@@ -191,22 +196,24 @@ For that go to Settings and click on clean the cache button.
 
 #### Fixed Variables
 
-Header and Footer currently have a support to variables (Only 1 actualy)
+Header and Footer currently have a support to variables (Only 1 actually)
 
 `{{DATA}}` - Current Date/Time - will be in format 2024-10-21T14:45:30.123Z
 
 ### Dynamic variables
 
 Variables are defined using double curly braces (`{{ }}`) and correspond to fields in the Adobe Commerce GraphQL product output. For example, `{{sku}}` will be replaced with the product's SKU.
 
-##### Additonal parameters
+##### Additional parameterss
+
+Note: The examples in 'Additional parameters' show how to use the parameters. The tag names may be different in your API, as they are specific to your system.
 
 ###### Repeating Tags with `count`
 
 When a variable corresponds to an array, you can use the `count` property to repeat the XML tag for each element in the array. For instance, using `count=5` will generate up to 5 tags, each containing a different value from the array.
 
 ```xml
-<g:brand>{{manufacturer count="5"}}</g:brand>
+<image>{{media_gallery.url count="2"}}</image>
 ```
 
 ##### Selecting Specific Array Elements with `index`
@@ -217,37 +224,60 @@ To select a specific element from an array, use the `index` property. This will
 <g:product_type>{{categories.name index="2"}}</g:product_type>
 ```
 
-##### Selecting Attribute with Specific code
+##### Selecting Attribute with Specific code (SaaS specific feature) 
 
 ```xml
 <color>{{attributes.value code='color'}}</color>
 ```
 
 Add attributes.value is an Array of attributes, to get specific attribute, you can use "code" parameter and define attribute with which code you want to use.
 
+#### Example for Google Feed
+
+##### Header
+```xml
+<?xml version="1.0"?>
+<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
+<channel>
+```
 
-#### Example 
+##### Body (PaaS)
 
 ```xml
 <item>
   <g:id>{{sku}}</g:id>
   <title>{{name}}</title>
   <description>{{description.html}}</description>
-  <link>https://www.native-instruments.com/{{detail_page}}</link>
+  <link>https://www.URL.com/{{url_key}}</link>
   <g:image_link>{{image.url}}</g:image_link>
   <g:condition>new</g:condition>
   <g:price>{{price_range.maximum_price.final_price.value}} {{price_range.maximum_price.final_price.currency}}</g:price>
-  <g:availability>In Stock</g:availability>
-  <g:google_product_category><![CDATA[Arts &amp; Entertainment &gt; Hobbies &amp; Creative Arts &gt; Musical Instruments &gt; Electronic Musical Instruments]]></g:google_product_category>
-  <g:identifier_exists>true</g:identifier_exists>
-  <g:product_type index=2>{{categories.name}}</g:product_type>
-  <g:sale_price>{{price_range.minimum_price.final_price.value}}</g:sale_price>
-  <g:brand count=5>{{manufacturer}}</g:brand>
+  <g:category index="2">{{categories.name}}</g:category>
   <g:mpn>{{sku}}</g:mpn>
   <g:additional_image_link><![CDATA[{{image.url}}?width=350&height=350&fit=crop]]></g:additional_image_link>
 </item>
 ```
 
+
+##### Body (SaaS)
+```xml
+<item>
+  <sku>{{sku}}</sku>
+  <description>{{description}}</description>
+  <image>{{images.url count="2"}}</image>
+  <color>{{attributes.value code='color'}}</color>
+  <weight>{{attributes.value code='weight'}}</weight>
+  <price>{{SimpleProductView||price.final.amount.value}} {{SimpleProductView||price.final.amount.currency}}</price>
+</item>
+```
+
+##### Footer
+```xml
+</channel>
+</rss>
+```
+
+
 ## Technical Module implementation
 
 Delete Feed - deleting current feed from the database and from all schedules
@@ -285,7 +315,7 @@ Regenerate Feed - will trigger the event “generate.feed” for a particular fe
 
 * `getAllStores` - get all Adobe Commerce Stores by API
 
-* `generateByCron` - trigger feed generation by OpenWisk alarms. 
+* `generateByCron` - trigger feed generation by OpenWhisk alarms. 
 
 * `getConfig` - receive public module configs. Currently only return type of authorization (ims vs oauth). 
 
@@ -306,8 +336,8 @@ Action is running every 30 minutes and checking by feed settings if it have to b
   Edit / Create New Feed form will contain form to save new Feed.
 
   Current elements: 
-  * Feed Format - select - JSON | XML
-  * Feed Item: Big text field to have XML | JSON there with feed item body
+  * Feed Format - select - XML
+  * Feed Item: Big text field to have XML there with feed item body
   * Feed Header
   * Feed Footer
   * Store View - select with list of available store views on Adobe Commerce (websites also have to be there, but it is not possible to select them)