Admin configuration and testing

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.

Navigate to Stores > Settings > Configuration > Adobe Services > Admin UI SDK screen.

General configuration

The General configuration section enables the Admin UI SDK and refreshes registrations when changes are made.

The Admin UI SDK is disabled by default. To enable it, set the Enable Admin UI SDK field to Yes.

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.

Database logging configuration

The Database logging configuration section allows you to save Admin UI SDK log entries for the specified retention period.

To save logs, set the Enable Logs field to Yes. By default, this field is set to No.

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.

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.

Sandbox testing

The sandbox testing option provides an environment to test your applications using the Admin UI SDK in a real-world setting. This option will retrieve Production workspace registrations that match the chosen statuses. This environment can be shared with colleagues for collaborative testing before publishing the application.

1. Select Yes from the Enable testing menu.

2. Set the Testing mode to Staging.

3. Select all app statuses to load.

Local testing

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.

1. Select Yes from the Enable testing menu.

2. Set the Testing mode to Local testing.

3. Set the Local Server Base URL that points to your localhost, including the port.

4. 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.

5. Set the Mock IMS Token. In the sample server.js file, this value is set to dummyToken.

6. Set the Mock IMS Org ID. In the sample server.js file, this value is set to imsOrg.

7. Save your configuration.

Configuration

You can download a sample app from the Adobe Commerce Samples repository to gain insight on how the Admin SDK injects menus and pages into the Admin.

1. Run the following command to clone and sync the repository:

   Copy
   git clone git@github.com:adobe/adobe-commerce-samples.git
   Copied to your clipboard
   git clone git@github.com:adobe/adobe-commerce-samples.git

2. Change directories to the cloned repository's root directory.

3. Create a server.js file in <repoRootDir>/admin-ui-sdk to define a local server:

   Copy
   const http = require('https');
   const fs = require('fs');
   const url = require('url');
   
   const options = {
    key: fs.readFileSync('key.pem'),
    cert: fs.readFileSync('cert.pem')
    };
    
    console.log('Server will listen at :  https://localhost ');
    http.createServer(options, function (req, res) {
      res.writeHead(200, {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Headers': '*'
      });
      
      console.log(url.parse(req.url,true).pathname);
      
      const json_response = [
        {
          "name": "test-extension",
          "title": "Test extension",
          "description": "No",
          "icon": "no",
          "publisher": "aQQ6300000008LEGAY",
          "endpoints": {
            "commerce/backend-ui/1": {
              "view": [{
                "href": "https://localhost:9080/index.html"
              }]
            }
          },
          "xrInfo": {
            "supportEmail": "test@adobe.com",
            "appId": "4a4c7cf8-bd64-4649-b8ed-662cd0d9c918"
          },
          "status": "PUBLISHED" 
        }
      ]
      
      res.end( JSON.stringify(json_response) );
    }).listen(9090);
   Copied to your clipboard
   const http = require('https');
   const fs = require('fs');
   const url = require('url');
   
   const options = {
    key: fs.readFileSync('key.pem'),
    cert: fs.readFileSync('cert.pem')
    };
    
    console.log('Server will listen at :  https://localhost ');
    http.createServer(options, function (req, res) {
      res.writeHead(200, {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Headers': '*'
      });
      
      console.log(url.parse(req.url,true).pathname);
      
      const json_response = [
        {
          "name": "test-extension",
          "title": "Test extension",
          "description": "No",
          "icon": "no",
          "publisher": "aQQ6300000008LEGAY",
          "endpoints": {
            "commerce/backend-ui/1": {
              "view": [{
                "href": "https://localhost:9080/index.html"
              }]
            }
          },
          "xrInfo": {
            "supportEmail": "test@adobe.com",
            "appId": "4a4c7cf8-bd64-4649-b8ed-662cd0d9c918"
          },
          "status": "PUBLISHED" 
        }
      ]
      
      res.end( JSON.stringify(json_response) );
    }).listen(9090);

4. Generate the key.pem certificate in the same directory.

   Copy
   openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048
   Copied to your clipboard
   openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048

5. Generate the cert.pem certificate in the same directory.

   Copy
   openssl req -new -x509 -key key.pem -out cert.pem -days 365
   Copied to your clipboard
   openssl req -new -x509 -key key.pem -out cert.pem -days 365

6. Run the local server:

   Copy
   node server.js
   Copied to your clipboard
   node server.js

7. Make sure you have access to the localhost server configuration by entering the following URL in your browser:

   https://localhost:9090

   The browser displays a JSON file similar to the following:

   Copy
    [
      {
        "name": "test-extension",
        "title": "Test extension",
        "description": "No",
        "icon": "no",
        "publisher": "aQQ6300000008LEGAY",
        "endpoints": {
          "commerce/backend-ui/1": {
            "view": [{
              "href": "https://localhost:9080/index.html"
            }]
          }
        },
        "xrInfo": {
          "supportEmail": "test@adobe.com",
          "appId": "4a4c7cf8-bd64-4649-b8ed-662cd0d9c918"
        },
        "status": "PUBLISHED"
      }
    ]
   Copied to your clipboard
    [
      {
        "name": "test-extension",
        "title": "Test extension",
        "description": "No",
        "icon": "no",
        "publisher": "aQQ6300000008LEGAY",
        "endpoints": {
          "commerce/backend-ui/1": {
            "view": [{
              "href": "https://localhost:9080/index.html"
            }]
          }
        },
        "xrInfo": {
          "supportEmail": "test@adobe.com",
          "appId": "4a4c7cf8-bd64-4649-b8ed-662cd0d9c918"
        },
        "status": "PUBLISHED"
      }
    ]

Custom menu example

1. Change directories to <repoRootDir>/admin-ui-sdk/menu/custom-menu.

2. Run the following command to load dependencies.

   Copy
   npm install
   Copied to your clipboard
   npm install

3. Select your App Builder project.

   Copy
   aio console project select
   Copied to your clipboard
   aio console project select

4. Select the App Builder workspace.

   Copy
   aio console workspace select
   Copied to your clipboard
   aio console workspace select

5. Sync the App Builder project details.

   Copy
   aio app use
   Copied to your clipboard
   aio app use

6. Build your solution.

   Copy
   aio app build
   Copied to your clipboard
   aio app build

7. Run your custom menu extension locally.

   Copy
   aio app run
   Copied to your clipboard
   aio app run

8. Confirm that the Apps section appears on the main menu and the First App on App Builder option appears in the Apps menu in the Admin. Click First App on App Builder and confirm that the Fetched orders from Adobe Commerce page opens.

   

   

Test using project workspaces

Use the following steps to test a specific workspace from your project:

1. Deploy the app to the workspace.

   Copy
   aio app deploy
   Copied to your clipboard
   aio app deploy

   After deployment, the command displays the URL to your app workspace under To view your deployed application:

2. Change the values of the name and href fields in the json_response section of the server.js file to point to your workspace.

   Copy
   {
     "name": "app_name",
     "title": "Test extension",
     "description": "No",
     "icon": "no",
     "publisher": "aQQ6300000008LEGAY",
     "endpoints": {
       "commerce/backend-ui/1": {
         "view": [{
           "href": "https://<app_workspace_url>/index.html"
         }]
       }
     },
     "xrInfo": {
       "supportEmail": "test@adobe.com",
       "appId": "4a4c7cf8-bd64-4649-b8ed-662cd0d9c918"
     },
     "status": "PUBLISHED" 
   }
   Copied to your clipboard
   {
     "name": "app_name",
     "title": "Test extension",
     "description": "No",
     "icon": "no",
     "publisher": "aQQ6300000008LEGAY",
     "endpoints": {
       "commerce/backend-ui/1": {
         "view": [{
           "href": "https://<app_workspace_url>/index.html"
         }]
       }
     },
     "xrInfo": {
       "supportEmail": "test@adobe.com",
       "appId": "4a4c7cf8-bd64-4649-b8ed-662cd0d9c918"
     },
     "status": "PUBLISHED" 
   }

   You can add multiple workspaces to the server to test several applications at once.

Last updated 1/13/2025

Was this helpful?

Yes

No