This is a terrible way to work. It leads to bad solutions and miscommunication.

You cannot find the flaws in the spec, and there are always flaws, if you cannot sanity check it yourself. You cannot know for sure your solution worked if you don’t know what the data means and how it is used.

The Importance of Understanding

When my wife and I attended the Polo match pictured above we tried to ask some of the regulars basic questions about what was happening. They responded to us using all the words of the sport, but not in a way we could understand. If they wanted to attract new fans to the sport, they needed to explain the game to us in words we understood. It got even worse when a horse got injured and no one really explained what was happening until the ambulance trailer pulled onto the field.

To do our best work we need to understand the end goal of our users. The most effective way I know to communicate clearly is to use the same language as my audience does when talking about their work. If you try to force them to use the terms and phrases you know best they will likely make mistakes that cause you problems.

We must meet our audiences where they are.

When I was a Drupal developer, I was creating web sites that were customized to a specific organization’s needs. When I was a Salesforce consultant and developer, I was tailoring the platform to handle the specific needs of those users. In my role inside a nonprofit energy company I am making sure our Salesforce org meets our needs.

What was common across all those roles is that I needed (and still need) to talk with my users and understand their needs and the work they need the tool to do for them.

Problems with Failure to Understand

When I was a web developer, often the spec I was working to support was a graphic design. The designers would create a very attractive design, the client would approve it, and I was told to go implement it. Drupal, of course, can be implemented many different ways. To create a good implementation I needed to understand the designer’s intent and why the client liked the design (beyond it being pretty). I would ask why images were placed where they were, not to challenge the design but to make sure I called them the right thing in the backend. Those names were important to the content editors to help them select the right image in the future.

Working with Salesforce brings the same challenges. To understand if a Flow is working right, or even worth building at all, I need to know what the user expects to happen and why. When organizing a page layout, I need to know which information is most important and what fields are related to group them sensibly.

A Quick Note About Ethics

A complete discussion of the ethics of technology is impossible here; it’s a whole field of thought within Philosophy. Still we all should care how our work impacts the world. If I create a tools that’s helping someone commit evil, I’m supporting that evil. There is a mountain of nuance and detail to be thought through.

Just because the topic is huge and complicated does not free us from the basic responsibility to care about it. When someone tells me they don’t care how the technology is used, they are implicitly announcing they are comfortable supporting outcomes they consider evil.

When Do I Know Enough?

Probably never.

Over the course of my career so far I have worked on projects that involved:

• International peace and conflict resolution efforts
• The US federal budget
• Private prisons
• Economic empowerment of women in Africa
• Lobbying at the federal and state levels
• The DNS system
• Youth empowerment in the US and other parts of the world
• Explaining Quakerism
• Phone system setup and operation
• Desktop computer and server hardware
• Web development
• Web site infrastructure
• Virtual machines
• Open source licenses
• Copyright (copyleft) and trademarks
• General nonprofit fundraising techniques and strategies
• Basic accounting practices
• The child welfare system in several US states
• Life guarding and water safety
• Natural disaster planning and response
• Rules for credit card processing and security
• Sales of kayaks, canoes, and other related products
• Advanced and basic marketing strategies
• Chemical coatings for packaging
• The US sales tax “system”
• The energy industry in California and generally around the US
• …and probably a bunch of other stuff I’m not thinking to include

While that might be a little more than is average in just over 25 years of professional life it’s probably not all that high for someone with a similar career track. If you’ve been working for a few years, think about all the different things you have had to work on – it’s a bigger list than you’ll expect.

All of that learning can be exhausting; I understand the temptation to say “I know enough, I don’t need to know more.” But if I want to keep getting chances to advance, I need to be ready to understand the next thing I need to know.

It helps to be curious.

What’s Happening

A lot of people have been talking about these updates across the community, so hopefully this isn’t news. Here’s a quick list of critical changes coming soon (the whole list is longer, see article above):

• Phishing-Resistant MFA Enforcement for Privileged Users, Including Admins: Production release starting July 1, 2026, staggered over approximately 30 days.
• MFA Enforcement for All Employee Users: Production release starting July 20, 2026 staggered over approximately 30 days
• Step-up Auth for Report Activities: Production release starting July 1, 2026, staggered over approximately 30 days

The biggest, most important one to track is Phishing Resistant MFA (PRMFA) Enforcement for Privileged Users. If you are a Salesforce admin, and do not prepare for this update,you risk getting locked out of the org.

What’s the lowest bar to keep things running?

All admins, even those who use SSO to login, should setup PRMFA inside of Salesforce. If everything else fails, at least you’ll still be able to get in.

Salesforce recommends setting up passkey-based authentication.

1. Turn on support for Phishing Resistant MFA:
   1. In your org go to Setup.
   2. Use the Quick Find box to find and select Identity Verification.
   3. Select Let users verify their identity with a built-in authenticator such as Touch ID or Windows Hello and Let users verify their identity with a physical security key (U2F or WebAuthn)
   4. Save the change.

      

2. Register your build-in authenticator (or passkey through something like 1Password).
   1. Go to your personal settings.
   2. Select Advanced User Details from Personal Information menu (on the left)
   3. Click the add button the Built-In Authenticators section (most of the way down the page)

      

   4. Will likely be prompted to verify your identity through an emailed code.
   5. At the prompt from Salesforce, click Register.
   6. You should then be prompted by the browser, and maybe your cloud-based password manager, to complete the process. This should be your last step.

How do I setup a second device?

This is harder to figure out than it feels like it should be. Option one, use a cloud-based solution (like 1Password or LastPass) to managed your passkey. Option two, use your phone to setup your PRMFA instead of the build-in for your laptop.

1. Back on your Advanced User Detail screen click the register link for Security Key(U2F or WebAuthn) in the user detail section.
2. Like with your build-in it should trigger an identity verification. This could be either an emailed code or your existing MFA.
3. This should give you an option to scan a QR for a security key on a phone. Follow that process.
4. Now when you login from a new device you should be able to use that phone instead of your original passkey.
   1. After entering username and password, Click “Use a Different Verification Method” link at the bottom of the page.
   2. Select the option to “Use Security Key”
   3. Select Scan QR Code, and scan with the phone you used for setup.
   4. Approve the request.

Support/My IT Team said I was fine

Hopefully they were right. A lot of IT folks, and Salesforce support, have been giving out the wrong answers. There is a lot of confusion out there, so please be extra cautious.

For step-up authentication you’ll need an MFA registered with Salesforce – they cannot trigger an MFA from your SSO provider. Basically, so the above steps are really close to the minimum bar you need for that too.

Go do it right now!

What else should I do?

• If you aren’t using a cloud-based password manager (like LastPass or 1Password), I strongly recommend setting up more than one device. This is particularly true for solo admins. Otherwise you risk getting locked out if your primary device fails or is stolen.
• Record you OrgId someplace. If you ever do get locked out, it’ll be easier to get a support ticket going if you have your OrgId (also for some reason Salesforce thinks we all do this, so might as well).
• Export a report, and see how the new step-up authentication system works. Document that, and tell your users.

When will it hit my org?

I don’t know.
I don’t know how to check.
Sorry.

There are some folks, including me, pressuring to get more details on this released to admins ASAP.

What I do know is that Salesforce always pushes updates in batches. They are not going to roll it every org on July 1st – very few will get it the first day. A few orgs will go first. Salesforce will wait a few days, then do another batch. This is how they always release updates. Chances are, you have a few days.

That said, don’t wait go setup PRMFA right now! For those who have a holiday weekend coming, don’t spend the weekend worrying, just get this done!

I need more time!!

Ask for it.

Salesforce is issuing 90-day extensions to customers who ask. If you need more time, open a support ticket and tell them. Then contact you AE and give them the case number so they can make sure it gets done.

Since last fall I’ve been working with Salesforce’s Kelly Hamilton to review Trailhead content for accessibility. Our goal is to make sure the content goes beyond just passing formal WCAG requirements. We are trying to make sure it’s actually useful to the largest audience possible.

To help broaden that effort, and help the Salesforce nonprofit community grow comfortable with accessibility testing, we are creating this new Salesforce Commons project for this summer’s virtual sprint. Hopefully it will grow into a sustainable project.

What does the project do?

I gave the sprint organizers this description:

We’re helping ensure Trailhead, and other content important to our community, is accessible to all members of our community. Building on efforts started during the Denver Sprint in 2025 we will be helping community members understand how to test for accessibility by auditing Trailhead content (and any other content we can influence that the group thinks is important to the community). No web accessibility experience required (but greatly appreciated). We will provide resources ahead of time, training during the sprint, and places for you to get started giving feedback directly to the trailhead team! We will also be looking for ideas about where the community thinks this project should go as we get established.

We needed something to get ourselves started, but nothing is cast in stone. Once we have a team gathered, we can discuss our future as a group. The description, name, and goals will all be subject to future discussions.

Who should sign up?

I hope anyone attending the sprint in August will consider joining us. No prior experience testing accessibility is required. For people new to accessibility testing we will provide materials ahead of time, and some training about what to look for and how to report it. If you have experience testing accessibility of web sites we’d love to have you join us.

If you use assistive technology in your daily life we are particularly interested in your engagement. I know full well the best people to engage in these efforts are the people who are let down when they are not done right.

What you can expect

As a participant in a new project you can expect to have a lot of influence over happens. Kelly and I worked out a process to do reviews and submit feedback for Trailhead content that we’ll be adapting to work for the sprint. We also want to have some discussion about effective standards to encourage for community related content.

Basically, we have a starting point, but we need more engagement to make the project successful.

What content will we review

We will have suggestions to help people get started. Those will include at least some trailhead modules and some community project documentation.

Our goal is to review any content that we can influence which is important to the Salesforce nonprofit community. We know that includes trailhead. I expect that means community documentation for other sprint projects (I’ve put out a call to other project leaders for content they want reviewed).

We hope people will bring their own ideas as well. The only boundary will be content we can actually influence so everyone’s time is well spent.

Some resources to get you started

We still need to get a list of resources together before the sprint, but here are some to get started with:

• Accessible Salesforce Customizations: Inspired by discussion at the Denver Sprint, Kelly made this one happen in what felt like record time. There’s a lot in there and well worth any administrator’s time.
• Get Started with Web Accessibility : A useful trail of general accessibility guidance.
• Stanford’s Guide to Alt Texts: Good image alt-texts are hard for a lot of people. I’ve had Stanford’s guide offered to me several times when seeking advice.
• Accessibility Best Practices for Your Project: A guide for open source projects to help ensure they are usable by as many people as possible.
• Official Fundamentals Overview: This is the introduction to accessibility from the folks that maintain the standards.

What happens after the sprint?

That’ll be up to the group that joins us. We have ideas but we want to hear from the community. So feel free to come with your suggestions about the directions we should take this effort in the future.

If you have questions and want to reach me ahead of time contact me through LinkedIn or the Trailblazer Community.

I spent a little more than ten years as a client before I became a consultant. I spent just a bit longer as a consultant before becoming a client again. There are things I’ve learned in each role that help me do the other better. To ensure a mutually beneficial engagement it is helpful to understand the perspective of the other team.

Why is understand both sides useful?

The goals of a consultant and a client organization are misaligned. That doesn’t mean you can’t do great things together, but if you don’t understand the goals of your partner you are likely to step on each other’s toes.

The goals of clients

Client looks to consultants for one of two primary reasons:

• Add to team capacity
• Solve a problem

We either need to complete a project that our team does not have the time to tackle, or we need expertise it does not make sense for us to keep on staff. Sometimes we’re looking to reduce costs by having a group of part time people fill the roles of a smaller number of fulltime team members.

I like to have my team’s staffing level sufficient to complete all day-to-day tasks and to bring in outside help to take on special projects. Other people like to have consultants around consistently to provide the outside perspective and the diverse expertise that consultants bring. Both of those strategies are foundationally aimed at those two needs.

A smart client wants to spend the money needed to be successful, but not more. We want the most value for our money we can possibly get.

The goals of consultants

Consultants have a different pair of primary goals:

• Record billable hours and/or ensure profit margin
• Have a happy client who refers more business

Some consultants will protest that they have the goal to solves client’s problems through good work. My perspective is those are way to achieve those two goals. Some clients are happy when you do good work (but not all). All clients are paying to have a problem solved (see above).

Profit motive isn’t evil or wrong – even when supporting nonprofits and other socially beneficial institutions (having spent much of my career in nonprofits, we think about this a lot). Consultants need to make money to stay afloat. A consulting firm has people to pay, overhead to manage, and founders/investors to reward. Independent consultants need to eat, pay their mortgage, and so on. The larger the firm, the more pressure there is for larger profit margins.

To get new clients, consultants need “referable” clients. That means having clients who are so happy with the work done they will serve as a reference. I wish that always meant creating the best solution possible. What it means in practice is building the solution that makes the client happy. As a consultant I gave clients my best advice, and when they disagreed and insisted on a different solution, we build that instead. If they ran out of money along the way we still tried to keep them happy, even if we had the duct tape the last bits.

In the end, consultants build what clients pay for, and that’s not always the best solution.

Finding the balance

With consultants trying to make the most money they can, and clients trying to get a successful solution for the least money, there is an inherent tension in the system. Still, there is a balance to be had, where everyone wins, and great things happen. The trick is to make it a healthy tension that forces everyone to be better. Finding that balance doesn’t require that everyone involved has spent time on the other side the relationships, but it certainly helps.

When you understand the needs and goals of the other side of the relationship you can adjust your approach to make sure everyone is aligned to win.

Lessons to take from being a client

One of the things I learned along the way was that a lot of the advice given to new consultants contradicts what I knew from being a client. Spending time as a client gives you insights into how to best serve customers that many pure consultants don’t understand.

Be the consultant you want to hire

When you work at an organization that hires consultants you see different approaches taken by different firms. You learn your preferences about what you like and don’t like in a consulting partner. While no one style is the best fit for everyone it’s unlikely that you are so unique that there aren’t lots of other people who like that same style.

Default to the Golden Rule: treat clients the way you wanted to be treated by consultants.

You can’t always do that 100% of the way – sure as a client I want everything free, but that’s not reasonable. But by approaching the client the way I would have wanted to be treated consistently went a long way to helping smooth over challenges.

Start there, and over time you’ll learn to adapt your approach when specific clients prefer a different style.

Be honest about your limitations

Do. Not. Lie. To. Me.

Do not guess without admitting it. If I wanted made up answers, I’d ask an AI.

Consultants always want to appear to be the expert in the room, and so they feel they have to answer every question. Too often that leads to consultants making up answers to show how smart they are; clients will catch you eventually.

One of the best ways to build trust with a client is admit when you don’t know the answer to a question, and then come back later with the answer. Do not say “I don’t know” and leave it there, go for some form of “I will need to go look that up/ask around/figure that out.”

Great consultants find solutions, they don’t always have the answer right away. We can wait for you to do some research when we stump you. That is a lot easier to explain than when you have to walk back having given us the wrong answer.

Focus on what the client needs to succeed

Clients should always have an outcome in mind that supports their work. Consultants are focused on the solution they are building. When everything is going well, that solution is what the client needs to support their work. If those stop being the same thing you have a very big problem.

Both clients and consultants can easily forget to consistently re-check that alignment. As a client and as a consultant I’ve been part of projects where the delivered solution didn’t solve the actual problem – even when it fulfilled the spec and SOW. These moments frequently lead to energetic discussions that often become loud. No one wins when that happens.

Regularly check with the client, and with yourself, to see if the solution will solve the client’s problem. When you see misalignment raise your hand early and often.

Lessons to take from being a consultant

Of course consultants know and learn stuff that isn’t obvious to any given client. Consultants bring wider experiences, different perspectives, and a different energy to a project. That is part of what makes them valuable. Clients should hire a consultant they trust, and listen to their consultant. Think hard before deciding you know better.

Always learn new things, even if they aren’t important today

As a client we tend to learn deeply about the tools we use and our work. Consultants work on a lot of projects with a lot of clients. Along the way they use a lot tools, and see at lot of ideas. That creates a culture and need for constantly learning. Often they are learning about things that don’t seem useful right away.

