Environment setup for multi-layer architecture
Full guide on how to set up a local environment with Visual Studio Code (Prophet) compatible with Jenkins structure if you are using OSF Builder Suite For Salesforce Commerce Cloud (Deploy and Data Import) and even more
I firmly believe that all the major Salesforce partners like Astound, OSF Global Services, Capgemini, Valtech, and others have already created an internal educational and procedural knowledge base as to how to set up the local environment, and Continuous Integration and Delivery. You might also already be familiar with the guide from Manu Saini published online on August 19, 2018, about Visual Studio Code integration with Demandware A.K.A Salesforce Commerce Cloud.
That user guide is useful. However, it does not cover multi-layer (multi repo) set up and is a bit outdated since, at the time, it was published Visual Studio Code (VSC) did not yet support multi-root workspaces. VSC overall has improved a lot over the past year, and the Prophet plugin used for SFCC B2C development has been upgraded multiple times with new features.
Why multi-repo is the first question I would ask myself as the reader, well, challenges are to be anticipated when you have multiple teams from different companies working with the same client for one big e-commerce program. Each of them working on their layer and own it. Every team responsible for their layer and it comes with ownership and organizational structure, which we will not cover here. I will talk only about the technical part and this comes with necessity store the core in separate repositories.
I’m delighted that Salesforce now promotes and literally forces new projects to be based on — Storefront Reference Architecture (SFRA), brand new and (technology-wise) entirely based on Javascript without old Demandware pipelines. The previous version, SiteGenesis (SG2), was not segregated, as much as possible from SiteGenesis (SG1) because of pipelines. As a result of this, many of us were forced to work on mixed projects with pipelines and so had to work on Eclipse. Fortunately, the Mesozoic Era (Age of the Dinosaurs) can now come to an end…
Eclipse finally can be uninstalled from your local environment if you are lucky enough to not sit on the legacy projects that are still using SFCC B2C pipelines.
In my current position, I code only on rare occasions to provide some proof of concept, so I don’t have to set up my environment too often. So a few weeks ago when I had to prepare a user guide for the client technical team for local and Jenkins setup that is based on multi-layer multi-repo architecture, I was a bit surprised to discover that the user guide that could previously be used by anyone on the planet involved in SFCC B2C development — was missing… Bureaucracy and privacy forced by old Demandware organizations seem to be impacting the entire SFCC B2C community so that one is not able to find a lot of public resources such as blogs, and certainly, no books talking about this subject… I’m here to change that, so here goes, the example user guide on how to set up local and Jenkins for multi-layer and multi-repo architecture:
Let’s say we have the following e-commerce architecture, in which we have our e-commerce code base for the core in the repository ecom-core. This ecom-core might have in common across all websites core cartridges with integrations, utils, and helpers. For example, it might have modules a cartridge used in SFCC B2C for better abstraction. If you implemented the Provider pattern, you most likely have the modules cartridge in your codebase.
Layer 1, 2 and 3 could be our zoning abstraction if, for example, we would like to have a layer that is specific only to Europe, APAC or maybe Americas (North and South). We could have there “zone” integration, maybe an extension of core functionality that is specific only to that region. Such a layer is very common among big players on the market. Our layers are also repositories: ecom-eu, ecom-apac, ecom-am. These are separate repositories as in most cases each zone will have its own SFCC B2C Realm, the client might have different solution integrators, maybe release management is segregated within the organization or for other reasons.
Layer 1.1, 1.2, 2.1 and so on till 3.2, are our final layers which most likely will reflect our localization layer for county, brand or country and brand together based on your business and case. Let’s say we have ecom-jp which will represent Japan.
So based on the above architecture for a Japanese website I will have to use 3 repositories ecom-jp <- ecom-apac <- ecom-core. Each of those repositories might have multiple cartridges. The idea of the cascade principle would be applied here, in the way that cartridges from those repositories will be used, that is in the same order as the order in the cartridge path. Cartridges from ecom-jp if required will override functionality from ecom-apac and ecom-corecartridges. While functionality in ecom-apac might override ecom-core.
If in all 3 repositories I have the template with the same path and name. Template from
ecom-jprepository will be used.
The description above was required (per my subjective opinion) to understand why we need multiple repositories and why we can’t just use “submodules” or “subrepos”. I have heard of such setups, but for this particular case, multiple repositories will work much better. Moreover, all those layers and repositories might be handled by different solution integrators or even with inhouse teams. If you still think we can achieve the same with “submodules” or “subrepos” please let me know, I would be curious to hear about it.
So finally… how do I set this up in VSC with Prophet? 😫
In the above diagram, you can see from the folder tree perspective, how we can organize our setup on the local environment. Steps for the VSC and Prophet set up are short and simple. Install Prophet and follow the steps below:
- Create a workspace folder
- Clone 3 repositories in the workspace folder
- Open VSC and add 3 repo folders to the current “window” via
File—Add Folder to Workspace…(3 times, as it allows us to add only one folder each time) or by selecting all 3 folders in your navigator and just moving them to the VSC window. - Save workspace and store workspace file under the workspace folder (not mandatory I just prefer to store it like this). You can save workspace via
File—Save Workspace As… - Then in any of the layer repository folder create and fill out your
dw.jsonandlaunch.json - Enable
Prophet: Enable Uploadand enjoy the magic.
You will be able to see how VSC with Prophet is uploading all your cartridges. You will be able to enable or disable auto-upload. Clean the project or upload all cartridges. Debug and control 3 GIT repositories without switching to other tools. For more about Prophet and VSC capabilities, you can follow the links shared at the beginning of the article.
I have not covered the SCSS/CSS or JS building process because it might vary from architecture to architecture, and it does not impact what we have discussed so far. For the current example, you can also have front-end architecture that is able to add/remove/deviate or even extend in any of the layers' core functionality. If you are interested in such a setup let me know and I will consider it for a future article. For now, we still need to discuss what is going on with Jenkins setup…
Please note that at this time you can perform SFCC B2C development within 3 tools: Eclipse, Visual Studio Code, JetBrains IntelliJ.
— Eclipse with Salesforce Commerce Cloud UX Studio
— Visual Studio Code with Prophet
— JetBrains IntelliJ with Salesforce Commerce Cloud Studio
With Jenkins, everything is even simpler. You need store repositories in different Jenkins folder hence your groovy configuration might look like this:
The only thing you will have to replace is ***** with your specific values. Then the configuration above will clone 3 repositories in scm folder what is an analog of your workspace folder on the local environment. Hence the command for building SCSS/CSS and JS will be the same. This script, with the help of OSF Builder Suite For Salesforce Commerce Cloud (Deploy and Data Import) plugin will:
- Clone
ecom-corerepository in thescmfolder - Clone
ecom-apacrepository in thescmfolder - Clone
ecom-jprepository in thescmfolder - Build your project using the
shdefinition - Upload all cartridges from 3 folder locations specified under
sourcePaths - Import into instance
ecom-coresite_templatethenecom-apacsite_templateand afterecom-jpsite_template. This will allow having the same principals in the data sharing and deviation as we have in the code architecture.
In my case, I have data push as separate steps, as I wish to monitor each of them and to be able to check logs for instances of errors later on.
If you followed all the steps up to this point, you should have local and Jenkins set up for multi-layer and multi-repository architectural setup. I hope you really enjoyed this journey and are ready for the next one ✋
My name is Oleg Sapishchuk, and I’m an experienced architect providing digital transformation with unified commerce solutions for some of the world’s best-known and most influential brands. Salesforce B2C Commerce is the topic that I write about most frequently. If you are interested in new or previously written material, I invite you to follow my Medium profile.
Special kudos to Shrikant Naphade, Georgiana Florea and Abdullah Obaidullah.
