A connection is one B2C Commerce instance: a hostname, an account from B2C Credentials and a code version. The active connection is the target for Auto Upload, the debugger, the remote list in B2C Site Scopes and every WebDAV action, and comes first in Deploy Code. Connections live in the B2C Explorer tool window on the right
dw.json is imported once, then ignored
When a project has a dw.json (or connections-source.json) and no saved connections, the plugin imports it once, the first time the project opens, and never reads it again. Opening either file shows a red DO NOT EDIT MANUALLY banner with links to B2C Explorer and B2C Credentials. Right-click the banner for What is SIG/PIG Instances? (Instance types) and What is ODS(On-Demand Sandbox) Instances? (On-Demand Sandboxes)
Add a connection
Add the account
Add the Business Manager account on the Accounts tab of B2C Credentials, or later with Add next to the Account field, see Credentials
Open Connections Settings
In B2C Explorer, click Add... › Add Connection, or pick Add Connection in the toolbar Select Connection popup. The plugin adds New Empty Connection to the tree and opens Connections Settings on it. If you close the dialog without filling it in, delete that connection
Fill in the instance
Enter a Name, paste the full instance URL from your browser into Hostname (the plugin strips the protocol and path) and choose the Account
Test it and pick a code version
Click Test Connection. On success the plugin shows "Connected to" with the hostname and loads the code versions. Pick one in Code Version, or create one with Add Code Version
Close and activate
Changes save as you type. Click Close, then choose the connection in the toolbar Select Connection popup to make it active
Connections Settings
The dialog opens from Add Connection, Edit Connection or Copy Connection. The left side is a tree of groups and connections with its own toolbar (Add..., Delete Connection, Copy Connection, Up, Down, Remove From Group), the right side edits the selected node
| Field | What it does |
|---|---|
| Name | Shown in B2C Explorer, the toolbar and B2C Sync tab |
| Hostname | The instance host. Open Business Manager next to it opens the instance in the browser |
| Account | An account from B2C Credentials, with Add, Edit and Delete buttons |
| Use lowercase username on authentication requests | For accounts stored in mixed case in the plugin but in lowercase on the instance. Without it the debugger may not authenticate (When to use it?) |
| Code Version | Where uploads and deploys go. The instance's active version is marked "[Active on instance]". Add Code Version creates one once the test succeeds |
| Test Connection | Loads the instance's code versions. Runs automatically when you open an existing connection |
OCAPI tab
Optional. Needed to activate code versions from the IDE and to run jobs in the B2C OCAPI tool window
| Field | What it does |
|---|---|
| Use OCAPI | Enables the fields below |
| Obtain a Business Manager user grant | Requests the access token from the instance itself instead of Account Manager. The Shop API uses this grant, in addition to the Data API |
| Credentials | An API client from the API Clients tab of B2C Credentials |
| Version | The OCAPI version used for requests |
| Test OCAPI Connection | Requests a token and reports "Token received. Credentials are valid." on success |
The instance must also allow the client, see Business Manager setup
Certificate Settings tab
For instances that accept code uploads only with a client certificate
| Field | What it does |
|---|---|
| Use Certificate Authentication | Enables the fields below |
| Secure Hostname | The certificate host, for example cert.staging.<realm>.<customer>.demandware.net |
| Certificate File | The client certificate file |
| Passphrase | The certificate passphrase. The field is not masked |
| Test Secure Connection | Reports "Connected. Certificate is valid." on success |
With certificate authentication on, the connection menu also offers Copy Secure Instance URL and remote files offer Copy Secure Remote Path
Instance types
cert.staging host with a client certificate, sandboxes connect with the account aloneThe hostname tells which kind of instance a connection points at. A realm has two instance groups, plus On-Demand Sandboxes:
| Type | Group | Hostname | Notes |
|---|---|---|---|
| Staging | Primary Instance Group (PIG) | staging-<realm>-<customer>.demandware.net | Where code is uploaded and data set up. Uploads need a client certificate, see Certificate Settings tab |
| Development | Primary Instance Group (PIG) | development-<realm>-<customer>.demandware.net | Gets code and data by replication from Staging, for testing |
| Production | Primary Instance Group (PIG) | production-<realm>-<customer>.demandware.net | Gets code and data by replication from Staging, the live storefront |
| POD sandbox | Secondary Instance Group (SIG) | dev01-<realm>-<customer>.demandware.net | One per developer, outside replication. Connect with the account only |
| On-Demand Sandbox | ODS | <realm>-<instanceId>.dx.commercecloud.salesforce.com | Created on demand with an Account Manager API client, see On-Demand Sandboxes |
The built-in OOTB Test Creds OCAPI client works on Development, sandboxes and On-Demand Sandboxes without Account Manager setup, see Credentials
Instance colours and PIG groups
Every Production, Staging and Development connection wears its kind's colour, in Business Manager's hues, so you can tell at a glance where code and actions go. POD sandboxes and On-Demand Sandboxes have no kind and keep the plain cloud
| Colour | Kind | Example hostname |
|---|---|---|
| Red | Production | production-<realm>-<customer>.demandware.net |
| Blue | Staging | staging-<realm>-<customer>.demandware.net or cert.staging.<realm>.<customer>.demandware.net |
| Green | Development | development-<realm>-<customer>.demandware.net |
| Plain | Sandboxes | dev01-<realm>-<customer>.demandware.net or <realm>-<instanceId>.dx.commercecloud.salesforce.com |
The kind comes from the hostname. When the hostname doesn't say, for example a custom domain, the connection's name gives it: PROD EU or prd is Production, stg or Stage is Staging, Dev 2 is Development. A name with sandbox or sbx never gets a kind
The colour follows the instance wherever the plugin names it:
- B2C Explorer: the instance's cloud, and a band of its light colour behind the instance and every row under it
- The toolbar Select Connection: the active connection's cloud on the button and each connection's cloud in the popup
- Deploy Code targets, the connections of an account in B2C Credentials and the instances of B2C MCP
- The instance's tabs in B2C Sync, which take its colour, and in B2C OCAPI and the Log Center, each with a line in its colour
- The editor tab of a file downloaded from the instance, such as a log
A group that holds a Production, Staging or Development connection shows the PIG icon , other groups the plain group icon . This is the Automatic choice. To pick another, right-click the group › Group Icon, or use Icon on the group in Connections Settings: PIG, Group, Clouds, Folder, Classic, or the Production, Staging or Development cloud
Switch the active connection
Only the toolbar Select Connection popup activates a connection. The button shows the active connection's name, or Add Connection while none is active
- Add Connection is at the top, then ungrouped connections, then each group
- The active connection has the connected cloud icon. Each cloud is in its instance's colour, see Instance colours and PIG groups. Hover a connection for its hostname
- Click a name to make it active. B2C Explorer selects and expands it, and collapses the rest as set in General Project Settings
- Each name is also a submenu with most Connection menu items, plus Open Code Versions in Browser
Open Selected Connection next to it offers Open Business Manager and Open Storefront for each site in the project's site.xml files
Most plugin actions stay hidden until the project has a linked cartridge, and the upload, deploy and code version controls also need an active connection. See Cartridges & Modules
Groups and order
Groups keep related instances together, for example one group per customer or realm. Each group shows how many connections it holds, such as Sandboxes 9 connections, or no connections
- Add... › Add Group opens Create Connections Group with a single Group Name field
- Drag connections onto a group to move them in, or use Remove From Group to take one out
- Edit Group renames a group. Deleting a group removes only the group, the connections inside it stay
- Group Icon in the group's menu picks its icon, see Instance colours and PIG groups
B2C Explorer toolbar
| Button | What it does |
|---|---|
| Add... › Add Connection, Add Group | See Add a connection and Groups and order |
| Delete Connection | Deletes the selected connections after Confirm Delete lists them. With a group selected, it reads Delete Group (connections will remain) |
| Edit Connection | Opens Connections Settings on the selected connection or group |
| Copy Connection | Copies each selected connection into the same group. With several selected, it reads Copy N Connections |
| Refresh B2C Explorer | Reloads every connection |
| Focus Active Connection | Selects and expands the active connection |
| Up, Down | Move the selected connection or group one place |
The title bar has Collapse All. Type in the tree to speed-search the expanded nodes
Connection menu
Right-click a connection in B2C Explorer
| Item | What it does |
|---|---|
| Refresh | Reloads the connection's folders |
| Edit Connection | Opens Connections Settings on this connection |
| Copy Instance URL, Copy Username, Copy Password | Copy to the clipboard |
| Copy WebDAV File Access Key, Copy OCAPI Access Key, Copy Storefront Access Key | Shown only when the account has that key for this host |
| Open Business Manager in Browser, Open Logs in Browser, Open IMPEX in Browser | Open the instance pages in the browser |
| Remove From Group | Shown for grouped connections |
| Delete Connection | Removes the connection after a confirmation. The account stays in B2C Credentials |
The WebDAV roots below each connection are covered in WebDAV Explorer
Where connections are stored
- Connection settings are project state in
.idea, so each project keeps its own list - Usernames, passwords and access keys stay in B2C Credentials (IDE password safe or encrypted credentials file), not in the connection
- The Auto Upload switch is stored per connection, see Upload & Auto Upload
- AI agents connected to B2C MCP see each connection by its hostname and kind, never its credentials, see Instances
Troubleshooting
| Message | What to do |
|---|---|
| No Valid B2C Commerce Connection | Deploy started without any connection, or clean or debug without an active one. Use Add Connection in the balloon or pick one in Select Connection |
| "Unable to connect to" the host | Check the hostname and the account |
| Sandbox is down | Start the sandbox, for example in On-Demand Sandboxes, and test again |
| "[401] ... User is not authorized" | The account text case differs from the instance. Fix the username or turn on Use lowercase username on authentication requests |
| Code versions | connection name, "Failed to get code versions. Unable to connect to instance." | The code versions couldn't be read. Click Edit Connection in the balloon, check the hostname and the account, and click Test Connection |
| Connection Error, "An error occurred while uploading files. Please check your connection settings" | An upload couldn't reach the instance. Click Edit Connection in the balloon and test the active connection |
| Config not valid, "Please check your connection settings" | The active connection has no hostname, account or code version for debugging. Click Edit Connection and fill them in |
| OCAPI Not Enabled | Activate Code Version needs OCAPI. Click Edit Connection and turn on Use OCAPI on the OCAPI tab |
| OCAPI Error, "Please check your connection and OCAPI settings." | Activating a code version failed. Edit Shop API and Edit Data API in the balloon open the Business Manager OCAPI settings, compare them with Business Manager setup |
| "Plugin access is unavailable" in B2C Explorer | Click Check Activation, see Purchase & License |