The higher the role you have as a consultant, the more you are expected to be at least conversant about technology you haven’t used yet. You also need to be conversant about the work of your clients. That’s a lot of learning.

I had good learning habits going in to being a consultant. They served me extremely well as a consultant, and are serving me well again as a client.

The broad knowledge of a consultant is extremely useful and everyone benefits from more people knowing more stuff. Having that breadth of knowledge also helps when you do run into the places where you don’t know something. It gives you the confidence that you can go learn the next thing you need to know quickly (see Be honest about your limitations above).

Know how to work to a deadline

Consultants are always working within time and budget constraints – usually tight ones. That forces them to learn to be efficient. Sometimes that means they cut corners (see next section) usually that just means they move fast. Good consultants have a high degree of dexterity with their tools, they learn to line up their work to knock out tasks, and they learn what’s needed and what’s just nice to have.

New consultants often feel like they are sprinting all the time, but experienced consultants learn to balance the sprints with jogging. The pace is nearly always high (at least if sales are going well), but it still ebbs and flows. Consultants learn to hit their deadlines, but rarely are ready to deliver early.

As a consultant if a deadline was far in the future it gave me time to do careful work, balance other clients, do research, or just time off. Far off deadlines gave me time to recover from sprints and make sure I had the energy for high intensity moment. That intensity is important to driving client success – but hitting the deadline is more important.

Hitting deadlines is also important for a client to do. Consultants need you to hit your deadlines so they can balance their workload to hit their deadlines. They may also have penalties embedded in the contract (see Read the Contract below) that could cost you time or money over the course of your project.

Perfect is the enemy of the good

Okay, this isn’t something just consultants know, but it is something consultants often learn to deal with the hard way.

Consultants need a solution that meets the requirements, fits in the budget, and pleases the client. They are not there to create a solution that is perfect, or even elegant. In any project there is a balance to be had between carefully polished, and just barely good enough to be successful. Consultants learn to thread that needle. As long as the project is successful that’s a good thing.

I have seen developers spend hours, days, even months, trying to build to the perfect level of abstraction, with the perfect naming conventions, and drive for the perfect code, only to have the project fail because it’s overdue, over budget, and was outmoded by someone who worked twice as fast.

Yes, we all want good solutions to our technical problems. But no solution is going to be perfect. You should aim for perfection and know you are going to miss. When you learn to accept that, it’ll be easier to move forward and be successful.

Things everyone should know regardless of role

For all there are things that each side brings something to the table, there are habits that everyone should have as part of their role. There are lessons I learned, or was taught, in both roles that are super important.

Read, and understand, the contract

Everyone on a project benefits from having working knowledge of the contract. In the end, when push comes to shove, all that matters is the words on the paper. You can usually avoid the pushing and shoving by understanding what everyone agreed to up front.

The biggest issues I’ve seen on consulting projects was when one side, or the other, didn’t pay attention to the agreement.

Sometimes this happens because everyone is working in good faith, and no one remembers to amend the agreement when needs changed. In those cases you can often recover by continuing to work with each other in good faith.

Sometimes this happens when someone signed a contract they didn’t read and understand. I once had a client yell at me because I added a paragraph to the contract outlining the resources they were responsible for providing and he didn’t read it before we asked him for those resources (these clauses are really standard, and the one I wrote was extremely simple).

If everyone on the team takes the time to read and understand the contract it greatly reduces friction. Clients who understand the bounds and assumptions in a contract are able to get the most from their vendor without creating tension. Consultants who track the required deliverables of the contract don’t frustrate clients by skipping required elements. It doesn’t take long. The more you read them the faster we’ll be at reading the next one.

Once you have read a bunch of contracts you’ll know what’s normal and what’s not. At this point, if I don’t understand the contract language I see that as a red flag even before I send it out for legal review.

Discuss problems and be solution oriented

Projects go best when everyone is open about what problems exist and then pivots to solving them.

Technology should be deployed to solve problems. That means starting by talking about problems. Being problem focused at the start makes it easy to be hung up talking only about those problems, or about new problems that come up while solving the first problem.

Having a good problem statement is critical to creating good solutions. But once you have the problem outlined you need to focus on solving it. Yes, raise problems, concerns, challenges, threats, weaknesses, etc. Talk openly about all those things. Then make the pivot into problem solving mode once the issue is well understood.

The best projects come together when when everyone collaborates on finding the best solutions to the problems at hand.

Quality matters

Everyone needs to focus on the quality of the outcome. Consultants, for all their fast moving creation of imperfect solutions, must still do good work. Clients should hold their vendors, and themselves, to high standards.

Every message that goes back and forth is a chance for misunderstand that gets in the way. Every input into discovery and every deliverable is a chance for gaps to form. If anyone takes their eye off the ball mistakes can happen and the solution no longer threads the quality needle correctly.

Mistakes will happen, and everyone will have to help course correct. But the higher the quality of the work done before the mistake, the faster it will be to recover and better and overall solution the client will get.

The Grass is Greener

One final note on the way out. If you are trying to decide between being a consultant or being a client, I recommend the switch – whichever you are today try being the other if you haven’t yet. Not everyone loves both roles, and different roles have been right for me at different times.

As a client I loved what I did. We were helping make the world better. I was pushing things forward and helping the organizations succeed. But eventually the things they needed me to learn, and the pace I wanted to grow, weren’t aligned to the organization’s needs.

I’d been there a decade, I left on great terms, but it was time to go.

When I first became a consultant it was exciting. I got to work on a variety of projects, with more technologies than any one organization generally needs. The pace was higher and I was frequently pushing myself in new directions. Consulting gave me insights into how different organizations worked (for both better and worse). And I made more money.

Interesting work, exciting environment, more money, great!

As a consultant I spent less time in positions, the billable grind was exhausting, I missed being focused. When I returned to the client side, I got to focus again. I have one org to worry about, one set of organizational politics to understand, and so on. I get to learn the work of the organization deeply again and really understand the market we serve. In my case I, again, got more money – but that was at least partially luck as much as anything; consultants are often paid better than in-house team members.

Focused work, no billable hours target, calmer work environment, great!

Each really does have it’s advantages. But so does understanding what it’s like to be the person on the other side the relationship. Try them both, learn from both, decide what’s the best fit for you.

This is not a technical article, about how to implement accessible designs. It’s about the thought process content creators should go through to make their content useful to as many people as possible. For those of us who don’t use assistive technologies on a regular basis, creating accessible content can be an abstract concept. We get tempted to focus on passing the scan, avoiding law suits, and generally treating accessibility as a checkbox. It is easy to forget that making your content accessible is about making it useful to people.

I’m not the greatest expert in the world on accessibility. But when I recently noticed a gap in Salesforce’s training materials it drew me back into thinking about the details. Instead of focusing on the strict rules of compliance I have been focused on making sure the content is actually useful.

Accessibility Gaps

During a discussion at the Open Source Commons Sprint in Denver this past November several of us got into a discussion about why so few people in the room knew how to make sure their screen flows and other custom elements were built to be accessible. The room was full of people who know the platform extremely well; if they don’t know how to do this then most Salesforce administrators don’t know.

When I am in a room of experts who have a common point of confusion, I assume there is a problem to solve. The exact problem isn’t always immediately clear, but the existence of one is. If people with 20 years of experience on the platform, which is rightly known for taking accessibility seriously, don’t know how to keep it accessible: there is a problem.

Salesforce’s Trailhead site provides good content about accessibility. So how then does the community not know how to put this information to work?

Closing the Gap

Fortunately, one of the people in the room not only creates that material, but is responsible for helping ensure the content is high quality. Kelly Hamilton immediately took it upon herself to review the Trailhead content on accessibility. Kelly found, and started to address, some specific weaknesses in the existing material but the immediately obvious gaps were small. They didn’t explain the lack of understanding in a room of experts.

I wasn’t convinced the gap was in the material directly about accessibility. I offered Kelly the next challenge: does content that is not focused on accessibility encourage accessible practices? She held my feet to the fire and challenged me to help check. That answer turns out to be far more mixed.

The core issue I am finding is not specific to Salesforce. Trailhead’s content, like many other similar resources, is divided into content about accessibility and everything else. That means articles about how to create custom elements do not consistently encourage practices that ensure the platform stays accessible. Writers take unneeded short cuts to keep the content simple. The writers also often assume the people completing tasks are not using assistive technologies themselves. The description of how to complete the task technically meets accessibility standards, but there are details missing to complete the task for many people who need those standards to exist.

Instead of having best practices for creating accessible content be a background hum, the content builds in assumptions that unintentionally send a message that accessibility is an after thought.

A Quick Example

One of the articles I recently reviewed covers setting up VSCode for Salesforce. At the moment there is a screenshot at the top of the page that shows what VSCode looks like when providing code auto complete (I reported a number of issues with this unit so it may change in the future). The alt text reads “Visual Studio Code’s code completion in action.” While technically accurate, and it certainly meets formal standards, it is completely useless to a blind user wanting to learn to use VSCode with Salesforce.

The Trailhead unit is a training article for people getting to know these basic tools. It assumes the reader hasn’t even installed VSCode yet. Nothing about the article tells a blind user what to expect from auto complete. Heck, it doesn’t even acknowledge that one of the reasons to use VSCode is that it provides support for screen readers or where to get training on use that mode.

The implicit assumption is that the reader is sighted. Accessibility support is therefore provided as a kindness (or for legal compliance) to an audience that would not actually use this instruction. Nothing about this article directs that segment of the audience to content intended to help them succeed.

In my experience a great deal of material on the web about creating good content suffers from the same faults. The implicit assumption about the audience is that they have no relevant disabilities themselves. Meanwhile, articles that aren’t focused on accessibility frequently skip the details required to make the demonstrated technique meet accessibility standards.

Why Accessibility Gaps Matter in Training Docs

There are two groups of people to whom it matters that training materials be correct: people who need assistive technologies to work, and people who care about people who need those technologies to work. In an ideal world that means everyone.

For people who need screen readers and other assistive technologies, accessibility is much more than a checkbox. These technologies help keep people engaged in the world around us and able to productively contribute to our community.

Just to make the situation ever so much more so worse: we are all training AIs through everything we publish. When our content fails to encourage accessible techniques in everything we are training those machines that accessibility doesn’t matter. Doubt that? In November 2025 Microsoft published a set of test results that found that even the best tools only create passing content 30% of the time. Those LLMs were trained off the same material we use to train humans.

It matters to people; it matters to machines; it matter to people who trust machine.

It matters to everyone.

Leveraging Your Empathy

Content is for people – even if machines steal use it to create money content for others. Creating good content requires thinking about your audience and how they experience your content.

A mistake often embedded in efforts to create universal designs is that advocates will at times argue to create the same experience of all users. When possible, that’s great! But that’s rarely possible in practice. The experience will never be the same for the person relying on a screen reader to read an alt-text as it is for the person seeing the image. Don’t pretend you’re doing the impossible. That’s not being empathic to different perspectives, it is denying the realities of our world.

Empathic Alt-Texts

As one thought experiment let’s look at alt-text. They are the first thing most people are taught to worry about when creating accessible content. That training nearly always focuses on describing the image.

I am advocating for a different starting point. When writing alt-texts try to put yourself in the place of someone encountering that text. Consider what they need to know about the image in the context you selected. Think less about the image, and more about its purpose.

What meaning is it conveying to a sighted reader?

How can you ensure that meaning is conveyed to all audiences?

If the purpose of the image is to convey a feeling, try to convey that feeling. If it is meant to convey information, provide that information (or better yet put it in the caption for everyone).

Ask yourself what you would want to help yourself understand this content. Is the image there to provide a visual break in necessarily dense content? Okay, then make sure the alt-text gives the user a mental break as well. If the image is silly, tell a joke. You gave you sighted audience a reason to smile, give that to your blind users as well.

When I wrote the alt-text for the header image, I wanted to help make it clear why that image was part of this article. I tried to include not only some sense of the image content but also the emotional reasoning for selecting it. Hopefully for those who saw the image all that was clear right away but for everyone else I still wanted to provide that detail.

What This Doesn’t Cover

No one approach addresses all needs in all contexts. We cannot close every gap.

There are places where no matter how much you care, it’s really hard to create proper parallels. Descriptive audio is really hard to create and should be done by experts when possible. Creating teaching materials or tests where students need to struggle with a piece of art to find details and understand its meaning is even harder. That does not mean we don’t try.

We should do our best and strive to improve over time. If we pretend everyone can provide all the accommodations equally well – or that AI will magically free us from this challenge – we hold back the push for further improvements. Many universities are doing this right now when they tell their professors to handle all accessibility needs for online classes without providing the needed resources. Even worse, they often tell those professors to remove valuable content if the office staff don’t know how to make it accessible. Harming everyone is not the right way to make progress.

Do what you can. Admit when you cannot be as good as you would like. And use that admission to get better, push for more resources, and support technical improvements.

Helping Out

If you’re interested in helping me review Salesforce’s Trailhead content, or just find something that needs review and improvement, contact me through the Trailblazer Community, Ohana Slack, or LinkedIn.

Accessibility bugs can be reported directly through the Share Your Feedback button at the bottom right of each unit. I’m happy to help get attention of those issues if your alert me to what you encountered. If you think you found something more subtle, where it works in the technical sense but is done poorly, please reach out and I’ll help your feedback reach the right people.

For what it’s worth I also know this blog is less than perfect in this regard. I have been improving it when I notice issues, but please feel free to send me suggestions about what is causing the most pain so I can prioritize fixing it.

This time I wanted to work out how to create a buttons in a Salesforce Lightning Web Component that allow a user to manage the records.

There are two links that matter in lots of use cases:

1. The edit link for a specific record
2. The manage records link for custom metadata type to add or delete records

The link to a specific record is fairly easy. It’s just a simple row action and well supported. The manage records link on the other hand took a bit more research.

Custom Metadata Type

Obviously, the first thing you need is to create your custom metadata type. Exactly what you create isn’t important here, the one I was working with was the field list type from my email invalidation tool.

For the purposes of this discussion I will use Your_Metadata_Type__mdt as the placeholder name. Swap in whatever your actual metadata type is called.

The LWC

Next we create our LWC to help us manage the records. The common use case here is when you’re creating a settings page for a custom app or tool. Hopefully one day we’ll be able to make these settings pages, but for the foreseeable future they generally need to be a custom app, with a Lightning Record Page, populated with one or more LWCs. Putting all those pieces together is beyond the scope of this article – I am telling you because that is the context of my assumptions.

A basic metadata setting for the LWC should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>64.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__AppPage</target>
  </targets>
</LightningComponentBundle>

We will also need a basic HTML file for this LWC (obviously yours will probably have more elements – mine does):

<template>
  <lightning-card title="Metadata Configuration" icon-name="standard:custom_metadata_type">
    <div slot="actions">
      <lightning-button variant="brand" label="Manage" title="Manage Custom Metadata"
        onclick={handleManageRecords}>
      </lightning-button>
    </div>
    <div class="slds-m-around_medium">
      <template if:true={hasData}>
        <lightning-datatable key-field="Id" data={metadataRows} columns={columns} hide-checkbox-column="true"
          onrowaction={handleRowAction}>
        </lightning-datatable>
      </template>
    </div>
  </lightning-card>
</template>

In this example I put the manage button at the top and a simple lightning datatable which will hold one row per metadata record. The button has an onclick action that will call handleManageRecords in the LWC’s JavaScript controller. The rows will each have a row action block that triggers handleRowAction.

The JavaScript Controller

Things start to get more interesting when we get to the actual JavaScript. In fact most of the important work is here.

The JavaScript starts by loading the required modules. Three from Salesforce, and two from our custom Apex Controller (coming up next).

import { LightningElement, wire } from 'lwc';
import { NavigationMixin } from 'lightning/navigation';
import getMetaDataRecords from '@salesforce/apex/MyMetadataController.getMyMetadataRecords';
import getMetadataPrefix from '@salesforce/apex/MyMetadataController.getCustomMetadataObjectPrefix';

