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.

Configure the Admin

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.

Test with a sample app provides a sample server.js file.

Local server configuration

Select Yes from the Enable Admin UI SDK menu.
Select Yes from the Enable Local Testing menu.
Set the Local Server Base URL that points to your localhost, including the port.
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.
Set the Mock IMS Token. In the sample server.js file, this value is set to dummyToken.
Set the Mock IMS Org ID. In the sample server.js file, this value is set to imsOrg.
Save your configuration.

Clear the cache.

bin/magento cache:flush
Copied to your clipboard
bin/magento cache:flush

Clean the Admin UI SDK cache

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:

bin/magento cache:clean admin_ui_sdk
Copied to your clipboard
bin/magento cache:clean admin_ui_sdk

Test with a sample app

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

Run the following command to clone and sync the repository:

git clone git@github.com:magento/app-builder-samples.git
Copied to your clipboard
git clone git@github.com:magento/app-builder-samples.git

Change directories to the cloned repository's root directory.

Create a server.js file to define a local server:

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': '*'
   });
   let json_response;
   
   console.log(url.parse(req.url,true).pathname);
   if (url.parse(req.url,true).pathname == "/config") {
     json_response = {
       baseUrl: "https://localhost.adobe.io:9090/",
       apiKey: "apiKey",
       auth: {
         schema: "Bearer",
         imsToken: "dummyToken"
       },
       imsOrg: "imsOrg",
       version: 1,
       service: "commerce",
       extensionPoint: "backend-ui"
     }
   } else {
     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" }]
     }
     //console.log(json_response);
   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': '*'
   });
   let json_response;
   
   console.log(url.parse(req.url,true).pathname);
   if (url.parse(req.url,true).pathname == "/config") {
     json_response = {
       baseUrl: "https://localhost.adobe.io:9090/",
       apiKey: "apiKey",
       auth: {
         schema: "Bearer",
         imsToken: "dummyToken"
       },
       imsOrg: "imsOrg",
       version: 1,
       service: "commerce",
       extensionPoint: "backend-ui"
     }
   } else {
     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" }]
     }
     //console.log(json_response);
   res.end( JSON.stringify(json_response) );
 }).listen(9090);

Run the local server:

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

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

https://localhost:9090/config

The browser displays a JSON file similar to the following:

{
 "baseUrl":"https://localhost:9090/",
 "apiKey":"apiKey",
 "auth":{
   "schema":"Bearer",
   "imsToken":"dummyToken"
 },
 "imsOrg":"imsOrg",
 "version":1,
 "service":"commerce",
 "extensionPoint":"backend-ui"
 }
Copied to your clipboard
{
 "baseUrl":"https://localhost:9090/",
 "apiKey":"apiKey",
 "auth":{
   "schema":"Bearer",
   "imsToken":"dummyToken"
 },
 "imsOrg":"imsOrg",
 "version":1,
 "service":"commerce",
 "extensionPoint":"backend-ui"
 }

Run your extension locally.

aio app run
Copied to your clipboard
aio app run

Check that the First App on App Builder option has been added to the Marketing menu in the Admin and that selecting the option takes you to the Fetched orders from Adobe Commerce page.