Merge pull request AdobeDocs#301 from asalloum5/admin-ui-sdk-2.1

Update documentation for Admin UI SDK 2.1.0 release

Author: keharper

src/data/navigation/sections/admin-ui-sdk.js

@@ -81,7 +81,7 @@ module.exports = [
       ]
     },
     {
-      title: "Admin configuration and local testing",
+      title: "Admin configuration and testing",
       path: "/admin-ui-sdk/configuration.md"
     },
     {

src/pages/_images/admin-ui-sdk-db-log-config.png

@@ -134,13 +134,15 @@ Update the `app.config.yaml` [configuration file](https://developer.adobe.com/ap
 ```yaml
 extensions:
   commerce/backend-ui/1:
-    $include: ext.config.yaml
+    $include: src/commerce-backend-ui-1/ext.config.yaml
 ```
 
 This file now declares extensions and redirects to an `ext.config.yaml` file.
 
 ## Add or update the `ext.config.yaml`
 
+Add or update the `src/commerce-backend-ui-1/ext.config.yaml` file. The `commerce-backend-ui-1` directory contains the `actions` and `web-src` code.
+
 Your extension configuration file should look like this:
 
 ```yaml
@@ -162,8 +164,12 @@ runtimeManifest:
           inputs:
             LOG_LEVEL: debug
           annotations:
-            require-adobe-auth: false
+            require-adobe-auth: true
             final: true
 ```
 
+The package name must be `admin-ui-sdk`, and the action must be `registration`. The `function` can point to any route that returns the registration in the correct expected format.
+
+We recommend securing the registration runtime action by setting `require-adobe-auth` to `true`. The Adobe Commerce instance will correctly load registrations securely based on the provided IMS credentials.
+
 Complete this file with the actions from your app.

src/pages/_images/admin-ui-sdk-general-config.png

@@ -1,6 +1,6 @@
 ---
 title: Admin configuration and testing
-description: Learn how to configure the Admin to enable local testing of your Admin customizations.
+description: Learn how to configure the Admin to enable testing of your Admin customizations.
 keywords:
   - App Builder
   - Extensibility
@@ -10,47 +10,61 @@ keywords:
 
 The Adobe Commerce Admin UI SDK allows you to use a local server to view and test your Admin customizations before you submit your app to the Adobe Marketplace.
 
-## Configure the Admin
+Navigate to **Stores** > Settings > **Configuration** > **Adobe Services** > **Admin UI SDK** screen.
 
-Navigate to **Stores** > Settings > **Configuration** > **Adobe Services** > **Admin UI SDK** and edit the **Local testing** screen. When you enable the local service, all calls are automatically redirected to the local server, instead of connecting to Adobe's App Registry. The values you specify must match the contents of your local `server.js` file.
+## General configuration
 
-[Test with a sample app](#test-with-a-sample-app) provides a sample `server.js` file.
+The **General configuration** section enables the Admin UI SDK and refreshes registrations when changes are made.
 
-![Local server configuration](../_images/sdk-config.png)
+![Admin UI SDK general configuration](../_images/admin-ui-sdk-general-config.png)
 
-1. Select **Yes** from the **Enable Admin UI SDK** menu.
+The Admin UI SDK is disabled by default. To enable it, set the **Enable Admin UI SDK** field to **Yes**.
 
-1. Select **Yes** from the **Enable Local Testing** menu.
+The `Refresh registrations` button reloads all registrations from the registries. It is typically used when changes are made to the registration on the app builder application side or when a new app is added and published, to reflect these changes in the Admin.
 
-1. Set the **Local Server Base URL** that points to your localhost, including the port.
+## Database logging configuration
 
-1. The **Mock Admin IMS Module** menu determines whether to send mock or real authentication credentials for the Adobe Identity Management Service (IMS). Ensure this value is set to **Yes** for early-stage testing. Set the value to **No** when you are ready to test with real credentials.
+The **Database logging configuration** section allows you to save Admin UI SDK log entries for the specified retention period.
 
-1. Set the **Mock IMS Token**. In the sample `server.js` file, this value is set to `dummyToken`.
+![Admin UI SDK database logging configuration](../_images/admin-ui-sdk-db-log-config.png)
 
-1. Set the **Mock IMS Org ID**. In the sample `server.js` file, this value is set to `imsOrg`.
+To save logs, set the **Enable Logs** field to **Yes**. By default, this field is set to **No**.
 
-1. Save your configuration.
+Set the minimum log level to save. Any logs at this level or higher will be stored. By default, the minimum level is set to **Warning**.
 
-1. Clear the cache.
+Set the retention period for logs to be cleaned from the database. This field specifies the number of days. By default, the retention period is set to 1 day.
 
-   ```bash
-   bin/magento cache:flush
-   ```
+## Staging testing
+
+The staging testing option provides a sandbox environment to test your applications using the Admin UI SDK in a real-world setting. This environment can be shared with colleagues for collaborative testing before publishing and deploying to production.
+
+![Admin UI SDK staging testing configuration](../_images/admin-ui-sdk-stage-test-config.png)
+
+1. Select **Yes** from the **Enable testing** menu.
+
+1. Set the **Testing mode** to **Staging**.
 
-## Clean the Admin UI SDK cache
+1. Select all app statuses to load.
 
-The `admin_ui_sdk` cache type stores Admin customizations.  As you develop these customizations, run the following command to ensure you are seeing the latest changes:
+## Local testing
 
-```bash
-bin/magento cache:clean admin_ui_sdk
-```
+When you enable the local service, all calls are automatically redirected to the local server, instead of connecting to Adobe's App Registry. The values you specify must match the contents of your local `server.js` file.
 
-## Test with a sample app
+![Admin UI SDK local testing configuration](../_images/admin-ui-sdk-local-test-config.png)
 
-### Prerequisites
+1. Select **Yes** from the **Enable testing** menu.
 
-- An Adobe Commerce instance installed on the local machine.
+1. Set the **Testing mode** to `Local testing`.
+
+1. Set the **Local Server Base URL** that points to your localhost, including the port.
+
+1. The **Mock Admin IMS Module** menu determines whether to send mock or real authentication credentials for the Adobe Identity Management Service (IMS). Ensure this value is set to **Yes** for early-stage testing. Set the value to **No** when you are ready to test with real credentials.
+
+1. Set the **Mock IMS Token**. In the sample `server.js` file, this value is set to `dummyToken`.
+
+1. Set the **Mock IMS Org ID**. In the sample `server.js` file, this value is set to `imsOrg`.
+
+1. Save your configuration.
 
 ### Configuration
 

src/pages/_images/admin-ui-sdk-local-test-config.png

@@ -10,7 +10,7 @@ keywords:
 
 The `customer grid columns` extension point enables you to add columns to the grid on the **Customers** > **All Customers** page in the Adobe Commerce Admin. This extension point requires an [API Mesh](https://developer.adobe.com/graphql-mesh-gateway/gateway) for Adobe Developer App Builder instance to retrieve the data to be added to the custom columns.
 
-You can use the [`aio api-mesh:describe` command](https://developer.adobe.com/graphql-mesh-gateway/gateway/command-reference/#aio-api-meshdescribe) to retrieve the values of the API key and mesh ID. The key is appended to the mesh endpoint URL.
+You can use the [`aio api-mesh:describe` command](https://developer.adobe.com/graphql-mesh-gateway/gateway/command-reference/#aio-api-meshdescribe) to retrieve the value of the mesh ID.
 
 ## Example customization
 
@@ -20,8 +20,7 @@ You can use the [`aio api-mesh:describe` command](https://developer.adobe.com/gr
 customer: {
     gridColumns: {
         data: {
-            meshId: 'MESH_ID',
-            apiKey: 'API_KEY'
+            meshId: 'MESH_ID'
         },
         properties:[
             {
@@ -35,12 +34,6 @@ customer: {
                 columnId: 'second_column',
                 type: 'integer',
                 align: 'left'
-            },
-            {
-                label: 'Third App Column',
-                columnId: 'third_column',
-                type: 'date',
-                align: 'left'
             }
         ]
     }
@@ -50,6 +43,7 @@ customer: {
 ### Sample API Mesh configuration file
 
 The following sample mesh configuration file defines the external source that contains the data to populate in the custom columns.
+It leverages API Mesh [JSON Schemas handler](https://developer.adobe.com/graphql-mesh-gateway/mesh/basic/handlers/json-schema/).
 
 ```json
 {
@@ -60,11 +54,15 @@ The following sample mesh configuration file defines the external source that co
                 "handler": {
                     "JsonSchema": {
                         "baseUrl": "https://www.example.com",
+                        "operationHeaders": {
+                          "Authorization": "Bearer {context.headers['x-ims-token']}",
+                          "x-gw-ims-org-id": "{context.headers['x-gw-ims-org-id']}"
+                        },
                         "operations": [
                             {
                                 "type": "Query",
                                 "field": "customers",
-                                "path": "/graphql",
+                                "path": "/get-customers?ids={args.ids}",
                                 "method": "GET",
                                 "responseSchema": "./schema.json"
                             }
@@ -77,9 +75,57 @@ The following sample mesh configuration file defines the external source that co
 } 
 ```
 
+### Sample runtime action to retrieve data
+
+The `get-customers` sample runtime action is referenced in the mesh configuration file. It defines the path to the runtime action that retrieves the data of custom columns.
+
+It is important to add the `ids={args.ids}` as part of the query and handle this filtering in the runtime action. This allows Admin UI SDK to load only the necessary data needed to display in the grid columns in the Admin.
+
+```javascript
+export async function main(props) {
+
+    const selectedIds = props.ids ? props.ids.split(',') : [];
+
+    const customerGridColumns = {
+        "customerGridColumns": {
+            "1": {
+                "first_column": "value_1",
+                "second_column": 1
+            },
+            "2": {
+                "first_column": 1,
+                "second_column": "test"
+            }
+        }
+    }
+
+    if (selectedIds.length === 0) {
+        return {
+            statusCode: 200,
+            body: customerGridColumns,
+        }
+    }
+
+    const filteredColumns = {
+        "customerGridColumns": {}
+    }
+
+    selectedIds.forEach(id => {
+        if (customerGridColumns.customerGridColumns[id]) {
+            filteredColumns.customerGridColumns[id] = customerGridColumns.customerGridColumns[id]
+        }
+    })
+
+    return {
+        statusCode: 200,
+        body: filteredColumns
+    }
+}
+```
+
 ### Sample schema file
 
-This sample `schema.json` file is referenced in the mesh configuration file. It defines the response of the external `customerGridColumns` query that fetches column data.
+The  `schema.json` sample file, which is also referenced in the mesh configuration file, defines the response of the external `customerGridColumns` query that fetches column data.
 
 ```json
 {
@@ -97,9 +143,6 @@ This sample `schema.json` file is referenced in the mesh configuration file. It
               },
               "second_column": {
                 "type": "integer"
-              },
-              "third_column": {
-                "type": "integer"
               }
             }
           }
@@ -112,11 +155,39 @@ This sample `schema.json` file is referenced in the mesh configuration file. It
 }
 ```
 
+### Create or update your mesh
+
+Use one of the following commands to create or update your mesh. Be sure to store the mesh ID provided.
+
+```bash
+aio api-mesh:create mesh.json
+```
+
+```bash
+aio api-mesh:update mesh.json  
+```
+
+### Customer data matching
+
+The Admin UI SDK expects the customer ID in Adobe Commerce to correctly match the customer to the data and fill the correct cell.
+
+A default value can be provided to be added to unmatched IDs, or in case data doesn't match, the expected type of the column. If a value is not provided, the cell is left empty.
+
+In case of error, check the Adobe Commerce logs.
+
+The following example provides a default value.
+
+```javascript
+"*": {
+    "first_column": "Default value",
+    "second_column": 0
+}
+```
+
 ## Parameters
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
-| `data.apiKey` | string | Yes | The API key assigned to the GraphQL mesh. |
 | `data.meshId` | string | Yes | The ID of the mesh used to retrieve the column data.|
 | `properties.align` | string | Yes | The alignment of the values in the column. One of `left`, `right`, `center`. |
 | `properties.columnId` | string | Yes | The identifier used in the external dataset to identify the column. |