Datatables need to know what columns they are displaying – and it’s best to put those in a variable for easy maintenance:

const COLUMNS = [
  {
    label: 'Label',
    fieldName: 'Label',
    type: 'text',
    sortable: true
  },
  {
    label: 'Developer Name',
    fieldName: 'DeveloperName',
    type: 'text',
    sortable: true
  },
  // Plus whatever other fields you need.
]

To make the Edit links work for each row we need to extend the provide NavigationMixIn class we imported above.

export default class MyMetadataLWC extends NavigationMixin(LightningElement) {
  columns = COLUMNS;
  metadataRows = [];

  // This does the work of actually loading the Custom Metadata.
  @wire(getMyCustomMetadata)
  wiredMyCustomMetadata({ error, data }) {
    if (data) {
      // Convert map to list
      const recordList = [];
      const recordNames = Object.getOwnPropertyNames(data);
      for (let i = 0; i < recordNames.length; i++) {
        recordList.push(data[recordNames[i]]);
      }
      this.metadataRows = recordList;
    } else if (error) {
      this.metadataRows = [];
    }
  }

  // Simple helper method to make the templates a little more stable.
  get hasData() {
    return this.metadataRows && this.metadataRows.length > 0;
  }

  // The edit action defined here is the really important part for navigating
  // directly to the record you want to update.
  handleRowAction(event) {
    const actionName = event.detail.action.name;
    const row = event.detail.row;

    if (actionName === 'edit') {
      // Navigate to the record page for editing
      this[NavigationMixin.Navigate]({
        type: 'standard__recordPage',
        attributes: {
          recordId: row.Id,
          objectApiName: 'Your_Metadata_Type__mdt',
          actionName: 'edit'
        }
      });
    }
  }

  async handleManageRecords() {
    const metadataPrefix = await getMetadataPrefix();
    // Navigate to the Custom Metadata Type management page
    this[NavigationMixin.Navigate]({
      type: 'standard__webPage',
      // I'll explain this bit below.
      attributes: {
        url: '/lightning/setup/CustomMetadata/page?address=%2F' + metadataPrefix + '%3Fsetupid%3DCustomMetadata'
      }
    });
  }
}

Currently the NavigationMixIn only provides direct links to Custom Metadata Records, not the manage records page (or the create record form). For the edit links that’s just fine: we use the NavigationMixIn’s behaviors and off we go. But to get to the Manage Records page we need to create the link itself.

If you go to the page Manage Records page for your Custom Metadata type you’ll see the URL is in the form: /lightning/setup/CustomMetadata/page?address=%2Fm01%3Fsetupid%3DCustomMetadata

Salesforce knows which Custom Metadata Type you’re talking about from this bit: %2Fm01%3F

In URLs anything that starts with % should be followed by a two digit hex code. These are URL Encoded characters (w3Schools has a complete reference if you want it). %2F is / and %3F at the end is ?. Between them is the custom metadata type’s prefix, in this case m01. This value is Metadata Type and Org Specific: you cannot safely hard-code it. We have to get that from the describe of the type, and that means diving into Apex.

The Apex Controller

To bolt this all together we need two tiny pieces of Apex. The first method will give us the list of records to display, the second gives us that prefix we need for the URL.

public with sharing class MyMetadataController {
  // This gets a list of all the metadata records we plan to display. Pretty standard for LWCs.
  @AuraEnabled(cacheable=true)
  public static Map<String, Your_Metadata_Type__mdt> getMyMetadataRecords() {
    Map<String, Your_Metadata_Type__mdt> records = Your_Metadata_Type__mdt.getAll();
    return records;
  }

  // This provides us with the key prefix for the custom type – needed for the link.
  @AuraEnabled
  public static string getCustomMetadataObjectPrefix() {
    return Your_Metadata_Type__mdt.sobjecttype.getDescribe()
      .getKeyPrefix();
  }
}

Of course you’ll also need test coverage for these functions as well. Everything you need is kicking around in the working example.

Working Example

My working example is embedded in the Email Invalidation Tool I built a few months ago and am slowing improving.

• The complete LWC is here.
• The Apex Controller is here

This is supporting content for my talk at Dreamforce 2025. My talk references many of the resources listed here. This page also includes other content I hope people find useful.

Writing References

It’s good to have an understanding of what other people expect from us, what the rules of the road are, and how we can break those rules at times.

Elements of Style aka Strunk and White,

~ William Strunk & E. B. White: The premier guide to the constructs of formal written English. This is your driver’s ed manual: the rules other people expect us to follow, but not sufficient for all conditions and settings.

• World Cat
• Amazon
• Barns and Nobles

Eats, Shoots, and Leaves

~ Lynn Truss: An exploration of how to use the rules effectively. We can bend, twist, and even break formal rules to improve our writing.

• World Cat
• Amazon
• Barns and Nobles

Blah, Blah, Blah

~ Dan Roam: How to use images to fill the gaps our words leave behind.

• World Cat
• Amazon
• Barns and Nobles

Speaking References

Public speaking is hard for a lot of us. Having some suggestions about how to do it well can be part of helping us learn to power through.

The Art of Public Speaking

~ Dale Carnegie: The original, and classic, guide to good public speaking technique.

• World Cat
• Amazon
• Barns and Nobles

Speaking Memorably

~ Bill McGowan & Juliana Silva: A 2025 guide on good public speaking and modern presenting.

• World Cat
• Amazon
• Barns and Nobles

Other Material I Think is Worth Your Time

In addition to the published works above, I think these resources can be useful to a lot of people.

• Posts about writing for developers and technical consultants
• Some classic works in our field
  • The Mythical Man-Month
  • Soul of a New Machine
  • Just about anything on this list
• Listen to good podcasts
  • Hidden Brain
  • People I Mostly Admire
  • Freakonomics Radio
• Trailhead Modules
  • Soft Skills for Sales
  • Storytelling & Communication
  • Writing Style
  • Virtual Presentations

Practice Suggestions

What you do for practice doesn’t matter a great deal. What’s really important is that you do it and get feedback. Here are some things you might consider for practice:

• Short Stories or other fiction writing that you publish online, ebook, or print on demand
• Contribute project documentation to an open source project
• Essays for Medium, or other blogging platforms
• Participate in online writing challenges
• Create a YouTube (or similar) channel

Whatever you pick, you want to be in control of how often you create content, and then make sure you create content on a regular basis. If you aren’t in control, you might find yourself cut off from chances to practice.

I strongly suggest you don’t use AI during your practice. You need to do the work, even when it’s hard.

Closing Suggestions

Generally, I recommend being curious person. Push yourself to learn more. The more you spend time finding good information sources to learn from the more examples of good communications you’ll have for inspiration on how to get better.

The Problem: Salesforce Truncates Custom Metadata Text Fields

When loading Salesforce Custom Metadata records using the static methods getInstance() or getAll() long strings are truncated at 255 characters (I actually ran into it at 511, but the documentation says 255).

My Use Case, and Reproduction

One of the features I wanted to add to my email invalidation tool was auto-detection of email fields. That’s turned out to be a whole complicated process that I’m still finishing as of this post date. Part of the solution I am using is to create a custom metadata object to store a list of possible fields. For a variety of unimportant reasons I elected to store that information as a JSON string. So I created a long textarea field maxed out at 131,072 characters. Everything went fine at first: the process scans the objects and drops the results into the metadata record. When I looked at the records in the UI or after downloading to a file it looked just as I expected. But when I started to load the records again I got JSON parser errors because the value had been truncated to 511 characters (see note about about 255 vs 511).

Preventing Salesforce Custom Metadata Text Truncation

The answer is to use SOQL. I typically use the static methods when working with Custom Metadata to reduce the number of SOQL queries in my code – but in this case that doesn’t work. To reliably get all the data in long text fields you have to use SOQL.

This approach consistently gives you a truncated values:

Email_Invalidator_Cache__mdt cacheRecord = Email_Invalidator_Cache__mdt.getInstance(
  'Field_Scan'
);

But using a simple SOQL statement to load the same record works just fine:

Email_Invalidator_Cache__mdt cacheRecord = [
  SELECT QualifiedApiName, Cached_Value__c, SystemModstamp
  FROM Email_Invalidator_Cache__mdt
  WHERE DeveloperName = 'Field_Scan'
];

Ask Salesforce to Fix This

There is an idea open requesting a fix to this issue. Please up vote.

Special Thanks

Thank you to Robbie Duncan for helping me out on Ohana Slack with this one.

When I migrate data I often add .invalid to all the email fields in the org. More than once this saved my team from accidentally sending a large number of messages. Having a tool to do this easily in a sandbox has been on my todo list for a long time.

Why Invalidate Salesforce Emails

Salesforce automatically adds .invalid onto the end of email addresses of Users to avoid accidental sends from sandboxes. This is great when you have an experience cloud portal setup. Because Salesforce’s core platform is not an email marketing platform Contacts, Leads, and other objects with email fields are left unaltered. But lots of organizations use the core platform to drive a marketing platform. The use add-ons and data syncs, or they use the org to send transactional email directly from Salesforce. When the org is the tool that initiates the send, there is a risk that a sandbox with real data can send invalid messages. I’ve seen sandboxes send a lot of messages during testing of new features or when an automation was left switched on that should have been disabled.

Most Salesforce consultants I know have stories about times when an org sent unwanted email messages to a client’s contacts. Those events are embarrassing at best. At worst they can expose you to financial or legal liability.

Often these events happen when someone makes a simple error with a full copy sandbox, or an org with migrated data under review. The story outline generally is that while testing an automation, or a scheduled process, a team member sets Salesforce to send messages. They forget to disable email again, or they don’t think about a scheduled automation set to run at 2 AM. Minutes or hours later that sandbox triggers dozens, hundreds, even thousands of emails.

Can’t I Just Disable Email in Salesforce?

You can, and should, disable email deliverability in most sandboxes most of the time. But in my experience that’s not sufficient all of the time.

That setting is good, but less than perfect. Sometimes you need deliverability switched on to test features or deploy changes. Sometimes you use a 3rd party email system that ignores that setting. By actually breaking every email address nothing can slip through.

How My Salesforce Email Invalidator Works

This tool uses a series of custom metadata records to determine which objects and fields have emails you want to invalidate (it comes with a sample record to invalidate the Email field on Contact). When the batch process runs – either from the provided app or post sandbox copy – it will add .invalid onto the end of any existing data in the field. It does not check to see if the value is actually an email, but it does ensure .invalid is only added once and ignores blank values.

The tool provides an app that gives you a place to see and update the exiting field list, a button to initiate the process, and allows you to replace the .invalid text with a different string. You can also have it automatically run after a sandbox completes its process by entering InvalidateEmailSandboxPostCopy as the Apex class to run when creating the sandbox. I created the tool to be metadata driven so that the setup carries down from the production org into new sandboxes.

Security

Please be careful when installing and using my email invalidator. It is designed to break data – that’s the whole point. I have not put it through Salesforce security review, and I don’t plan to bother. I’m not even sure they would approve a tool designed to break data. It does have a permission set that should be giving out on a very restricted basis to highly trusted users – ideally don’t assign it to anyone in production including yourself.

I am releasing the invalidator tool as an open source project. You are free to review the code and validate that it does what I’ve described. I will do my best to answer any questions you post to the issue queue.

Installation

The current setup is just a collection of loose metadata in a repo. Until I get around to packaging it you’ll want someone who is comfortable with git and sf cli to support installation. You should clone the repo to your local machine and push all the metadata into your org with sf cli’s sf project deploy start command.

Of course please install in a sandbox first and test it out there before putting a copy in production. To make it easy to use over time it will need to be in production.

Feedback and Suggestions

I am open to, and interested in, feedback. Currently the tool is a very early alpha quality version. It works, but hasn’t been tested in a lot of use cases. In the project issue queue you can offer feedback, report bugs, or make suggestions. I’d also enjoy getting code contributions as well.

I changed jobs recently. In the process of leaving my old job I was asked a lot of questions about how I’ve built up a wide-array of skills and knowledge. During those discussions I tried to give the best advice I could on the fly to a question I was asked cold. Now I’ll try to assemble a set of more carefully considered advice.

These suggestions are more or less in the reverse direction of importance: the more you read the more valuable I think the suggestion is.

Directed Learning (Job Related Learning)

By “Directed Learning” I mean learning that is supported or encouraged by your employer. This can be certification preparation, employer provided trainings, or research into an emerging technology, even building tools that directly support your work. Into this category goes anything that can lead to higher pay, advancement, or even just keeping your current job.

Some employers are really good about this. Over time I’ve been sent to trainings, had course fees covered, and other direct support. The job I just left even provided financial incentives (cash) for us to acquire select certifications of value to the company. Other employers have published a list of what they wanted people to have – without direct incentive. But most often I’ve had to figure this out on my own which is not ideal of anyone involved.

This type of growth has a few benefits. First, it can help with your reputation (and hopefully pay) with your employer: “Oh, Aaron is certified on [interesting product] we can assign him to [high profile project].” Second, it helps make sure you are growing in alignment with your employer’s needs. That can be helpful when they are forced to make cuts: “We should keep Aaron, he’s the only team member with [rare certification] and Salesforce wants us to have that on the team.”

In my life as a Drupal developer this looked like creating modules for internal use, or learning new techniques. But it boils down to the same thing: learning stuff your employer needs you to know.

The downside of only learning what your employer needs is that you miss chances to grow beyond their needs. That limits your future mobility – your best chances will be for another job like you have today. If you want a better job or a job doing something different, you need skills your employers doesn’t think they care about.

Personal Learning: Side Projects and Other Self-Directed Research

To learn things your employer does not care about you will likely need to put in your own time. You should focus this kind of learning on something that interests you – make it fun. My experience is that this kind of learning goes best with side projects.

Side projects allow us chances to test and practice the ideas we’re learning. I use them to learn programming languages, frameworks, and techniques that interest me but not directly useful to my work. Sometimes they come around to being useful in my work. Sometimes they just give me a chance to learn interesting things. My Github account is full of examples.

An early professional mentor told me to learn a new programming language every year, and so over time I taught myself a bunch of programming languages. These days I generalize that advice a bit and try to learn a new platform, framework, or technique every year – and sometimes a new language. That meant when Salesforce rolled out LWCs to replace Aura Components, I was ready to learn them quickly. It also means when a friend started to talk about using Wails I could related from my experiences using Electron. My experience creating a project estimation tool helps me discuss estimation techniques with project teams.

This blog is an example of a side project. Every post gives me practice at writing. To keep posts accurate I include research as part of my writing process. That research teaches me things I wouldn’t learn otherwise. The act of writing forces me to clarify my thinking on topics. All of that is useful to me and helps me be better at my work. I also know this blog as been read by colleagues, employers, and potential employers all of whom are useful audiences when getting new work.

When I give talks about communication skills I tell people what they do for practice doesn’t matter: what matters is that they practice. Same is true for side projects. What project you tackle isn’t important. What is important is that you do something that forces you to learn new things.

Side projects help us look at our work from different angles, and therefore test our limits and grow.

Develop Learning Routines

It’s easy to get lazy or to put your professional development aside – it feels like there will be time later. So you should create a routine that works in your life.

I like to have a routine to make sure I’m steadily doing some form of professional development – it’s a marathon not a sprint. For me that generally looks like job-related learning for about an hour after my formal work day and working on a side project on weekends. Attaching your learning to your work day allows you to more easily block the time in your mind and with family.

I know people who like to do their study before work because that’s when they are fresh and study gets their brain into the right gear for the day. Other friends tell me they like to do research or study after their kids go to bed because it gives them more time with the most important people in their lives. All of those are great patterns because they are tailored to their life.

Whatever routine works for your life is a good one. The important part is to making learning a regular activity.

Share What You Know

One of the best ways I know to learn is to teach. Giving talks, writing blog posts, and mentoring all give me a chance to share what I know with other people.

Sharing can be intimidating. I have been writing this blog for nearly 10 years. I gave me first conference talk more than 10 years before that. And still, every time I take on a new topic I’m nervous I’ll be found to be a fraud.

