I’m a confirmed Administrator.* I love being an admin with all my heart and soul, but I know that point and click isn’t always the quickest way to perform some admin tasks, especially when you need to do something quickly, repeatedly, and at scale. Which is why we need to borrow some Developer tools to be an awesome Admin, such as SFDX (a set of power tools) and VSCode (Visual Studio Code).
Updating one page layout is easy, but what happens if you want to update 15 page layouts? Or if you want to find out where an email template is referenced?
Even if you take into account the “where is this field used?” button (released in Spring ‘20) within the Salesforce setup menu, it’s still a slow way of finding and updating multiple settings, field names, page layouts, Flows and Apex references. If only there was an easier way to update this “metadata”.
This Admin’s guide to SFDX and VSCode comes in two parts. Part 1 (which you’re reading now) is an introduction to the tools by working through an example of adding custom fields to multiple page layouts that contain a specific field. What may sound like a headache now will be easily possible by the time you have finished reading. Look out for part 2, where I will take a deeper dive into VSCode, and another challenge!
*or sometimes I go by the title of “Consultant”, when I want to boost my salary for doing exactly the same job.
Discovering SFDX and VSCode
Huge thanks (and some sighs of relief) go to Christian “Szandor” Knapp MVP for introducing me to this free, open source, tool that can help with this very situation.
What is VSCode? VSCode is the shorthand for Visual Studio Code. It’s a free and open source product from Microsoft, available on Mac, Windows and Linux.
Developers use it all the time, but it’s not just for them. In 2017 Salesforce released an extension that connects it to your production, sandbox and scratch org environments.
Combine this with Salesforce’s SFDX (a set of power tools) and you have a way to get up and running very quickly; to speed up your configuration/development, testing and deployment cycle. Using a real-life case study, Christian and I will show you how!
The Challenge
Imagine you have been asked to do the following: Add two custom fields under the Amount field on all the fifteen* Opportunity Page Layouts that contain the Amount field.
*yes, it’s silly, but if you have a large org it happens.
Just for reference, the field names that we will be adding are “SalesforceBen Offer” and “Time Sensitive”.
There are a few steps, but once you’ve done it once, it will feel easy and intuitive the next time.
Time to complete the challenge: 30-60 minutes the first time, less than 5 minutes on subsequent runs!
Preparing the Ground
We’re keeping this short and simple. If you want lots more detail then you can delve into the “Set Up Salesforce DX” module on Trailhead.
The Install
Step 1: Ensure the fields you want to add to the page layout are already created in Custom Fields (it saves lots of hassle later on).
So, if you’re going to work through this example and follow it step by step, open up a Developer Org or sandbox and create the following two fields in Opportunity:
- SalesforceBen Offer (Field Name: SalesforceBen_Offer__c. Type: Checkbox.)
- Time Sensitive (Field Name: Time_Sensitive__c. Type: Checkbox.)
You can also use a Trailhead playground but you then need to work out your username and login details for that org, for use later on.
Step 2: Next you need to install “Salesforce CLI”. Accept the default options.
Tip: If you get an Apple security warning, follow the steps in this article.
Step 3: Download and install the latest version of VSCode for your operating system. This takes a short while, depending on your computer speed – perhaps as many as five minutes. It installs many things under the hood and there’s no useful progress bar. Again, accept the default installation options.
Tip: Once VSCode is installed, you may get warnings about Java (e.g. “an unsupported version was detected”). You can ignore these warnings as, for purposes of this walkthrough, we won’t be needing any Java features.
Step 4: Install the Salesforce Extension Pack. To do this go into VSCode and click on the “Extensions” icon on the left hand side (see white highlighted area on screenshot, below), searching in the Marketplace for “Salesforce Extension Pack” and clicking “Install”.
Step 5: As with many things VSCode, the installation routine could be described as “low key” (see white highlighted area on screenshot, below). After a minute or two it will have finished installing.
Tip: If you get prompted you can ignore the Recommended Extensions.
Step 6: Close and reopen VSCode so that the installation process is fully completed (it won’t prompt you to do this).
Intermission #1
An important concept to get used to in VSCode is that quite a lot of it is keyboard driven. It’s recommended that you get used to the keyboard shortcuts rather than clicking around.
There’s two main keyboard shortcuts
- For any commands: Ctrl Shift P
- For searching within the metadata (that’s the fields, Flow stuff etc): Ctrl P
p.s. Don’t ask me why they use Ctrl P. Apparently they don’t want you to do any printing.
Tip: If using a Mac, use “Cmd” instead of “Ctrl” throughout this guide.
Saving the Project
A Project is the collection of all the settings you need to get up and running. They can vary from time to time, which is why you can have multiple Projects. For our purposes we need just one.
Step 7: Creating your Project
Tip: The Project is where the details of your Salesforce org are stored. When VSCode loads it will then reopen your most recent Project automatically.
Hit Ctrl Shift P and type: dx
Your screen should look like this:
Step 8: Select “SFDX: Create Project with Manifest” (you can ignore the other options)
Step 9: Select “Standard” when prompted; then type in the name of the Project (e.g. “SandboxFull-UniversalContainers”)
Tip: A recommended naming convention is OrgType-OrgName (or “OrgName-OrgType” if you’re working with multiple orgs), based on whether it’s a production system, sandbox and the name of the organisation.
Step 10: You’ll then be asked which folder to save it in. On PCs, VSCode does not like “symbolic” folders (such as “Desktop”), so you should save it to a full path, e.g. C:UsersNameDropboxVSCode (see screenshot below if you’re just used to clicking on “Desktop” or other virtual links when selecting folders, because VS Code won’t react kindly!)
Step 11: This is optional, but if you click on the File Explorer icon on the top left, you should get something like this appearing…
Connecting to a Salesforce Org
Step 12: Hit Ctrl Shift P and type: dx
Step 13: Type or select: SFDX: Authorize an Org (in fact typing “Auth” into the search box would do)
Step 14: Select the appropriate Salesforce instance. As it’s your first time, we really hope it’s a sandbox!
Tip! You can also type sa to filter the list (if you do want to choose a sandbox).
Step 15: Enter the name of your Project again (e.g. SandboxFull-UniversalContainers; usually the same as in Step 9) and hit enter.
Step 16: A seemingly normal browser window will open with the Salesforce login screen. You just need to pop in your login details and allow “Salesforce CLI” the access, when prompted.
Step 17: You can then close the browser. You will then see the name of the org displayed in the bottom left corner of VSCode (see screenshot just below).
Getting your Data (the Layouts)
n.b. In this case we’ll be “pulling” page layouts from Salesforce, as it’s those we want to update.
Step 18: Click the Salesforce Cloud on the Icon Bar on your left (n.b. if reopening VSCode it only appears once all plugins are loaded).
Tip: This will open up a list of all the possible available metadata in your org.
Step 19: Select “Layouts” and then press the cloud/download button; you will see a “Retrieve source from Org” popup in the bottom right hand corner of the screen. You need to wait until this is finished before proceeding to the next step – there will be a box saying “SFDX: Retrieve Source from Org successfully ran” in the bottom right hand corner.
Tip: In most side windows in VS Code you can type a search term straight into it, and it will highlight or filter results. Try typing “layout” to see what happens.
Step 20: Now press Ctrl P (not Ctrl Shift P) and type “Opportunity” to see your layout (navigating down and clicking on the name in the left hand column won’t have the same result). Single click to enter your chosen layout and we’re nearly done!
Tip: If you don’t see anything, it’s because you skipped pressing the cloud/download button in the previous step. Just seeing lots of entries listed isn’t the same thing as downloading them.
See the screenshot, just below, for an example of what the results should look like:
Editing your Data
Good news! This part is actually quite fast, you’re about 2 minutes away from completing the entire task.
Step 21: Press Ctrl F to search the current layout/file for “Amount” (since that’s the example we’re using).
We’re now going to copy the existing details into memory, make a copy, and adjust them slightly to fulfill our mission. It’s very much like basic HTML, for good reason.
Step 22: For “Amount”, select the adjacent lines, from <layoutItems> to </layoutItems> and copy them into memory (e.g. Ctrl C).
These four lines
- <layoutItems>
- <behaviour>
- <field>
- </layoutItems>
are the information that Salesforce uses to display this field on the layout screen correctly.
Step 23: Press Ctrl Shift H (global find and replace; Ctrl H will do the same, but just within that page layout) and a new panel appears on the left, which we’ll come back to in a moment.
Intermission #2
Let’s explain what we’re about to do next, because it’s quite clever!
The task was to add two new fields below an existing field. We’re going to find the existing field (the original), and copy it twice so we have all the formatting correct (copy #1 and copy #2), which we can then update with the correct field names. In total there’ll be 3 sets (original + copy #1 + copy #2), because otherwise when we do a find and replace, we’ll lose the original text if we’re not careful!
Step 24: Press Ctrl N to get a new window to appear (File | New also works), then paste three times (so we have the original, and copies #1 and #2), e.g. using Ctrl V.
Step 25: Here you leave the original entry as it is, but then you change the copy #1 to the API name of the first new field you have created and want to insert onto the page, and the copy #2 to the API name of the second new field you are inserting.
It will look like the next screen shot…
Step 26: Go to the “Search” on the left. Paste the original text (for the first field) the “Search” box, and everything from the right hand side of the screen in the “Replace” box (as per the Intermission above). See screenshot below for what it should look like.
Tip: You can resize screen elements by finding the almost invisible section divider and dragging it left or right.
Step 27: Press “Replace all” – the weird button in the smaller circle, in the screenshot above; a warning comes up which you can accept/confirm.
Step 28: Check your changes! You can click on the File Explorer icon (see next screenshot) and navigate to the relevant page layouts to check that they were updated as you intended. At this point, if you’re unhappy with them you can undo them (this is much less the case later on).
Saving Changes
Step 29: Click on the File Explorer icon (“1” on the screenshot below), navigate to “force-app” (2), then “layouts” (3), right mouse click and then select “SFDX: Deploy Source to Org” (4).
Tip: If you get an error message in the bottom right hand corner, perhaps something like “Parent entity failed to deploy”, this is probably because you have Social Account Sharing enabled in your org (this is common in Developer orgs). Simply right mouse click on the following two page layouts and delete them, then pop back to Step 29 again. You won’t lose any data; this just stops those two pages trying to copy themselves back to your org.
- SocialPersona-Social Persona Layout.layout-meta.xml
- SocialPost-Social Post Layout.layout-meta.meta.xml
Step 30: After a while you will get a “Success” message in the bottom right hand corner.
Result: And your Opportunity should go from:
to…
Bonus
Want to find out where your email template is referenced, the example I gave in the introduction? If you look in “Email Alerts” you can see which Approval Processes use your email template but that doesn’t tell us which Apex Classes and Flows are using it.
I’ll be explaining how to do this in part 2, plus giving a little bit more background to VSCode.
Next Steps
Well, here’s the thing. Normally I put some next steps. This would be for admins to learn more about the product, but there’s a dearth of accessible information. Plenty for those who are familiar with developer speak-though! Reckon you have something to add? Comment below with extra resources or reach out to the SalesforceBen team if you want to write a follow up article.
- Salesforce’s Extension Guide for VSCode
- Hands-on: Creating Lightning Web Components using Trailhead (which is all about VSCode)
- SFDX community on Discord
- Salesforce community on StackExchange (which is slightly more to the Developer end of the support spectrum)
- Trailhead: SFDX
Thanks
First and foremost to Christian “Szandor” Knapp MVP without whom this article wouldn’t have happened. For queries Szandor is happy for you to contact him on twitter or on the Ohana Slack.
Further credit to my proofreading, editorial and suggestions team/victims: Ana Kelly Campos, Anastasia Korzhikova, Ankit Taneja, Christine Marshall, Rob Cowell and Vignaesh Ram Amaranth.
Comments: