The Cartridge Path Editor turns a colon-separated XML value into an ordered list. Add linked cartridges, enter a cartridge name, remove entries, and drag them into the order you need. The top entry loads first
Open the editor
Open the local XML file
Open a site's site.xml containing <custom-cartridges>, or a preferences.xml containing <preference preference-id="CustomCartridges"> for the Business Manager path
Use the cartridge path CodeLens
Above the XML element, select Edit [site ID] Cartridge Path ([count]) or Edit BM Cartridge Path ([count]). The site ID comes from the site-id attribute of <site>, or from the folder of the file when the attribute is missing. The editor opens in its own tab, for example RefArch Cartridge Path (3) or BM Cartridge Path (2), and the count in the tab title follows your changes. Selecting the lens again brings that tab back instead of opening a second one
Change the order and save the XML
Drag entries in In cartridge path to change priority. Choose Open XML to review the updated value and save the document with VS Code. The editor shows Unsaved while that document has pending changes, then Saved after it is saved
For example, a local site export might contain:
<custom-cartridges>app_demo_custom:app_storefront_base</custom-cartridges>Moving app_demo_custom below app_storefront_base changes the value to app_storefront_base:app_demo_custom. Review the order before applying it to a sandbox because it changes which implementation takes priority
The editor
The header shows the path's title, for example RefArch Cartridge Path or Business Manager Cartridge Path, its count and the XML file relative to the workspace. On the right:
| Control | What it does |
|---|---|
| Saved, Unsaved | Whether the XML document has unsaved changes. Hover Unsaved to see "The XML document has unsaved changes" |
| Applying… | Shows while a change is written into the XML document |
| Update failed | A change could not be written. A message below the header says why, and both clear after a few seconds |
| Open XML | Opens the XML document in the same editor group |
| Refresh | Reads the XML and the linked cartridges again |
In cartridge path
The left list is the path in load order, under Drag to reorder · top loads first. Each entry shows its position, a cartridge icon, its name and where the linked cartridge is: the workspace folder, then the path inside it, for example storefront • cartridges/app_custom. A name that matches no linked cartridge shows Not linked to this project and the not-linked cartridge icon. Hover or select an entry to show its Copy and Remove buttons
| Action | How |
|---|---|
| Reorder | Drag an entry by its row. A line shows where it lands. In a list longer than the panel, Scroll up and Scroll down hints show while you drag, and holding the pointer near the top or bottom edge scrolls the list |
| Add a name | Type it in Add cartridge by name… and press Enter or Add. It goes to the top, and it doesn't need to be linked to the workspace |
| Remove | Remove on the entry takes it off the path. The cartridge's files stay in the project |
| Copy | Copy on the entry copies its name and confirms with "Cartridge name copied to clipboard → app_custom" |
| Filter | Filter cartridges in path… narrows the list by position, name or location. The count beside it shows matches of the total, for example 3/5, and the clear button resets it. Dragging in a filtered list still drops at the right place in the full path |
Enter one cartridge name at a time. Names cannot contain spaces, :, <, >, or &. Adding an existing name focuses its current entry instead of inserting another copy
Linked cartridges not in path
The right list shows the cartridges linked to the workspace that the path doesn't use yet, see Cartridges & Overrides. It reads "All linked cartridges are already included." when every linked cartridge is on the path, and it updates when you link or unlink a cartridge
| Action | How |
|---|---|
| Add at a position | Drag the cartridge into In cartridge path. The path list's border highlights, and a line shows where the cartridge lands |
| Add at the end | Add on the entry appends it to the path |
| Add all | Add All appends every cartridge in this list |
| Copy | Copy on the entry copies its name |
| Filter | Filter linked cartridges… narrows the list by name or location |
Saving and undo
Every change is an ordinary edit of the XML document. Only the cartridge path value changes, and the rest of the file, its formatting and the whitespace around the value stay as they were. A self-closing element such as <custom-cartridges/> gets the path as its content
The document isn't saved for you. Its tab shows the unsaved dot and the editor reads Unsaved. Choose Open XML to review the value, then save the file with Cmd+S on macOS or Ctrl+S on Windows/Linux. The editor reads Saved as soon as the document is saved
Each change is also one step in the document's undo history, so Undo in the XML editor reverts it and the list follows. Edits you make in the XML yourself show up in the list right away, and if the element moves because you edited the file above it, the editor keeps following it
Local XML and the active site
The editor updates the open XML document. It does not change the cartridge path in Business Manager or deploy cartridge files. Apply the saved XML to the target instance through your normal site import process when ready
When the active B2C Site Scope comes from this local site.xml, saving a changed cartridge path refreshes that scope's code-assistance context. A scope selected from the remote instance uses the remote path, so editing a local export does not change that selection's source
Troubleshooting
- The CodeLens is missing: check that the local file is named
site.xmlorpreferences.xml, contains the matching element, and VS Code CodeLens is enabled. This feature requires active Intellij SFCC access, including trial access - A cartridge is marked “Not linked to this project”: its name is in the XML, but the extension has no linked local cartridge with that name. Link the local cartridge if you need its source for navigation
- "The cartridge path changed or was removed. Reopen the editor from CodeLens.": the element the editor was opened for is no longer in the XML. Close the panel and reopen it from the current XML CodeLens so it targets the correct element
- "Could not update the cartridge path in site.xml.": VS Code could not apply the edit, for example because the file is read-only. Make the file writable and try again
- "Enter one cartridge name without spaces, ':', '<', '>', or '&'.": type one name, with no separators
- Sandbox behavior is unchanged: saving the local XML updates your project. Review whether the path was applied to the intended site on the instance and whether its cartridges were deployed