I try to leverage the fear I feel to help me assemble the best content I am able (at least within my time and resource constraints). When I am writing, or preparing a talk, I also do a lot of fact checking. Since I never want to put anything into the world that I can’t back up later, I do my best to make sure I’m right. In the process I also learn more about the topic. That even means correcting information I was preparing because my initial understanding was wrong.

On the flip side I try not to let the perfect be the enemy of the good. I require myself to post on my blog once a month – limiting my editing time. Similarly conference talks have a hard deadline. Those deadlines force me to complete content on a schedule, not when it’s perfect. So be it.

When you share what you know people start to see you as an expert. That can lead them to ask you questions that push you to learn more.

All that can lead you to be an expert.

Make Friends

Making friends is easier for some of us than others. And maintaining friendships in our current society is extremely hard. But friendships are super important. They help keep us healthy, mentally fit, and happy. Friends also teach us really important things about the world around us.

If you have read this blog much you are used to seeing me make references to my friends as sources of information. They are my greatest resource for learning (and a bunch of other things too). Friends know stuff we don’t know. Even better, they will tell you things you don’t know. Good friends don’t judge you for your gaps, but are happy to help you fill them.

I value the input and perspective that friends share with me. We don’t have to agree on everything. We don’t have to be interested in the same technologies. In fact both of those conditions help me understand things I wouldn’t know about otherwise.

I cite my friends in my writing because they are important. They deserve credit when they teach me things. Processing ideas with my friends helps me test them for quality. Often they point out errors in my thinking. Those are all good things.

Be Curious

This is one of the most important lessons I learned from my mom. She was a deeply curious person and that rubbed off on my sister and I. We both remember her dragging us to lectures at the RPI Freshwater Institute in Bolton’s Landing, NY (it’s fun to discover those still happen – I highly recommend if you’re in the area). And the time she took us to a ranger talk at a National Park where the ranger offered a postcard to anyone who asked a question he couldn’t answer – she promptly earned all his postcards with questions she genuinely wanted answered. She would stop and talk to keepers at the Philadelphia Zoo to learn more about the animals (a habit my wife and I both now share).

Because of her constant interest in, well just about everything, I have been to historic sites, factory tours, art and science museums, zoos, and many other places. My wife – a curious person herself with her own curious parents – and I continue those kinds of adventures. We go places, we ask questions, and we learn things.

We also read widely, both in our professional fields, and about the world in general. Long drives often involve several hours of listening to podcasts featuring experts in a variety of fields. I’ve previously talked about those as my ongoing Liberal Arts education.

If you aren’t someone who was trained to be curious by your family, it turns out you can do things to increase your curiosity. And yes, I found that article cause I was curious to know if curiosity is trainable – there are deeper articles on curiosity out there too.

The value in being curious is that it causes you to learn things you might otherwise have missed. Some of those things just make you smarter about your world – and the world needs more smart people. Others will suddenly pop up in your work and make you better at your job. They might come up in random conversation with a new friend and deepen your connection to another person.

Learning new things is never a bad idea.

Always Learn More

All this advice boils down to this central idea: always being learning something new. It’s good for your brain and good for your life (oh yeah, and career).

Reading through all of this commentary on professional development you might think: “Wow, that takes a lot of time!” But if you put yourself into a mindset of always trying to learn something new much of that times starts to overlap with other activities in life. And when it’s not all dedicated directly to work it doesn’t burn you out the way constant study of one technology of platform can.

Push yourself forward. Find things that are interesting to you. Nothing new is a waste of your time.

So, as a public service to the community, I provide here a list of common lies and a sentence or two about why you should stop telling them.

My code is self-documenting

Not once in my career have I heard a developer say this and found their code to be “self-documenting”. Never. Nope. (If we’re friends: yeah, not even yours.)

Developers who claim to write self-documenting code seem to solve problems in the least-obvious way available. Or at least it feels that way to me. Maybe if they left comments explaining why they used their approach it would seem brilliant. I don’t know; it’s never come up.

Self-documenting code doesn’t mean following a variable naming convention and having no comments at all. You still need doc comments. You still need good functional decomposition. You still need comments to say why your code does things. Sure, I can usually figure out what it does, but not why.

If you still want to argue with me make sure you read Chapter 15 of Mythical Man Month before calling.

See Also: Nobody else needs to understand this code; I’m the only one working on it

Just because you are the only one working on it right now, doesn’t mean that will be true 4 years from now. I recently had to update code that had been running happily without attention for 5 years. By the time I was working on it, everyone had forgotten it existed let alone how it worked.

And don’t forget you might be that person who needs to remember these details 5 years from now. Guess who I called first when we realized that code needed updating? Yup, the guy who wrote it. No, he didn’t remember why he had made important choices either.

The only time I am not disappointed in the person who committed code in my name 6 months ago is when he wrote me really good comments to explain what he was thinking. When he didn’t do that: that guy was an idiot.

Future you, your colleagues, friends, clients, strangers, they all will thank you for explaining yourself. Doesn’t that feel better than having them all hate you?

I don’t need to use Git

Yes. You. Do.

It’s 2025. Bell Labs invented source control in 1972. “I don’t know how to use it” isn’t a valid excuse. If you’ve been putting off learning to use these tools, it’s time you admit they aren’t going away.

Just because the code exists in a Salesforce sandbox org does not mean you don’t benefit from tracking its history, knowing who (including you) changed what when (and if they wrote good comments why!). The first time it saves you because another developer overwrote your code, it’ll have saved you all the time setup required and more.

I can setup a new repository, with Salesforce configuration, in 90 seconds. It takes 10 seconds to do a commit. Sure, you can have merge problems sometimes – that usually happens when two people make conflicting changes. When do you need source tracking the most? When two people make conflicting changes.

When you see two sandboxes with two different versions of code, how do you know which is right? On my projects it’s the one that matches Git, cause Git is always canonical.

There really is no good argument against putting every line of code into a repo. Just because you have an argument does not mean you have a good argument. It’ll take you less time to start using Git than it will take to argue with me.

See also: I’ll just comment out this section of code for now, and delete it later

No you won’t. Nope, stop kidding yourself. I’ve seen your 200 line blocks of commented out “stuff” (without notes about why it was there in the first place, or why it’s commented out). You want to keep it for 3 or 4 minutes while you test a change – okay sure. But this is part of what source control does for you. Deleted something you want back? Okay, go get it out of your source control system. Delete your block of commented out code before your next commit.

I will fix this hard-coded ID later

If it’s easy to fix, just do it now.

If it’s going to be a bunch of work later, you know as well as I do that you’ll find excuses not to bother at that point either.

Either write the query to get the Id you need now, or move it to custom metadata/setting/environment variable/whatever now. It’ll take probably take 5 minutes to do it right now, and 20 minutes to find the stupid thing later (and 10 minutes to fix it cause you’ll be tired from the 20 minute hunt).

My invocable action doesn’t need to be bulkified

Sure, damn near every example invocable action only processes the first record in the list. Yes, that encourages us to think it’s okay to write code that way. And yes, bulkifying code is hard sometimes.

You might think that your record triggered flow will only need to deal with one user-entered update at a time. And then someone loads a 100,000 records and your action breaks the whole process.

And sure, you always feel like your action is only getting used in that one Screen Flow. But 9 months from now when someone realizes they can get the inputs other ways and call your action with the screens and puts it in a record triggered flow your code will still work.

There exist settings where the screen flow thing is true. They are rare, but I’ve seen them. Use this measure to determine if it applies to your project: if you cannot write a rigorous proof which is good enough for your high school geometry/trig teacher (college CS or Math Professors will also count here) to accept showing this code will only ever be run in a one-record context – you better plan for 200 records.

I will convert this test setup to use a data factory when I have more tests

Why? Why would you think you will take the time to do this conversion later? When you arrive at “later” you will just need one more object added to your setup. Or maybe 2. And you can copy-paste it into the next test setup method. Then may add 2 more objects. And then you’ll just…

If you don’t lay down good patterns up front, you won’t convert to them later. Starting a test factory class doesn’t take a lot of time. Just do it now, and thank yourself later when you realize you’ve slowly built a factory that’s supporting 5 different test suites and hundreds of tests.

I’ll move my business logic out of the trigger once it’s working

Once your code is working you have almost no incentive to clean it up. Chances are you’ll just deploy your code and wash your hands of it. It wont be until you’re neck deep in a conflicting sets of requirements that you’ll decide it’s time to refactor this mess – and then you’ll wonder what each conditional was for in the first place (see self-documenting code above).

Even during a recent technical interview, I took the 15 seconds needed to create the trigger and have it call a service class. I didn’t plan to keep that code for more than 15 minutes and I still bothered. I really think it took 15 seconds. Bing, bang, done. Sorting it out later is so much harder then just doing it on the first pass.

As longs as I hit the test coverage requirement, my tests are good enough.

Automated test coverage is not about hitting a certain number of lines run – that’s the minimum threshold. Good automated tests ensure you code works correctly. Good test coverage now means that when you revise the code later you know if your revisions broke something.

• Do not play games with getting the coverage percentage up.
• Do not have tests with no assert statements.
• Do not decide that 75% is just fine because to get to 90% you’d have to write three more tests – write the three tests!
• Do not let test coverage meaningfully changes when someone auto-formats your code.

Write tests that ensure your code meets specifications, not tests that make the deployment process happy.

I don’t need automated code standards enforcement

Salesforce Code Analyzer is a free tool you can install right now and will help ensure you don’t do stupid stuff in your code. It will also make sure you team follows the same habits. These tools have been around for Salesforce developers for years, but for some reason we don’t all consistently turn them on.

This is standard fare for professional developers. What makes you special that you don’t need to follow standards? Why would you think you can enforce standards on a team without automation?

Every time I have to do a commit to reformat code to be consistent with all the other code on a project, a [insert sad thing here] happens. This pretty much only comes up with people who don’t have auto-formatting of their own. Their code had blends of tabs and spaces, different line endings within the file, off-by-one spacing error (dear God I hope no one uses 3 on purpose), and all kinds of things that cause other editors to sputter and complain.

If you don’t like Salesforce’s default analyzer rules, you can setup your own. It’s just enforcing ESLint and PMD patterns. I have extremely little interest in debating code standards – just have some!

Special Thanks For Shared Salesforce Developer Lies

The following people sent me lies to include in this list, and I appreciate their shared pain. My rants about each are mine alone.

• Peter Churchill
• Michelle Hansen
• Raul Roque

I want to be clear, these are not the only resources to help you be a better communicator. They are just some resources that I have found useful and I hope you might also find useful.

Basics

I generally list two works to help with the basic mechanics: Elements of Style and the Art of Public Speaking. Both are over a century old, and yet still commonly referenced and both still have useful advice.

Elements of Style

Commonly referred to as “Struct and White”, Elements of Style is a short and easy to consume guide to writing well in formal English. It’s an excellent starting place for improving formal writing. But it is just that: a starting place. It is committed to helping the readers understand the formal rules – the elements. Elements of Style is not committed to teaching style, or even encouraging your own personal voice. For those things you will need to explore further.

Art of Public Speaking

Dale Carnage wrote a series of guides in the first half of the twentieth century to help people (mostly men) perform better in white collar work places. He started almost accidentally with the Art of Public Speaking. Many of his guides are still commonly read and referenced – almost to the point of being cliché (How to Win Friends and Influence People is also his). While his works are certainly somewhat dated at this point, the basic instructions on how to use your voice, organize your thoughts, and even the practice exercises it includes are still extremely useful when working on how to improve your speaking presence.

Further Explorations

As you gain comfort with the formal rules and techniques, you may find you struggle to find your own voice within those rules. The good news is that you don’t actually have to follow those rules all the time – just when it suits your needs. But learning how to manipulate the rules gives you control and freedom over the language. You might also find you want tools beyond just words to accomplish your goals.

Test the Limits of Grammar

Lynn Tross’s Eats, Shoots & Leaves helps with the first of those two goals. She has an entertaining approach to looking at how and why punctuation matters. But she also makes it clear that some uses are about style as much as clarity. She encourages her reader to both take punctuation seriously and to have fun with it. With her insights you can think about how to bend, twist, and even break the rules outlined in guides like Stuck and White. I know several people who found her guidance helped them take more control over all parts of their writing.

Don’t Only Use Words

Dan Roam’s Blah, Blah, Blah provides ideas for how to handle the second of those challenges: what to do when words alone don’t work. It provides an overview of why and how to use images to help improve your presentations and writing. Like all the others it can give you ideas and inspiration. Where you go from there should be your own interpretation of those ideas and suggestions.

Keep Going

Reviewing materials that are meant to train you in basic techniques is necessary, but not sufficient. You need to take the time to see how other experts use those techniques in practice. The good news is that just about anything on a technical topic can be helpful here.

More Readings

For reading on technical issues I tend to personally suggest well known works. Books because well know, because they are good (usually). Books stay important because they have important ideas – even if we have moved away from the details.

Mythical Man Month, for example was often required reading for developers and project managers for decades. While we want to believe our field advances so fast that a book first written in the late 1960’s is ancient history, the content is surprising relevant. It has held on so long because Fred Brooks covered important ideas and because he expressed them well.

Speeches and Keynotes

Listening to speeches, watching videos of great talks can be excellent as well. The obvious choice here is to watch Ted Talks. The only down side to those is they can be intimidatingly good. They have an extremely high production quality, world renowned speakers, and a well trained team to make it all happen. While I find that content excellent and inspiring, I would never try to match their production quality for a talk I’m giving at a local user group meeting.

For that I look to more simplistic content. When I commuted by train many years ago I would listen to talks published on the old Conversations Network because they were interesting, audio only (so good for public consumption), and sometimes flawed – I could imagine myself giving talks like that. More recently I’ve taken up listening to podcasts from the Freakonomics Radio Network and other places that are polished and high quality, but not so much that you can’t imagine reaching their level. Particularly shows outside their flag-ship Freakonomics are a little rougher around the edges while still being a good listen with interesting ideas.

Practice

All of these resources are only useful if you put them to work. I’ll talk about this more in a future article, but to really get good at this you’re going to need to practice. Nearly everything in life improves through practice, including your communication skills. To really get good at this, plan to put in some work. And expect to fail sometimes. It’s how we all learn and grow.

As I said in my first post on this topic, communications skills for developers and consultants is an enormous topic. The plan for this series is evolving as I go. If you have suggestions or requests feel free to leave me a message.

Why not use Salesforce Ids on public web sites? I run into this question from time to time and figured some more public commentary would be useful.

The super short version: they are not a security or access control mechanism.

During a recent Salesforce Open Source Commons sprint a question came up about why it’s important to use a random value, instead of a Salesforce Id, in public facing use cases. We were talking about the Unsubscribe Link package, and it makes a good use case for discussion.

What is Unsubscribe Link?

Here is some quick context on Unsubscribe Link and why I’ll be using it as an example in this post. Jessie Rymph created the Unsubscribe Link package for Salesforce Labs. Community volunteers are taking over the future of that package and those volunteers need to speed on the great work she already did.

The package provides links you can embed in email messages sent by Salesforce that allow recipients to unsubscribe from future messages. These links need to allow the recipient, and just the recipient, to make this update. It needs to update the data in Salesforce in a secure manner, based on a link provided in an insecure channel (an email message). Links need to be reliable and consistently formatted, but not guessable. The package, rightly, uses UUIDs in those link to match the link opened back to the correct Salesforce record.

The Attack on Salesforce Ids

If you have a public facing web page or service that allows for display or update of data that filters access based purely on the Salesforce Id, you are at risk. An attacker can manipulate those Ids and either steal, or mass update, your data. This is called a “bad thing”.

The technical terms here are: Insecure Object Reference leading to a Web Parameter Tampering attack.

In the case of Unsubscribe Link, if the link used the Salesforce Id, it would be possible to unsubscribe all, or nearly all, Contacts in the org. The attacker would start with the Id in the email they got, and then start scanning up and down the Id range (see next section for how). Unsubscribe Link is protected against this attack, but I see elsewhere all the time.

