Skip to Content

Connections

Add, group, test and switch B2C Commerce instance connections in JetBrains IDEs

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

Click B2C Explorer on the right tool window bar. Add Connection opens the connections editor on a new empty connection. Fill in the name, hostname and account, run Test Connection to load the code versions, then close the dialog: every change is already saved

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

FieldWhat it does
NameShown in B2C Explorer, the toolbar and B2C Sync tab
HostnameThe instance host. Open Business Manager next to it opens the instance in the browser
AccountAn account from B2C Credentials, with Add, Edit and Delete buttons
Use lowercase username on authentication requestsFor 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 VersionWhere uploads and deploys go. The instance's active version is marked "[Active on instance]". Add Code Version creates one once the test succeeds
Test ConnectionLoads 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

FieldWhat it does
Use OCAPIEnables the fields below
Obtain a Business Manager user grantRequests the access token from the instance itself instead of Account Manager. The Shop API uses this grant, in addition to the Data API
CredentialsAn API client from the API Clients tab of B2C Credentials
VersionThe OCAPI version used for requests
Test OCAPI ConnectionRequests 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

FieldWhat it does
Use Certificate AuthenticationEnables the fields below
Secure HostnameThe certificate host, for example cert.staging.<realm>.<customer>.demandware.net
Certificate FileThe client certificate file
PassphraseThe certificate passphrase. The field is not masked
Test Secure ConnectionReports "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

The hostname tells the instance type. Staging belongs to the Primary Instance Group and takes code uploads through its cert.staging host with a client certificate, sandboxes connect with the account alone

The hostname tells which kind of instance a connection points at. A realm has two instance groups, plus On-Demand Sandboxes:

TypeGroupHostnameNotes
StagingPrimary Instance Group (PIG)staging-<realm>-<customer>.demandware.netWhere code is uploaded and data set up. Uploads need a client certificate, see Certificate Settings tab
DevelopmentPrimary Instance Group (PIG)development-<realm>-<customer>.demandware.netGets code and data by replication from Staging, for testing
ProductionPrimary Instance Group (PIG)production-<realm>-<customer>.demandware.netGets code and data by replication from Staging, the live storefront
POD sandboxSecondary Instance Group (SIG)dev01-<realm>-<customer>.demandware.netOne per developer, outside replication. Connect with the account only
On-Demand SandboxODS<realm>-<instanceId>.dx.commercecloud.salesforce.comCreated 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

Production is red, Staging blue and Development green, in Business Manager's colours, and sandboxes stay plain. A group with any of them shows the PIG icon. The colour follows the instance into Select Connection, Deploy Code, B2C Sync Log, Log Center and the tabs of files opened from it

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

ColourKindExample hostname
RedProductionproduction-<realm>-<customer>.demandware.net
BlueStagingstaging-<realm>-<customer>.demandware.net or cert.staging.<realm>.<customer>.demandware.net
GreenDevelopmentdevelopment-<realm>-<customer>.demandware.net
PlainSandboxesdev01-<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

ButtonWhat it does
Add... › Add Connection, Add GroupSee Add a connection and Groups and order
Delete ConnectionDeletes the selected connections after Confirm Delete lists them. With a group selected, it reads Delete Group (connections will remain)
Edit ConnectionOpens Connections Settings on the selected connection or group
Copy ConnectionCopies each selected connection into the same group. With several selected, it reads Copy N Connections
Refresh B2C ExplorerReloads every connection
Focus Active Connection Selects and expands the active connection
Up, DownMove 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

ItemWhat it does
RefreshReloads the connection's folders
Edit ConnectionOpens Connections Settings on this connection
Copy Instance URL, Copy Username, Copy PasswordCopy to the clipboard
Copy WebDAV File Access Key, Copy OCAPI Access Key, Copy Storefront Access KeyShown only when the account has that key for this host
Open Business Manager in Browser, Open Logs in Browser, Open IMPEX in BrowserOpen the instance pages in the browser
Remove From GroupShown for grouped connections
Delete ConnectionRemoves 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

MessageWhat to do
No Valid B2C Commerce ConnectionDeploy 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 hostCheck the hostname and the account
Sandbox is downStart 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 EnabledActivate 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 ExplorerClick Check Activation, see Purchase & License

On this page