Here are a couple quick examples (which I saw, helped fix, and hear people describe recreating):

• An org that allowed members to confirm their details by clicking a link in an email. They could then see their contact and membership information on a web page. That web page had no authentication, and the link’s only parameter was the Salesforce Id. Once you had one link, you could change Id and view other people’s data.
• An event check in solution that used a QR code volunteers scanned at the door. The QR code contained a link that lead to a form which showed their registration information (including name and email) and updated their Campaign Member status – again the only link parameter was the Salesforce Id. Anyone with the QR code could have pulled the complete email list of attendees with a few hours of scripting.

Salesforce’s Id Structure

To understand how an attacker can do this it is useful to understand Salesforce Ids. They often look random but are not. They are defined by a predictable, and published, pattern. If you want really gritty detail have a look at this post. But I’ll give you the short version here.

They start with a 3 character prefix that encodes the object type. Salesforce provides documentation for decoding the id prefix for all standard objects. Custom objects have a prefix that’s specific to your org.

The next three characters are an instance reference. This reference indicates the Salesforce instance hosting your org when creating the record. It’s highly stable, but can change from time to time.

Then there is a zero that’s reserved for future use.

Next comes a 8-digit base-62 number. This provides a huge range, but it is just an incrementor stored in a convenient fashion.

That covers the first 15 characters. Salesforce Ids come in two flavors, 15 or 18 characters. These 15 character Ids are case-sensitive base-62 strings. In most cases you will be using the 18 character flavor. The 18 character version are case-safe and add three more characters that encode the case of the preceding 15 characters. So those last three also often look random, but are entirely calculable based on the first 15.

From an attackers perspective a Salesforce Id looks like this:

[7-digits I can copy and paste][a very big number][three digits I calculate]

How Do They Know What Salesforce Ids to Scan

For an attacker the only hard bit is figuring out what very big numbers to use.

These Ids are not meant to be random or secure. You should think of an 18-digit as a base-62 number. Worse yet, an attacker only needs to scan a small portion of the space to find data. Only 8 digits are actually incrementing (still a huge range – 62^8 is large by even astrophysics standards).

If an attacker had to check that whole range they’d never find you. But your Ids are clustered together relatively tightly. Worse yet, when they start their scan, they already know where to look – you told them.

But I Read This Isn’t Important In Practice!

There is commentary around suggesting that these numbers are too big to guess so they therefore protect you from attack. If those numbers were random that might be true, but they aren’t randomly assigned.

Salesforce generates Ids sequentially within a node which is often hosting multiple customers. The node started at zero once upon a time. Every time a record was created Salesforce incremented that number. Whenever someone runs tests, it increments the number and then dumps the data (and those Ids). When someone on another org on that instance adds data, up goes the number. During bulk data loads there are multiple processes running, the processes will each reserve a transaction’s worth of Ids at a time and may be on different parts of the file making them look out of order. If one of those transactions fails, it’ll create a gap in the sequence (typically 200 records in length).

All that means that your attacker usually cannot reliably guess the Id of a specific record, but if they scan large numbers of records they can find lots of data.

Those behaviors do spread the data out over a slightly larger area than a purely sequential Id in a traditional database. But your data all starts are some number with Ids above that number. The larger your org, and more active you are, the more likely it is that your data has dominated Id generation since you joined the node.

Yeah, They Know How to Attack You

You have also done things in the course of business that clustered your Ids together in sub-ranges that help your attacker. For example when you migrated data into your org, or any other bulk load, you created a lot of records with very tightly clustered Ids. So while searching they may find large gaps between records, and long runs of perfectly sequential Ids.

If the attacker knows one Id, then they know what area to start looking around in for more. How do they get that first Id? I already told you: you gave it to them.

In my experience an attacker is going to find your vulnerable service by getting one of the links. They will quickly see that it doesn’t require authentication, and that the Salesforce Id is the primary parameter. That link has an Id in it. That means they have an Id in their hands from whatever email or other solution you used. They don’t have to start at zero and count up until they find your range. They aren’t picking a random starting point. Instead they will start with a number they know is in your range. After that they can just search up and down the number line to find a lot more.

Sure they will get a lot of misses – but who cares? Attackers don’t do this by hand, they use software that works fast and never gets bored. They also know things about the likely size of gaps, can spot common patterns, and hop around in smart ways to find likely valid Ids. Attackers spend a lot of time thinking about these problems. Always assume they know patterns that you did not know existed.

Solutions

There are two main ways to prevent these attacks:

1. Use authentication for all web services – even when that’s hard or annoying.
2. Use a truly random value to do the lookup and limit the attacker to one record.

If you put some form of reliable authentication in place you can make this problem largely go away. But it limits what you can do. That can work for event registration or member directories – but it doesn’t work for Unsubscribe Link or other unauthenticated use cases.

A properly generated UUID creates a random value that cannot be guessed or iterated. Unsubscribe Link leverages this approach to make it impossible to unsubscribe another person. The package assigns each Contact or Lead a UUID generated with Apex’s UUID class. The package then uses that UUID in the link included in the email. When someone clicks that, it opens a page which searches for the UUID and updates the matching record. It doesn’t have to be a UUID, there are other solutions to get truly random data, but UUIDs are a great solution in lots of use cases.

Depending on the setup, you can also create or use services to detect these kinds of attacks. It’s not uncommon to see but not something Salesforce provides directly, nor is it common to see with form providers and other services.

In the end, secure design is your responsibility.

To be clear I have been experimenting with Github Copilot and Salesforce’s Agentforce for Developers since they were released. Most of my earlier experiments were failures. The tools wrote trivial code terribly and simply couldn’t understand more complex requests. They made me slower, not faster, so I put them aside for a time. But they are evolving fast and were worth another look.

I learn by doing. So I set about creating a few tools that were on my mind to see if I could get good code out of the LLMs. Or at least if they could save me enough time to be worth the learning curve to get good at using them.

Project 1: Simple OpenWRT Status Call Out

I recently updated my home wifi router to run OpenWRT. When I bought the router I selected one compatible with that OS. After realizing T-Link would never fix some security issues in the firmware I made the switch.

Our internet service from Breezeline has always been spotty; sometimes bad enough I need to relocate to get stable service. One of the things I want to know when I’m working elsewhere is: has my internet come back up yet?

I have a programmable router, I’m a programmer, therefore this is a problem I could solve for myself.

But I’ve never written code to work with OpenWRT. Worse, I generally work in high-storage environments. I mostly do side projects in Python or NodeJS, but my router doesn’t have the storage needed for those run-times. OpenWRT recommends C or Lua for scripting. I’ve done my time in C. Jumping through all the hoops required to make C do something this simple did not feel like fun. So Lua it is. Too bad I hadn’t written code in Lua before…enter Copilot.

Throughout this project I used the current defaults – which meant GPT-4o was the selected LLM.

Initial Code

I actually found Lua by asking Copilot. My first prompt was just:

Generate a program for openwrt that sends a post request to an API endpoint at spinngingcode.org

And it generated a reasonable looking Lua script. Since I don’t know Lua, or at that point why Copilot chose it, I dove into a little research into the language. After a few minutes I confirmed that, yes, this is the right use case for Lua. I also confirmed Copilot made reasonable choices in how the code was written.

I went on to ask Copilot to change call outs from curl to a library, add features to pull in the network status information from the router, and other adjustments. It consistently generated code that was close to correct. I did have to tell it to adjust details after validating them against my router’s actual setup and commands. It took some time but on the whole I was able to make steady progress. Eventually I had a good-enough solution.

Tests

Automated test generation has been a promise of these tools since they arrived. It always feels like something that’s easy to do: read code, write test. Which is, of course, the 100% wrong way to write tests. However, the point of the exercise was to see what I could get the tools to do, so I gave it a try.

It took several tries for it generate valid tests. The first time I asked, it wanted to know what framework to use (a fair request), but generated a useless hello_world test file. On subsequent tries it switched frameworks without asking, and took several tries before generating something that looked valid.

Too bad it wasn’t valid.

The test framework I picked, luatest, was a bad choice. But with little experience in the language I didn’t know that. When I finally had it refactor to busted, I got tests I could setup and run…and they all failed cause they were still all wrong.

I spent more time getting a valid test setup than primary code – eventually I gave up. It would have been faster to do the research and figure it out from scratch.

Code Review

All in all, Copilot gave me a reasonable piece of code for the primary request. Using Copilot was far faster than I could have done the research to write something equally good. It still needs a lot of supervision to get it right, but the refactoring requests seemed to go okay.

The code commentary Copilot provided in the response is detailed and accurate, where I checked it. It’s chatty so I didn’t check every piece of commentary just every line of code. The code itself came with passable comments about what each block and function does. And functional decomposition was vastly improved over previous experiments I’ve done with Copilot.

It had to make up a few details, like the actually API endpoint name (it picked https://spinningcode.org/api/endpoint – okay sure reasonably good fake answer that is clear but also obviously wrong), but those were good enough for the limited details I gave it.

Outside of the automated test disaster, the biggest issue was that it did nothing to encourage secure design. Copilot recommended no security for that endpoint, nor does the commentary flag that it skipped security suggestions.

Project 2: Simple PHP Status Server

Since I have PHP on my personal server, I decided that PHP was the right choice for the server side of the router project. Despite being a little rusty I am much more comfortable with PHP than Lua. I have standards and expectations about how to write and organize good PHP code.

The prompt I provided:

I have a Lau script that looks like this:

[a copy of the then current version of the Lua file]

Now I need a PHP application that will listen to those calls, record the data into a CSV file, and includes a page that displays the last 100 lines of the csv file.

It managed to generate valid PHP code that matched my request – sorta.

Code Review

The PHP it generated is not to my standards – not even close.

It lacked security checks, was poorly organized, and had borderline useless comments. If you look at the repo there are both a lot of generated refactors and then a lot of hand edits cause that’s web facing code, security matters, and I could fix it faster than debating with an AI.

I made some effort to get it to highlight the important information I wanted, but it struggled to regain the context from the OpenWRT requests that the Lua script was built around.

Unlike the Lua script, the PHP saved me little or no time. It was terrible in this context even with lots of attempts to refine the code. This piece of code I’ll probably maintain by hand.

Project 3: Data Migration Scripts for Salesforce

One of the hardest things to get people to fund sufficiently for a Salesforce project is the data migration. They are hard, boring (well not for everyone – I have undying respect for people who like these projects), and super time consuming. So we are always looking for ways to do them faster.

A few years ago I proposed a training exercise for data migrations that involved taking the data from my SC Salary Data repo and loading it into Salesforce. It’s a great training project because there is lots of data and it’s real-world messy. But it’s also simple: just two or three objects depending on the data model you choose. So I decided to test if I could use AI code to generate basic scripts to clean and load this data quickly.

For this project I made two changes to my approach. First, I switched the model to Claude 3.5. Second, I decided to treat the LLM like a junior developer and lead it through the project more intentionally. Part of this second change was driven by my initial experiences with the other projects. I assumed from the start that the code would be sub-standard, but that I could encourage Copilot to make changes to meet my expectations – just like I do when working with a human.

Code Review

This project was startling successful. The first stage was to have it create a script that prepped all the data into a simple SQLite3 database (it does some clean up, but not all that’s possible with this data). The second stage was to have it create a script to load the data. That second stage became it’s own repo because I wanted to include a Salesforce SFDX project to setup the objects and fields I wanted correctly.

I generated probably 90+% of the code in that repo with the LLM. The Python to load the data, most of the Salesforce Metadata to create objects and fields needed, even the read me file I generated in large part with the LLM.

Frankly this is a project I’ve seen developers struggle to get right, and with a little guidance the LLM was able to do it. It probably needed as much guidance as a human would have (a very junior human developer), but the iteration cycles were much faster. I am not convinced when all is said and done the project was faster – it took a few hours to complete each stage – than my doing it solo. However, it required far less mental engagement from me than if I had written the code unassisted.

This project went well enough I’m using it to help drive a conversation about how to change our approach to migrations in general. There are major differences between what I did and I do in a migration of a database with thousands of tables targeting hundreds of objects with millions of records. But I was impressed enough to want to move on to fill those next gaps.

Conclusions

LLM generated code is improving fast, but it is still generating low-quality code by default. Unlike experiments I ran a year ago, it now generates functional code that is equal to the code that a brand new developer could write.

Generated code is not to be trusted, particularly in production or public facing settings. If you don’t ask for security, you don’t get security. It organizes code as if it’s following train of thought, not in the order that well structured code should follow. And it does not write tests worth having without significant effort.

Good AI driven tools can make good developers faster. They are not good enough to replace a good developer – yet. Developers will need to learn to work these tools into the process, but we need to be aware of the gaps and how to close them.

I expect the quality also depends deeply on the quality of the code in public repos on the internet. I believe the terrible quality of the PHP I got vs the reasonably good Lua and Python is because there is lots of terrible PHP out there used to train these models. As long the LLMs write code that conforms to the average of the examples online communities will need to sweat the details of what is out there.

But because they have no user interface access there is no clear path to reset the security token (in fact Salesforce says you cannot do it, although it’s listed as on Roadmap). There is a way to get this done, it just requires that you have Login As permission.

1. Go to Setup -> Users, and find the Integration user for which you need to reset the security token.
2. Click Login next to the user.
3. You will be logged in as this user (it used to be that you were using the Salesforce Classic Interface but that’s no longer true). You can reset the token using the standard process.

And from there Salesforce should email you the new token.

It is worth noting this is not best practice. Best Practice is to use the OAuth JWT Bearer flow or the OAuth Client Credentials which don’t require the tokens. But not all tools are setup to use those flows, so the tokens are still useful.

When Salesforce completes providing a direct mechanism it should be better than this process, but until then you can happily reset tokens as needed.

Reminder of the Options

Part 1 provides a detailed review of the directions that data can flow, and the types of architectures you can use to support your solution:

• Data can be outbound to constituents, provided by individual constituents, or exchanged among constituents.
• There are all-in-one solutions, two-system solutions, and solutions with an API or data proxy layer.

Three patterns, three potential solutions: it’s temping to think they align 1:1 – but then a whole second article would have been a waste of time. But it is important to keep them in your mind as you determine the best-fit for your organization and use case(s).

Portal Architecture Considerations

To make the right selection you need to balance your overall data ecosystem, staffing, budget, audience interest, as well as projected growth over time. I keep wanting to create a simple decision matrix, but an easy solution eludes me still.

Audience Engagement

The first major consideration is how will your audience actually engage with the portal. This should drive not only how you build it, but if you build it at all. Lots of organization believe their constituents are all waiting for a great portal to see all their information, update their addresses, and even communicate with each other. This is rarely true. None of us is short on things to do online – you need to be clear about what makes your portal worth their time.

When you align your project to your audiences interest, a portal is powerful, useful, tool that can make a huge impact. But if your audience isn’t interested in what you offer them, you just spent a bunch of money on a web site no one uses. There are times when the most effective constituent portal is none at all – because you can use those resources elsewhere.

Think carefully about how many of you constituents want to log into your portal enough to:

1. Remember it’s there.
2. Care enough to take the time to log in.

You spend something like 40 hours (probably more) a week thinking about your organization’s work. They spend 40 hours (or more) a week thinking about their employer’s work, also their families, friends, all the companies and nonprofits they interact with, politics, meal planning, shopping, and whatever else – there isn’t much time left for your organization.

Think about the features you can provide that are valuable to your audience and the best way to deliver those. For example, organizations often want to give people places to update their address or payment information. But think about the last time you moved, did you want another place to change your address information? Another common ideas is that nonprofits want to make delivery of annual tax receipts cheap and easy. If successful that means a wave of use once a year that might save your on mailing costs – of course you can also ask for a gift in that mailing so it might not actually be a net gain.

Questions to ask:

• What problem does this portal solve for my constituents? Do they care if I solve it?
• What is the best way to deliver our solution to our constituents?
• Will my constituents be willing to log in at all?
• How will this portal empower themselves or to support our work?
• How many people need to use the portal each week, month, or year for it to be successful?
• Do we expect that number to grow over time?
• Will likely traffic be spread out, or come in a wave?

Technology and Data Ecosystem

Your portal does not exist is a vacuum. Your organization has lots of technology kicking around these days, and you want the tools you select for this project to build on your overall technology landscape. When I make a recommendation to a client, I spend a lot of time asking them about the tools that are already in place and how they are used. I’m looking for tools that could be the basis of the portal, reveal the expertise of their staff, and would work well with Salesforce (or other technologies I’m part of introducing). I am also trying to understand some of the history about those tools and how they came to be.

If there are other complex systems, and they are working well, that’s a sign that an organization can probably handle more complex architectures. It’s also a sign they probably know how to benefit from that complexity. But it’s also a sign their staff may be consumed with what they have. If they have all simple systems I am going to be inclined to keep my solution equally simple.

Questions to ask:

• How many interconnected data systems do we have today? Do they work well, or are we struggling to keep up?
• If we add a new system will it enhance our digital presence or pull attention from other critical systems?
• Are the solutions we are considering related to technology we already use, or are they entirely new?
• What kinds of resource, limits, and features does my main CRM provide?
• What other technical resources do we already have in place that we could leverage?
• Did past projects go well, or leave a bad aftertaste?

Staffing

Your solution will require staff support. Even the simplest of systems will trigger requests for help using it. The more complex the solution, the more skilled your staff need to be to make sure it runs smoothly – and the more staff you need to support it.

You staff bring two things to the table: time and skills. They need to have the skills to support your solution, and the time to use those skills effectively.

Please do not just plan to push your staff harder, you need to find ways to remove other tasks from their plate or add people to your staff if you want to avoid burn out.

If you use an all-in-one solution, you probably just need people who understand that platform, know how to engage with your user constituents, and can work with to provider’s support team. The more systems you need the more platforms your team needs to understand, and at least one person needs to have a deep understanding of how the whole thing works.

You also should consider aligning your technology selection to what your team either knows, or wants to know. Most of the time you want to play to your team’s strengths not ask them to develop a whole new skill set from scratch.

Questions to ask:

• What roles do we need to have for your portal to work?
• What work do we want done by our staff vs consultants?
  • Who will answer support requests?
  • Who will respond if there is an outage?
• Do our current staff have time for new responsibilities?
  • How can we reduce their workload to offset new requests?
• Can we hire more staff?
• What technologies do our current technical team members already know?
  • What are they interested in learning?

Budget

Obviously all this will cost money. There will be some combination of license costs, hosting fees, implementation costs, support contracts, staff salaries, and other expenses. Just because a sales person says their solution works “out of the box” does not mean it’s free to get started.

You need to account for the implementation cost: how much will it take to setup and train people on the new system?

You also need to plan for maintenance costs: what will it cost to keep it running every year?

In very broad sweeping terms my experience is that most of the time an all-in-one solution will be cheaper and faster to implement than a two-system solution. But all-in-ones often have higher annual operating costs. Those operating costs are likely to grow linearly with audience size. A two-system solution, while more expensive to setup because of the complexity, will often have a lower annual cost and lower price escalation curve.

When you are considering your options, those are the two budget figures to make sure you understand. What will it cost to setup? How much will it cost over the first 5 years? And what factors will impact those two figures?

Different organization can tolerate different cost structures. If your organization prefers to invest up front and have lower long-term costs, you should make a plan to optimizes for that. Other organizations want the lowest upfront risk, but can tolerate higher costs – particularly if they are linked to a successful and growing solution.

More complex systems are also riskier to build. There is a greater chance of hitting problems that require extra budget to resolve.

Questions to ask:

• What will each of my main choices cost to implement?
• What are the 1, 2, and 5 year costs likely to be?
• What factors will drive costs?
• What is my organization’s budget tolerance for up-front vs long-term costs?
• How firm is the budget? What are my contingency options for overruns?
• What are my options to control costs if there are problems?
• What can our staff realistically do vs what do we need to pay consultants to do?
• If we learn the portal isn’t working, what will it cost to cancel our contracts early?
• If my traffic will be in small bursts, will I have to pay extra for those bursts, or pay all year for services we’re not using?

Closing Thoughts

There is no one right answer to these questions, and they lead to complex matrix of decision making.

Take the questions I’ve posed, and have a robust and honest discussion about them. Ask your own questions. If you have a consulting partner you trust, have them test your answers and add their questions as well (sure, they are incentivized to get your to build it, but they should still have insights you want).

To make your final selection I suggest you write out a 3-5 year plan – this is a thing consultants can help you do well. Test it with your internal team before taking it to leadership. Make sure you understand it, and that your team understands it, particularly if a consultant wrote it.

I’ve been down this road a few times, and seen organizations make great decisions that led to successful projects, careful decisions that led to portals no one used, and wise decisions to walk away from their vision for a new plan. You need to be open to all possible paths.

Good luck!

This is the first in a series on what your choices are, and now to select the right one. The architecture you select will drive the implementation cost, maintenance costs, and scalability.

The Purpose of Your Constituent Portal

Before deciding on the architecture of your portal, you need to have a clear understanding of its intended purpose and expected scale. The purpose of the portal will also dictate the direction(s) data flows, and the scale will help you plan the long term costs.

If you can’t clearly state why you need a constituent portal, you don’t need one.

Different organizations have different reasons to create portals. Companies that sell products may want a warranty or support portal. Nonprofits often want a donor portal that provides tax receipts and allowed recurring donors to update their gift information. Member organizations want a place for members to see their benefits, update their information, and renew their memberships. And so on.

The purpose of your portal will determine the direction that data flows through it. There are essentially three directions that data can move.

Outbound Data

You can send data from your organization to your constituent. That could be things like receipts, memberships status, or product warranty information. Anything that is data you have, that your member might need to see, but not update.

Data Exchange

You can allow constituents to update information. That could be address changes, support requests, donation schedule updates, event registration details, and more.

Data Network

Your third option is to allow you constituents to exchange information with each other. This could be a any form of member community where they engage with each other.

When planning a network, remember you have to plan for content moderation and acceptable use policies.

Primary Portal Data Architectures

To support your portal, whatever the data flow is, there are three main data architectures you can choose from, each which a different strengths and weaknesses. The more complex your architecture the more options you will have for what it can support, but it will also increase costs and maintenance efforts. Bigger is not always better – sometimes it’s just more expensive.

1. All-in-One Constituent Portals

In an all-in-one solution your constituent portal is part of your CRM. For obvious reasons this is the type of portal that your CRM vendor wants to sell you. In Salesforce land this means Experience Cloud. There are also many nonprofit-focused CRMs which include one in their solution. When your portal is part of your CRM you get a bunch of advantages:

• Data all lives in one place. There is no data sync to worry about setting up or maintaining.
• You have one vendor. That means you can centralize your support arrangement and billing.
• They are often fastest to implement. They are designed to be fast to market to help make them the obvious choice.
• They generally do not require a developer. Again, your CRM vendor really wants you to select this path, so they clear as many hurdles as they can.
• There is only one technology stack. By leveraging the technology of your CRM your investments in learning that technology carry over, at least in part, to your portal.

There are also downsides:

• New template system to learn. The CRM’s portal likely has a different template system than the CMS on your main web site. That may be hard to make match your primary online branding.
• The vendors make a lot of assumptions. To provide that ease listed above they make assumptions about how data flows, security, user experience, and how other elements should work – those assumptions may not match your ideal solution.
• Costs often scale linearly. There are usually license costs that are scaled based on user count meaning your costs grow as the portal grows at more or less a 1:1 rate. While there are price breaks and other incentives this is the right expectation to have for estimating.

2. External Constituent Portal

In this pattern an external constituent portal moves the user experience from within your main CRM’s sphere of influence into a separate platform. In my career I’ve mostly built these with Salesforce as the CRM and Drupal as the portal platform – it’s a powerful pairing. The strengths and weaknesses here are more or less the mirror of the all-in-one portal.

• Your web team may already know the technology. If you use the same technology as your web developers use for your main web site(s) they already know who to handle design and branding.
• You have greater control over the User Experience. The assumptions that go into the portal are yours not the ones imposed by the CRM.
• You have greater control over security, along with data flow and formats. Since they aren’t built around assumptions you don’t control you have greater control and freedom.
• Costs typically grow more slowly. It is less common to have per-user license costs in this context so the cost curve is likely closer to logarithmic.

The downsides:

• You have to handle data synchronization. The two systems means data has to pass back and forth.
• You have two different vendors/platforms. When you had one system everything was centralized, now you have two different systems handling constituent data.
• This design typically is harder to implement. All those short cuts your CRM provider had in mind for you are gone. Even if you use a purpose built solution it’s going to take more time and effort.
• This approach generally requires a developer and/or data architect. To implement this pattern you need someone who understands both platforms – ideally both for setup and support.

3. External Constituent Portals with Data Proxy

In some situations it makes sense to insert a data proxy, or API layer, between your main CRM and your constituent portal. This creates a layer of abstraction, security, and data augmentation that can benefit a lot of organizations. While this is the most complex of the three main architectures it is one I find is frequently overlooked – in part, I suspect, because no one partner benefits from selling it.

This setup certainly isn’t for everyone, but when it’s the right fit it makes a huge difference. It also creates a significant number of iterations – all of those arrows could be one directional or two directional.

An extra data layer makes the most sense when data from your CRM is going to multiple places and/or needs to be augmented by an external data source. For example think about an organization that provides trail maps for hiking or paddling. All that data geocoding those trails does not need to be in your CRM, but you probably want to know which members are interested in which trails so some trail data is needed there. Meanwhile in public you want a great deal more information all linked together. An organization like that may have a portal for members, a web site to find trails for non-members, apps for iPhone and Android, and perhaps a public API for other people to use to build their own web sites with. That’s a lot of API calls all with different data sets, all of which need to be very fast.

Your CRM is designed to be very stable and reliable – it is not designed to be very fast. What’s more, you often have limits on the number of API calls you get in your package (with extra fees charged if you go over). By inserting another layer between your CRM and other services you can bypass these limitations.

There is another added benefit to this design pattern, and that is increased security. By creating an additional layer in your system you are able to create a separation of concerns between the various systems. Each should have access to only the data is absolutely needs from any of the others.

How to Pick?

There are lots of considerations that go into selecting the right architecture for your project – which is why that’s getting it’s own post soon.

I have been wanting to setup a CI pipeline for Salesforce scratch orgs for a long time. The documentation out there isn’t great, and it’s taken me awhile to get around to powering through the details. For testing that my scratch org configurations for Education Cloud and Nonprofit Cloud to work properly I finally bit the bullet and setup a Github action.

What you’ll need

1. An SFDX-style project on Github that you want to setup for automated testing that includes a Salesforce scratch org.
2. An org with Devhub enabled. I recommend using a production org for this, not a developer org because of the higher scratch org limits. There are no good reasons not to enable Devhub.
3. A working install of sf cli with a connection to that devhub-enabled org.

Setup Github Secret

For your action to work it will need to use your connection to your Salesforce Devhub. Salesforce CLI stores the needed key on your local machine, which includes tokens to open the org. You will need to put those keys into a Github secret for proper security.

Note: Should that key ever be compromised, they attacker will be able to open the org as the same user. I suggest you consider using a dedicated user with either a Free Limited Access License, or another similarly restrictive set of permissions. These users are designed to avoid exposing data if they are compromised (they are also free, which has some upsides). That said, you can get yourself started with any user that can access to Devhub objects and then switch out to something more restricted later.

To get the key from sf cli, run sf org display -o [your devhub alias] --verbose where [your devhub alias] is the name of the connection you selected when setting up the connection. The output of that command will include: “Sfdx Auth Url”, that is the value you need in your Github secret.

1. In Github, go to your repository’s settings, expand Secrets and Variables from the left menu, and select Actions.
2. Create a new Repository secret.
3. Name the secret DEVHUB_SFDX_URL
4. Copy and Paste the Sfdx Auth Url value into the Secret field.

Create the Github Action

The full details of Github Actions are a deep topic, as are the full capabilities of sf cli for testing. So I’m going to focus on setup of an action the creates your scratch org. From there you can expand your workflow as you need.

In your project root create a .github folder, and workflows folder within if you don’t already have them. In the workflows folder create a file called buildScratch.yml.

Copy the following code (explained below) into your file:

name: test run scratch

# Definition when the workflow should run
on:
  # The workflow will run whenever an event happens on a pull request
  pull_request:
    types: [opened, synchronize]

jobs:
  validate_scratch_deploy:
    runs-on: ubuntu-latest
    steps:
      # Install Salesforce CLI
      - name: "Install Salesforce CLI"
        run: |
          npm install @salesforce/cli --location=global
          nodeInstallPath=$(npm config get prefix)
          echo "$nodeInstallPath/bin" >> $GITHUB_PATH
          sf --version
      # Checkout the code in the pull request
      - name: "Checkout source code"
        uses: actions/checkout@v3
      # Load secret for dev hub
      - name: "Populate auth file with SFDX_URL secret"
        shell: bash
        run: "echo ${{ secrets.DEVHUB_SFDX_URL}} > ./SFDX_URL_STORE.txt"
      - name: "Authenticate with dev hub"
        run: sf org login sfdx-url -f ./SFDX_URL_STORE.txt -a devhub -d
      # Create a scratch org
      - name: "Create scratch org"
        run: "sf org create scratch -d -f config/project-scratch.json -a our-scratch-org --duration-days 1"
      # Deploy Project Manifest
      - name: "Deploy Metadata"
        run: "sf project deploy start --manifest manifest.xml --target-org our-scratch-org"

Action Breakdown

The first few lines are common to all actions, it gets a name, then a set of conditions to trigger the workflow. In this case we’re calling our workflow “test run scratch” and it will run when a Pull Request is opened or gets new commits.

The jobs section is the more interesting bit. We tell Github to create a virtual machine using the most recent version of Ubuntu Linux. Next we install Salesforce CLI onto that virtual machine. Once that’s done, we tell it to checkout our code from Github onto this virtual machine. With all our tools in place we’re ready to start the real work.

The next two steps extract the Github secret we defined earlier into a file on the virtual machine and use that file to authenticate to your Salesforce devhub. All that work gets this temporary virtual machine into the same position as your personal device probably was when we started.

The last two steps create the scratch org based on a hypothetical scratch org configuration file and gives the scratch org a short life of one day. Finally deploy your project’s manifest-tracked metadata. This last step could use any version of the deploy command. It could also be added by more steps to deploy other metadata, run tests, or anything else you want to have happen.

Closing Thoughts

Building from this point you can do all kinds of things. For example, if you don’t need to gain access to the org itself, you can include a step to delete the scratch org when you’re done to help avoid the active scratch limit.

You’ll want to pay attention to the limits of your org to see if you need to tweak the triggers of your workflow. If you aren’t using a production org you scratch limit is only 6 per day, and three at a time; I blew through that testing the steps in this article. Even larger orgs only have 200 per day. So be thoughtful about when your action runs, and how often you clean up.

As always, if you find a flaw in my solution please let me know. I’m always interested in making these better.

Over the last few years I’ve done a number of large data migrations into Salesforce, and developed a pattern I like to follow. This pattern allows me to load data efficiently at any scale. While the implementation details will vary, you can adapt this pattern to your projects.

Efficiency matters more the larger your project: for a small project, this is overkill. If you are loading 1,000 Contacts it will probably take you longer to setup my process than just format the file in Excel and load it through Data Loader. But if you need to load 100’s of thousands of records, millions of records, across lots of different objects, this pattern can save hours or even days.

Migration Process Overview

The general concept here, is that you’ll run your migration in two major phases:

1. Prepare the data in a staging database.
2. Load the data into Salesforce.

Salesforce Schema Mirror Staging Database

The key to this process is that staging database in the middle.

In my experience having a database that is a clone of Salesforce’s schema allows you to fully prepare the data prior to loading. It also gives you a source of truth when handling partially loaded data.

Salesforce is slow to load compared to most traditional databases. By having a staging database you can load fast, gives you a chance to insert steps into your process that are hard in other contexts. These steps allow for testing, speed-enhancements, and error recovery.

Some ETL tools make a staging database easy to build, others do not. If you aren’t sure how to build such a database (or it seems like a huge effort to re-create all those tables), you can use Salesforce2Sql – that’s why I created it. It will clone your Salesforce org’s schema into any of its supported databases.

Testing and Error Recovery

The staging database lets you test for errors after you do your initial conversion; before you load it into Salesforce. You can leverage reporting and scripting engines designed for that database. You can log and error trap during your loading process far more gracefully than the Salesforce APIs support by default.

I often add one more table than just the objects: a logging table. This allows me a place to write the rows from Salesforce error files, and also log the time it takes for each process to run. I can see exactly what errors my process encounters at the record level during testing, and measure the running time.

This database will also give you a place to trace what has, and has not, been loaded into Salesforce. More about how to implement this and drive performance to come.

Transform the Data

Using the tool of your choice, create a process to transform the data from the source data into your staging database. How you do this stage could be a series of posts by itself. For my ideas on a good process for this I suggest my Queries on Queries talk.

Your process will have a mountain of small details – I often describe it as “hard and boring”. Done well this is your best point in the process for testing your work. Test thoroughly! You should run this process so many times you lose count.

Salesforce Migration Keys

One important detail is that you will want to leave the main record Id field null. Your legacy Id goes into a legacy Id field, but the main Id field should be empty. We’ll use that in the loading stage to determine which records were successfully loaded and which need follow up attention.

Every object you are migrating should have a legacy Id field that links back to your source database. These should generally be text fields, set to be external Ids and unique. These fields will both help with the migration itself, but also the validation process – and should you need to, you will be able to update the data post-migration using those same keys.

To handle references between records use the legacy Ids as the lookup Id values. For example, on a Salesforce Contact there is an AccountId field to reference the parent account. The Account’s legacy Id should be in AccountId. Often this value is already in your foreign key fields so it can be a real time saver in your transformation build. We’ll see in a minute how we use those to resolve to new Salesforce Ids as we load data.

Data Cleaning

This is also the time and place to do whatever data cleansing you plan to do in your process. You can do that work post-launch as well (mostly). I highly recommend this cleansing be automated for large data sets. If you can’t automate it, do it pre-migration in your old system, or post-migration in Salesforce.

Pre-Load Data Validation

Using the staging database your transformed data can be fully validated before you load it.

• Check your references: Make sure all your lookup fields are populated with valid data.
• Check your record counts: Do you have the expected number of records in every table?
• Check your critical fields: All data points are created equal, but some are more equal than others. Check those a few extra times.

If you have the time and resources, you can write scripts and other automations to run these tests for you. The more the better.

Loading Salesforce

Finally, all that data you just transform and staged is ready for high volume loading. For each object you run two steps:

1. Insert the data via the Bulk API ( Insert not Upsert!), record the start and end time and all errors in your log table.
2. Update the records in your staging database to add the new Salesforce Id into the source record’s Id column (the one I told you to leave blank before).

When there are no null values left in the Id column, you have loaded all your data. If there are records that refuse to load, for any reason, you will know because the Id will be null. If you logged the errors you can see why.

You will also use those Ids in later jobs to update the reference Ids. Remember, we put the legacy Id into your reference fields, when you actually load the data you need to replace that legacy Id with the actual Salesforce Id.

When possible you should build these load jobs to only load records without a Salesforce Id already assigned. That will allow you to safely re-run the job if it encounters errors that lead to partial success (like record locking, see below).

Why Not Upsert?

People used to loading small amounts of data will be tempted to use Salesforce’s upsert command. The benefit is that it allows you to use those legacy Id values directly instead of swapping for the newly generated Id. But as record volumes grow, upsert performance drops – I’ve had projects where I measured it at ⅓ the speed of insert, I heard of projects where it got far worse than that. The larger the dataset, the more important it is to use Insert.

Playing Nice with Salesforce

To make sure your data loads correctly, and efficiently, there are three more important details you still need to plan for:

1. Automations and Sharing Rules
2. Object Load Order
3. Record Load Order

Automations and Sharing Rules

Automations take time to run, even small amounts of time add-up when loading large amounts of data. To the degree possible, you want automations off. Some automations you want to replicate in your transformation process – particularly if it’s a simple field value or record creation. Some automations you want to defer and run later, like custom roll up values via DLRS, NPSP rollups, or similar approaches. And some automations you cannot disable at all.

Sharing calculations in Salesforce are really a special-purpose automation. Just not one you often think about unless you’re doing manual sharing. Like all automations in Salesforce, the more data you load, the larger the impact of these calculations. Salesforce allows you to defer these calculations and run them in the future. The more complex your security setup, the more impact this will have (open security models can generally ignore this consideration).

The person doing the data loading needs to work with the folks that implemented those automations to map out which can be disabled, which can be deferred, and which must to be tolerated.

Object Load Order

In Salesforce, object load order is critical. You cannot disable or defer assignment of required references. So you need to understand the object hierarchy and relationships.

Generally you start with objects that have no dependencies: e.g. Account, Campaign, Product, Lead.

Then proceed to objects that have relationships to those: e.g. Contact

Then to objects that can have relationships to objects from that previous layer: e.g. Opportunity, Account Contact Relation, Campaign Member

When possible, test running two objects in parallel. What exact combination is most efficient will vary by org details and data volumes. My experience is that you will be able to run objects in 4-5 groups usually with two or three objects loading in parallel.

Ideally we’d just load records and not have to go back and update, but if there are circular references, or record hierarchies you’ll need to update records after insert. Plan that second pass into your sequence.

Users

Salesforce Users are a special case. If you have a security model where record ownership is important, you need to load Users first.  If you have an open security model, I recommend loading Users last – and the smallest number of Users possible.  Remember, Salesforce bans User deletion, so you must be as careful as possible about loading them.  I never like to load Experience Cloud Users if I can avoid it – 1,000’s of accounts that will never be used but cannot be deleted is sub-optimal.

Record Load Order and Record Locks

Salesforce has aggressive record locking to deal with concurrent edits and updates across relationships. Great for day-to-day operation; frustrating when you’re loading data.

The first place people often encounter this is when they go to load Opportunities. Opportunity bulk load can run into massive problems with Account records being locked because another Opportunity is being loading for the same Account in a parallel process. If you sort the records by the locking parent record you can often reduce, if not eliminate, your record locking issues.

• Sort Contacts and Opportunities by Account.
• Sort Campaign Member by Campaign.
• Some Objects benefit from sorting by multiple fields: e.g. Tasks which you want to sort by WhoId and WhatId.

Use Serial Mode only as a last resort. Serial mode is ⅕ the speed of Parallel mode most of the time. There are situations that call for it. But it should never be your default go-to solution. Try everything else first before resorting to serial mode. Since you have tracking of which records were loaded or failed, if you design your load job carefully you can just re-run to resolve small numbers of record locks.

Extra Sorting Trick:

It turns out, in many cases the way data gets entered over time will gather it in useful patterns. So sorting data by a date field can radically reduce record lock contention. If you cannot figure out what field to sort by (often because sorting by field 1 causes locking issues on another object) try sorting by a date field and see if that helps.

Warning: depending on your data patterns, it can make the problem vastly worse too.

Mock Runs

A mock run is a test load into a sandbox that should involve you going through all the steps to load the data – starting with extracting it from the source system.

I personally recommend at least two full test mocks of your process.

If you’re working on a tight budget that may not be feasible (migrations are the first place project leaders trim budgets, and the first place users complain about errors), but that doesn’t mean multiple tests aren’t valuable.

The first test will go poorly, but you’ll learn a lot. The second test will, hopefully, go far better, but you will still learn a great deal.

In your testing you should expect to find places where your mappings are wrong, your transformations are incorrect, your testing is inadequate, your load order doesn’t work, you have source data patterns not accounted for, and more. Make time for good testing, you’ll thank yourself later.

Final Considerations

Large volume data loading in Salesforce is a deep topic. For all this is a long article, I’ve left out a lot of details. I designed this pattern to support high speed loads, rigorous testing, and error recovery. But within each of step of this pattern I could write articles this long or longer. You should continue to research the topic and adapt your implementation to your project.

A few sample topics you might consider:

• How to set audit fields.
• How to enable and disable triggers in production.
• Wipe and reload an org’s data.

You may even need to do something I’ve never encountered before.

But in any large volume Salesforce data load, the general pattern outlined here will serve you well.

If you’d like a breakdown of the content from Dreamforce, there are many better sources for that. Salesforce+, the plethora of blog posts written more quickly by people who went to more sessions. This is just my reflections on my experience.

For my first post-pandemic work trip it was a more than a little overwhelming. Dreamforce was supposed to have roughly 40,000 people. The largest professional in-person event I’ve been part of in 4 years was my wife’s department gathering at our house – I think 10-15 people came. This was a little bigger.

Networking is Still Most Important

For me the most important part of any professional conference is the networking. And you put 40,000 people together, there are going to be interesting people to meet.

I was able to spend time with old friends. Meet people in person I had previously met only online. And I got a chance to spend time with new colleagues.

Figuring out how to engage with that many people is a challenge for nearly anyone. Having not been to any conferences for awhile, it took me a little time to get my rhythm back.

Still, talking with other people who are active in the space is the best way to gain insights. Sure, I attending some workshops, and I did learn a few things in those. But sitting around playing cards with friends, or hearing people complain about bugs over drinks, is often far more informative. Not because those speakers aren’t good, but because they are speaking to a group in a polished way – of the cuff in a small group people share more details and reveal the hard earned lessons.

Sales and Client Meetings Are Fun

Working now for Coastal Cloud, which has people qualified to work on all the Salesforce products in all the industry verticals, meant I spent more time working our booth and visiting with clients than I would have in some of my more recent jobs.

On the one hand, standing around a sales booth, talking to people who really just want to see what swag you have on the table, isn’t a thrill a minute. But I learned early in my career that those conversations are just as much 1:1 networking as any other. And I like people, so talking to people is fun.

Not every organization would benefit from a booth at Dreamforce. But Coastal Cloud did (at least I think we did, other people are running those numbers), and it was fun to be part of that.

Dreamforce also attracted currently clients and potential clients we are already in the proposal stage with. I really like chances to talk to those people. Sometimes we talked about their projects, but more of the time was spent getting to know the larger context of their work. That means hearing about the work we’re empowering through our efforts. It also gives us all a chance to share personal information we might have otherwise missed.

Stuff I Could Have Done Better

In part because I changed job during critical window to arrange flights and hotels rooms, and in part due to lack of experience, I made terrible travel plans. I missed day zero entirely. So I missed the MVP Unconference, and some time with colleagues getting our stuff setup (I actually like basic physical setup projects). I also flew red-eyes out and back – I don’t know how I got through the second day I was there.

Next time I need to plan further ahead. Make sure I arrive on time for day zero. Make sure I have a reasonable flight there and make sure I have a reasonable flight home again.

I also didn’t play the swag game aggressively, and so I didn’t get as much “stuff” as some people. Frankly, I known I don’t need more stuff in my life, but somehow having still had room in my bag on the way home made me feel left out of something. Oh well.

To Sum Up My First Dreamforce

I met great new people. I got to spend time with friends. I learned new things. I have ideas for future projects. I helped support others. I had fun. I did not come home with COVID. I did not come home with DreamFlu.

On the whole, what more can one ask?

For a little over two years I’ve had the privilege of helping lead the Data Generation Toolkit Project for Salesforce. In general, Open Source projects are not known for their inclusive and supportive communities. I believe it is fair to say our project demonstrates that building a supportive community can yield great results.

Started by a question I wrote on a piece of paper in 2019 and posted to a wall, the project grows more every time I look around. That first meeting inspired the creation of Snowfakery and the recent training for Snowfakery has attracted more than 300 registrants. Contributors created documentation and presentations to help Salesforce admins learn to seed sandboxes. We are building a recipe library to help people starting out on Snowfakery. We launched two faker data providers. This year we reviewing and documenting other tools to generate and move Salesforce data.

More importantly we’ve built a project that is useful to the community, and supports new contributors to open source projects.

We did not get here accidentally. The project leadership wants to support the community members as much as create new tools. From the beginning we chose to encourage people unfamiliar with open source projects, contributions, and technologies.

Leading an Supportive Open Source Project

To be a supportive project starts with the leaders.

The project currently has seven identified leaders: Alisa Edwards, Allison Letts, Jung Mun, Paul Prescod, Samantha Shain, Cassie Supilowski, and myself. For those who like diversity statistics: that can be seen as 5 women, 2 men, 3 countries of residence, 3 counties of origin (not the same 3), 3 developers, 4 Salesforce admins, and at least 3 racial identities. No sub-group perfectly reflects its community, but that’s not a bad start in my opinion.

We have agreed that some of us lead specific sub-projects, while others tend to the health of the community. Everyone has a role.

When we started out with just 4 leaders either Paul (as creator and maintainer of Snowfakery) or I (as the person who started the project) could have dominated the project claiming founder status. Certainly men leading other open source projects have used that status to control the project direction. But Salesforce Open Source Commons projects are designed to discourage that behavior, and Paul and I embraced that design. Cori O’Brien created a wonderful space for our project to grow within.

Any open source project should focus on supporting its users. Our goal as a project is to support the Salesforce community – particularly nonprofit and education users. To do that we need the insights that only come from being open to outside ideas.

Our project’s leadership also established a pattern of self-review and reflection. Each year we will gather to discuss if the leadership group is the right size, and if anyone needs to step down. That creates a space for us to routinely reflect on what we’re doing and if we’re doing it well. The invitation to leave frees people from responsibilities they have to the project without frustration or burn out.

Recipes for Open Source Projects

Beyond our leadership team structure we also are intentional about how we encourage all contributors.

The project as a whole has space for all kinds of contributions. If someone wants to write documentation we will support them. When someone wants to learn to write recipes, we will work in pairs to get through the first one. People who want to write Python code for our faker providers get the chance to do that too.

We try to be kind to all contributors. We thank everyone when they open pull-requests or issues. Even I get thanked when I open a PR. Even if someone needs to make significant changes to a contribution before we commit it, we make sure to praise their effort.

These aren’t shit sandwiches. We genuinely appreciate all contributions and divorce that from any corrections that we request. As a long time open source contributor I am surprised at how much I appreciate the messages.

Maintaining Supportive Discussion Channels

Most open source maintainers know we have to maintain good ways for contributors to ask questions. Over time projects have used a wide variety of tools: IRC, News Groups, Email, issue trackers, and now Slack. In most projects those are the spaces that tend to become ugly. You see RTFM-style answers, personal criticisms, identity-based attacks, and other ugliness. The Slack channels for our project are a key piece of how we engage with each other, and support new contributors. We work hard to make sure people get timely answers, clear directions, and steady encouragement.

Our work falls within a community where our reputations matter and so there is a level of decorum absent in some open source projects. But no group is perfect and we will address issues when they arise. The open source common’s DEI Framework project will hopefully help us continue to deepen our understanding of the community. The kinds of attacks open source community spaces frequently allow in the name of good code, are simply unacceptable.

Come Join Us

The next community sprint for our project is coming up May 4th & 5th.

Thus I would like to introduce Electron Salesforce Base.

Like my generic project starter it is intended to be a jumping off point that handles some of the basic elements of a project.  It’s a bit more opinionated because comes with a little more plumbing in place – there is a simple interface and it’ll actually log into orgs (assuming you have your security token).

The interface is built using a Bootstrap dark theme from Bootswatch, and is set up to follow the Airbnb ESLint standards (with a couple small tweaks). The interface generates two windows, one that is meant to be the main interface and includes the controls to log into your org, and a second that is meant to keep a running log of events.

The main thread is fully isolated from the render threads, with all requests and data being passed back and forth using the current inter process communication methodology from Electron leveraging the IPCmain object in the main thread and the contextBridge in the render thread – there is no access to remote in the render thread (actually remote is fully disabled as it should be), and the preload.js file largely serves to filter IPC requests to maintain thread isolation. Currently the main thread of this project isn’t what I would call graceful, and I’m actually working on a refactor for ElectronForce to improve the IPC listener definitions (readers with examples of good design patterns are more than welcome to offer suggestions, whatever I settle on will likely get folded back into this project eventually).

To help understand the general pattern that’s emerging as people get better at sandboxing in Electron (and Electron gets better at demanded it) I find it helpful to think of Electron apps in a client-server model with two largely separate applications and a well defined API for communication between them. You’ll see that reflected here, and in my other recent Electron apps. You can implement whatever you’d like in each layer and just pass messages back and forth. This also means you can totally refactor one part of your application without worrying about the other. So if you hate my proto-interface dump it and build something better.

If you look at the code for this base project, then look at ElectronForce, you will see the render thread provides all the details of the interface – including use of render-friendly libraries like jQuery and a collection of helper functions to make life a little easier – makes an API call (with a filter list provided in preload.js), and then handles responses from the main thread. In main.js you see all the IPC listeners defined, which then pass the needed data to JSForce to make the API calls, before handing back structured data for the interface to render.

As you dig through the code you may notice various @TODO statements that are notes to myself about places with obvious room for improvement. I’m always happy to get suggestions, as comments here, issues there, or as pull requests to help resolve those notes with better solutions.

A recent support issue in the Salesforce issue queue asked for example code for writing queries. While I’ll address some of that here, there is ongoing work to replace the query interface to be more like Drupal core’s.  Hopefully once that’s complete I’ll get a chance to revise this article, but be warned some of those details may be a little out of date depending on when you read this post.

To run a simple query for all closed Opportunities related to an Account that closed after a specific date you can do something like the following:

      $query = new SelectQuery('Opportunity');
      $query->fields = [
        'Id',
        'Name',
        'Description',
        'CloseDate',
        'Amount',
        'StageName',
      ];
      $query->addCondition('AccountId', $desiredAccountId, '=');
      $query->conditions[] = [
        "(StageName", '=', "'Closed Won'",
        'OR', 'StageName', '=', "'Closed Lost')",
      ];
      $query->conditions[] = ['CloseDate', '>=', $someSelectedDate];
      $sfResponse = \Drupal::service('salesforce.client')->query($query);

The class would need to include a use statement for to get Drupal\salesforce\SelectQuery; And ideally you would embed this in a service that would allow you to inject the Salesforce Client service more correctly, but hopefully you get the idea.

The main oddity in the code above is the handling of query conditions (which is part of what lead to the forthcoming interface changes). You can use the addCondition() method and provide a field name, value, and comparison as lie 10 does. Or you can add an array of terms directly to the conditions array that will be imploded together. Each element of the conditions array will be ANDed together, so OR conditions need to be inserted the way lines 11-14 handle it.

Running a query in the abstract is pretty straight forward, the main question really is what are you going to do with the data that comes from the query. The suite’s main mapping features provide most of what you need for just pulling down data to store in entities, and you should use the entity mapping features until you have a really good reason not to, so the need for direct querying is somewhat limited.

But there are use cases that make sense to run queries directly. Largely these are around pulling down data that needs to be updated in near-real time (so perhaps that list of opportunities would be ones related to my user that were closed in the last week instead of some random account).

I’ve written about using Drupal 8 to proxy remote APIs before. If you look at the sample code you’ll see the comment that says: // Do some useful stuff to build an array of data.  Now is your chance to do something useful:

<?php

namespace Drupal\example\Controller;

use Symfony\Component\HttpFoundation\Request;
use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Cache\CacheableJsonResponse;
use Drupal\Core\Cache\CacheableMetadata;

class ExampleController extends ControllerBase {
    public function getJson(Request $request) {
        // Securely load the AccountId you want, and set date range.

        $data = [];
        $query = new SelectQuery('Opportunity');
        $query->fields = [
            'Id',
            'Name',
            'Description',
            'CloseDate',
            'Amount',
            'StageName',
        ];
        $query->addCondition('AccountId', $desiredAccountId, '=');
        $query->conditions[] = [
            "(StageName", '=', "'Closed Won'",
            'OR', 'StageName', '=', "'Closed Lost')",
        ];
        $query->conditions[] = ['CloseDate', '>=', $someSelectedDate];
        $sfResponse = \Drupal::service('salesforce.client')->query($query);

    if (!empty($sfResponse)) {
        $data['opp_count'] = $sfResponse->size();
        $data['opps'] = [];

        if ($data['opp_count']) {
            foreach ($sfResponse->records() as $opp) {
                $data['opps'][] = $opp->fields();
            }
        }
    }
    else {
      $data['opp_count'] = 0;
    }
    // Add Cache settings for Max-age and URL context.
    // You can use any of Drupal's contexts, tags, and time.
    $data['#cache'] = [
        'max-age' => 600,
        'contexts' => [
            'url',
            'user',
        ],
    ];
    $response = new CacheableJsonResponse($data);
    $response->addCacheableDependency(CacheableMetadata::createFromRenderArray($data));
    return $response;
  }
}

Cautions and Considerations

I left out a couple details above on purpose. Most notable I am not showing ways to get the needed SFID for filtering because you need to apply a little security checking on your route/controller/service. And those checks are probably specific to your project. If you are not careful you could let anonymous users just explore your whole database. It is an easy mistake to make if you do something like use a Salesforce ID as a URL parameter of some kind. You will want to make sure you know who is running queries and that they are allowed to see the data you are about to present. This is on you as the developer, not on Drupal or Salesforce, and I’m not risking giving you a bad example to follow.

Another detail to note is that I used the cache response for a reason.  Without caching every request would go through to Salesforce. This is both slower than getting cached results (their REST API is not super fast and you are proxying through Drupal along the way), and leaves you open to a simple DOS where someone makes a bunch of calls and sucks up all your API requests for the day. Think carefully before limiting or removing those cache options (and make sure your cache actually works in production).  Setting a context of both URL and User can help ensure the right people see the right data at the right time.

As of this writing the suite provides six usable field mapping types:

• Properties — The most common type to handle mapping data fields.
• Record Type — A special handler to support Salesforce record type settings when needed.
• Related IDs — Handles translating SFIDs to Drupal Entity IDs when two objects are related in both systems.
• Related Properties — For handling properties across a relationship (when possible).
• Constant — A constant value on the Drupal side that can be pushed to Salesforce.
• Token — A value set via Drupal Token.

There is a seventh called Broken to handle mappings that have changed and need a fallback until its fixed. The salesforce_examples module also includes a very simple example called Hardcoded the shows how to create a mapping with a fixed value (similar to, but less powerful than, Constant field).

These six handle the vast majority of use cases but not all.  Fortunately the suite was designed using Drupal 8 annotated plugins , so you can add your own as needed. There is an example in the suite’s example module, and you can review the code of the ones that are included, but I think some people would find an overview helpful.

As an example I’m using the plugin I created to add support for related entities to the webform submodule of the suite (I’m referencing the patch in #10 cause that’s current as of this writing, but you should actually use whatever version is most recent or been accepted).

Like all good annotated plugins to tell Drupal about it all we have to do is create the file in the right place. In this case that is: [my_module_root]/src/Plugins/SalesforceMappingField/[ClassName] or more specifically: salesforce_webform/src/Plugin/SalesforceMappingField/WebformEntityElements.php

At the top of the file we need to define the namespace, add some use statements.

<?php

namespace Drupal\salesforce_webform\Plugin\SalesforceMappingField;

use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\salesforce_mapping\Entity\SalesforceMappingInterface;
use Drupal\salesforce_mapping\SalesforceMappingFieldPluginBase;
use Drupal\salesforce_mapping\MappingConstants;

Next we need to provide the required annotation for the plugin manager to use. In this case it just provides the plugin’s ID, which needs to be unique across all plugins of this type, and a translated label.

/**
 * Adapter for Webform elements.
 *
 * @Plugin(
 *   id = "WebformEntityElements",
 *   label = @Translation("Webform entity elements")
 * )
 */

Now we define the class itself which must extend SalesforceMappingFieldPluginBase.

class WebformEntityElements extends SalesforceMappingFieldPluginBase {

With those things in place we can start the real work.  The mapping field plugins are made up of a few parts:

• The configuration form elements which display on the mapping settings edit form.
• A value function to provide the actual outbound value from the field.
• Nice details to limit when the mapping should be used, and support dependency management.

The buildConfigurationForm function returns an array of form elements. The base class provides some basic pieces of that array that you should plan to use and modify. So first we call the function on that parent class, and then make our changes:

 /**
   * {@inheritdoc}
   */
  public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
    $pluginForm = parent::buildConfigurationForm($form, $form_state);

    $options = $this->getConfigurationOptions($form['#entity']);

    if (empty($options)) {
      $pluginForm['drupal_field_value'] += [
        '#markup' => t('No available webform entity reference elements.'),
      ];
    }
    else {
      $pluginForm['drupal_field_value'] += [
        '#type' => 'select',
        '#options' => $options,
        '#empty_option' => $this->t('- Select -'),
        '#default_value' => $this->config('drupal_field_value'),
        '#description' => $this->t('Select a webform entity reference element.'),
      ];
    }
    // Just allowed to push.
    $pluginForm['direction']['#options'] = [
      MappingConstants::SALESFORCE_MAPPING_DIRECTION_DRUPAL_SF => $pluginForm['direction']['#options'][MappingConstants::SALESFORCE_MAPPING_DIRECTION_DRUPAL_SF],
    ];
    $pluginForm['direction']['#default_value'] =
      MappingConstants::SALESFORCE_MAPPING_DIRECTION_DRUPAL_SF;
    return $pluginForm;

  }

In this case we are using a helper function to get us a list of entity reference fields on this plugin (details are in the patch and unimportant to this discussion). We then make those fields the list of Drupal fields for the settings form. The array we got from the parent class already provides a list of Salesforce fields in $pluginForm[‘salesforce_field’] so we don’t have to worry about that part.  Since the salesforce_webform module is push-only on its mappings, this plugin was designed to be push only as well, and so limits to direction options to be push only. The default set of options is:

'#options' => [
    MappingConstants::SALESFORCE_MAPPING_DIRECTION_DRUPAL_SF => t('Drupal to SF'),
    MappingConstants::SALESFORCE_MAPPING_DIRECTION_SF_DRUPAL => t('SF to Drupal'),
    MappingConstants::SALESFORCE_MAPPING_DIRECTION_SYNC => t('Sync'),
 ],

And you can limit those anyway that makes sense for your plugin.

With the form array completed, we now move on to the value function. This is generally the most interesting part of the plugin since it does the work of actually setting the value returned by the mapping.

  /**
   * {@inheritdoc}
   */
  public function value(EntityInterface $entity, SalesforceMappingInterface $mapping) {
    $element_parts = explode('__', $this->config('drupal_field_value'));
    $main_element_name = reset($element_parts);
    $webform = $this->entityTypeManager->getStorage('webform')->load($mapping->get('drupal_bundle'));
    $webform_element = $webform->getElement($main_element_name);
    if (!$webform_element) {
      // This reference field does not exist.
      return;
    }

    try {

      $value = $entity->getElementData($main_element_name);

      $referenced_mappings = $this->mappedObjectStorage->loadByDrupal($webform_element['#target_type'], $value);
      if (!empty($referenced_mappings)) {
        $mapping = reset($referenced_mappings);
        return $mapping->sfid();
      }
    }
    catch (\Exception $e) {
      return NULL;
    }
  }

In this case we are finding the entity referred to in the webform submission, loading any mapping objects that may exist for that entity, and returning the Salesforce ID of the mapped object if it exists.  Yours will likely need to do something very different.

There are actually two related functions defined by the plugin interface, defined in the base class, and available for override as needed for setting pull and push values independently:

  /**
   * An extension of ::value, ::pushValue does some basic type-checking and
   * validation against Salesforce field types to protect against basic data
   * errors.
   *
   * @param \Drupal\Core\Entity\EntityInterface $entity
   * @param \Drupal\salesforce_mapping\Entity\SalesforceMappingInterface $mapping
   *
   * @return mixed
   */
  public function pushValue(EntityInterface $entity, SalesforceMappingInterface $mapping);

  /**
   * An extension of ::value, ::pullValue does some basic type-checking and
   * validation against Drupal field types to protect against basic data
   * errors.
   *
   * @param \Drupal\salesforce\SObject $sf_object
   * @param \Drupal\Core\Entity\EntityInterface $entity
   * @param \Drupal\salesforce_mapping\Entity\SalesforceMappingInterface $mapping
   *
   * @return mixed
   */
  public function pullValue(SObject $sf_object, EntityInterface $entity, SalesforceMappingInterface $mapping);

But be careful overriding them directly. The base class provides some useful handling of various data types that need massaging between Drupal and Salesforce, you may lose that if you aren’t careful. I encourage you to look at the details of both pushValue and pullValue before working on those.

Okay, with the configuration and values handled, we just need to deal with programmatically telling Drupal when it can pull and push these fields. Most of the time you don’t need to do this, but you can simplify some of the processing by overriding pull() and push() to make sure the have the right response hard coded instead of derived from other sources. In this case pulling the field would be bad, so we block that:

  /**
   * {@inheritdoc}
   */
  public function pull() {
    return FALSE;
  }

Also, we only want this mapping to appear as an option if the site has the webform module enabled. Without it there is no point in offering it at all. The plugin interface provides a function called isAllowed() for this purpose:

  /**
   * {@inheritdoc}
   */
  public static function isAllowed(SalesforceMappingInterface $mapping) {
    return \Drupal::service('module_handler')->moduleExists('webform');
  }

You can also use that function to limit a field even more tightly based on the mapping itself.

To further ensure the configuration of this mapping entity defines its dependencies correctly we can define additional dependencies in getDependencies(). Again here we are tied to the Webform module and we should enforce that during and config exports:

  /**
   * {@inheritdoc}
   */
  public function getDependencies(SalesforceMappingInterface $mapping) {
    return ['module' => ['webform']];
  }

And that is about it.  Once the class exists and is properly setup, all you need to do is rebuild the caches and you should see your new mapping field as an option on your Salesforce mapping objects (at least when isAllowed() is returning true).

FormAssembly provides a variety of great features for creating flexible forms that integrate with Salesforce. One of the more popular features is its ability to pull data from Salesforce to prefill fields on a form. But the downside is that it is easy to create forms that leak information from Salesforce into those forms, and create privacy risks.

To address this, FormAssembly allows 3rd party tools to securely sign URLs that contain parameters (often Salesforce IDs) that could be used to extract information through an iteration attack and other basic approaches. This secure signing process can be done statically but for most interesting projects you want to sign the URLs dynamically. The dynamic signing process allows you alter the parameters on the fly and set an expiration date to limit the value of a stolen link. Our project required this approach.

But the dynamic signing process has a couple sharp corners. First, it’s rarely done outside of Salesforce so there aren’t a lot of code samples around, and none that I could find in PHP.  Second, FormAssembly is very open and honest about the fact that they do not provide support on this feature. So I had to create my own process from the documentation they provide.  The docs are good, but very Salesforce centric, with all code samples in APEX.

The process involves preparing the data for signature, generating a HMAC-SHA256 with a form specific pre-shared key (in binary mode), converted to a string using base64, and finally URL encode the result.

Their convention for preparing the data is straightforward. You format all parameters as just their key and value strung together: key1Value1key2Value2

The interesting part is the actual HMAC-SHA256, which needs to be generated in binary mode, something that is often the default mode but not in PHP (in fact most PHP devs I’ve talked don’t realize the last parameter to hash_hmac() is useful, if you are doing this in another language check out this collection of examples).

From there you encode the output in base-64 (which results in a 44 character hash), and URL encode the hash to make sure it’s URL safe, and you’ll end up a few characters longer.

Finally you add you hash to the query string, and you’re ready to go.

To help anyone else who needs to do this, I generalized this part of the solution and I created and tossed it into Gist.