The Documentor Documented (and Moar Detail)

This week I closed a couple of issues on the Org Documentor, and added some more flexibility around the output.

Moar Detail

The first issue was a request from Andy Ognenoff for some additional fields - relatively straightforward as three came straight from the CustomField metadata and one combined a couple of fields if the first was true. 

This gave rise to the need for a little more flexibility, as the pages started to get pretty wide with the number of columns and the length of the detail rendered. So the latest version of the plug-in allows you to configure the columns that will be displayed - at the group level, for all objects, or you can leave configuration alone and pick up the default of all columns.

Here's the configuration from my sample metadata repo:

"groups": {
    "events": {
        "name":"events", 
        "columns":["Name", "Label", "Type", "Description", "Info", "Page Layouts", "Encrypted"],
        "description": "Objects associated with events",
        "objects": "Book_Signing__c, Author_Reading__c"
    },
    "other": {
       "name":"other", 
       "columns":["Name", "Label", "Type", "Description", "Info", "Page Layouts", "Security", "Compliance", "In Use", "Encrypted"],
       "title":"Uncategorised Objects",
       "description": "Objects that do not fall into any other category"
    }
}

and the associated output, first for events, which just adds the Encrypted field (which is empty as I don't have Shield enabled!):

and then a new Email_Address__c field on the Author__c custom object, which includes compliance fields:

As always, you can view the output for the sample metadata on the public site.

The Documentor, Documented

The other issue that I finally got around to was documenting the configuration file. I used a Google Site for this, as I find them extremely easy to spin up and fill in. You don't get the same level of control that you would over something like Github pages, but if you want something out there quickly then they are hard to beat. There's not too much in there right now, mostly around setup and configuration, but more will come. If there's something that you particularly want to see, then create an issue in the Github repo and I'll see what I can do.

Updated Plug-in

Version 3.5.1 of the plug-in has this new functionality and can be found on NPM. 

If you already have the plug-in installed, just run sfdx plugins:update to upgrade to 3.5.1 - run sfdx plugins once you have done that to check the version.

The source code for the plug-in can be found in the Github repository.

Related Posts

• The plug-in on NPMJS
• Documentation generated from the sample metadata
• Sample metadata repository
• Plug-in source repository
• Org Documentor - Flag Non-Display Fields
• Org Documentor - Custom Header Colours
• Org Documentor - A Little More Configuration
• Org Documentor - Fields Usage in Page Layout
• Org Documentor and AuraEnabled Classes
• Documentor Plugin - Triggers (and Bootstrap)
• Documenting from the metadata source with a Salesforce CLI Plug-in - Part 5
• Documenting from the metadata source with a Salesforce CLI Plug-in - Part 4
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 3
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 2
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 1
• Offline mobile app template plug-in Dreamforce 18 session
• Salesforce CLI Play-by-Play
• Salesforce CLI Cheat Sheet

Follow @bob_buzzard

A Year Remote

Today (16th March 2021) marks the one year anniversary of BrightGen pivoting to a fully remote workforce. We knew it was possible, as we'd carried out a trial run the week before, but we didn't know how well it would scale, or indeed how long it would last for. It's pretty safe to say that none of us were expecting it to go on this long! The scaling worked surprisingly well - people's internet connection held up, kitchens and bedrooms were pressed into service as home offices, and we onboarded new joiners pretty seamlessly. Not perfect, and not everyone's first choice, but it was a very smooth transition.

For some, including me, the biggest challenge is stopping working from home turning into residing at your office. When you live and work in the same space, the boundaries become blurred, and if you have few distractions (because you are in the middle of a pandemic lockdown maybe) then it's easy to start working as soon as you get up and not stop until well into the evening. It's also easy to end up in a state of always on, where you check your email and instant messages every waking hour and jump straight into solving problems. This really can't scale, so you have to keep reminding yourself to take breaks and to set a time to switch off. The BrightGen team have done a great job of providing distractions, including virtual coffee breaks to mix us up and get us talking, pub and Kahoot quizzes, Taskmaster and more.

In the UK the vaccine rollout it is going surprisingly well, and confidence is growing that we will be able to open up the country on the government's target timeline including, at some point, our offices. This present us with an opportunity that doesn't come along too often - to redefine how work gets done. We've blown it all up for the last year, so we should spend some time thinking about how we can put it back together for everyone's benefit. The good news (in my opinion) is that simply going back to the way we worked before isn't going to happen. The genie is out of the bottle!

Follow @bob_buzzard

Subscribe to my Substack

The Substack Experiment

What is Substack?

I've been hearing a lot about Substack recently, mostly on technology podcasts and particularly on those that sit at the intersection of media and technology. In some quarters, Substack is seen as a way for writers/journalists to connect directly with their readers and monetise their output, and by all accounts some people are doing well with the top 10 newsletters bringing in $7 million a year.

I'm fairly certain that those writers didn't start from scratch on Substack - most of the stand out successes are well known writers with a large existing following and a great reputation. They brought their existing audience over with them, but have then been able to define their own price for access to their content and keeping around 85% of the money. They are also the first and have no doubt captured quite a bit of the audience that is prepared to pay, and if my experience with the Internet is anything to go by, there will be a limited set of giants and a large number scratching by. 

I suspect there's also going to be a limit to the number of separate subscriptions that anyone is prepared to pay. I don't know the specific numbers, but if I guess at $10/writer/month for the top tier, then subscribing to 10 quickly turns into real money, especially when compared to subscribing to traditional news media where you get access to a whole host of writers. Those that haven't decamped to Substack at any rate. By all accounts Substack expect to offer bundles, but based on writers wishing to bundle rather than pivoting to aggregation themselves.

I'd also have some personal concerns about limiting my reading in this way - it makes it far more likely that I'd descend into an echo-chamber and assume the whole world felt the same why I do about everything. I quite like reading things that I really disagree with, even if they make me angry sometimes, but if that took time away from the content I was paying for, I'd probably cut right down on it.

My Substack

All of this monetisation is very interesting, but in my case highly likely to be theoretical. I can't see myself trying to monetise my audience, particularly as the number of writers I would be prepared to subscribe to is a number pretty close to zero, and if I'm not doing it I can't really expect anyone else to. And, of course, clearly nobody would pay to read my ramblings, especially as I don't really know what I'm going to use it for.

I have signed up for Substack - in keeping with my history of creative names like the Bob Buzzard Blog you are currently reading, I've gone for the Bob Buzzard Stack - you can sign up to join me on the journey.

Right now I don't have a great sense of what I'm going to use it for, but as it's a regular newsletter it seems likely there will be links to things that interest me that I've found since the last issue, probably with some of my thoughts about those things or my opinion about something in the news. And they mystery of why I don't expect to monetise this deepens! 

I'll try to post regularly, but I make no promises about the cadence. Feast or famine seems the most likely outcome, but we'll see.

Why Substack?

Because it's there. Because it's popular. Because it's new and I like learning about new things. And because it's free - you only pay if you charge, and even then it's a cut of what you make rather than a flat fee.

I've tried other regular posting concepts before, like Medium Series, but I didn't really warm to the format and, maybe because of that, I didn't get a lot of interest. Series are deprecated now, so even if I wanted to continue with them I couldn't. I also added a News section to my Toolbox, but then it gets hard to provide easy access to the older links, and I didn't really want to build out a whole front end for it. 

My Substack may well go the same way, but you can't hit the ball if you don't swing, so I'm giving it a go.

Links

• Substack Home
• Bob Buzzard Stack

London Salesforce Developers Want Your Spring 21 Favourites

Since the UK went into first lockdown in March 2020, the London Salesforce Developers have met virtually over zoom. This works fine from the perspective of the talks and Q&A, but one area that is a real challenge to replicate is the casual conversations. Sometimes this is just general catch ups to talk about what we've been working on recently, which is something we can just about manage without. More problematic is that we aren't sharing the cool new features that we've just learned about, and that just isn't acceptable.

For that reason, our March 2021 event will be nothing but our members sharing their favourite feature from the Spring 21 release of Salesforce - we want to hear what you are excited about, and why!

So if you've spotted a hidden gem, sign up for our session on March 10th 2021 and tell us all about it. Don't delay - if someone else gets in before you, they'll get to talk about it!

You can sign up for the event here - once registered you'll need to fill in another form with details of what you want to talk about. You can also put in a backup choice or two, in case someone got in early and grabbed your favourite.

The event takes place on March 10th from 18:00 to 20:00 GMT - we'd love to hear from some internationals, so if you can make the timing work then please join us.

Follow @bob_buzzard

Spring 21 - AuraEnabled Apex and Sharing

(Updated 11/02 to fix typo on inherited sharing when Apex is invoked by starting a transaction. Mea culpa)

Introduction

The Spring 21 release of Salesforce includes an update that may change the behaviour of your Apex classes that are used as controllers for Aura or Lighting Web Components. If your org was created after the Spring 18 Salesforce release, or you activated the (now retired) update

   Use without sharing for @AuraEnabled Apex Controllers with Implicit Sharing 

then by default your controllers run as without sharing, which means that they don't take into account sharing settings for the user making the request and allow access to all records. 

Once Spring 21 goes live, the

   Use with sharing for @AuraEnabled Apex Controllers with Implicit Sharing (Update, Enforced)

will be applied and this behaviour will be reversed - the default will be with sharing and access will only be allowed for records owned by, or shared with, the user making the request. 

Why the Change

In a word, security. This update makes your components secure by default - if you forget to specify with sharing or without sharing, the principle of least privilege is applied and the most restrictive option is chosen. 

The absence of a sharing keyword can also be considered a sharing keyword

I'm really not a fan of acts of omission driving behaviour, especially when that behaviour isn't guaranteed. Prior to the Spring 21 release, if you don't specify the type of sharing, there's no way to tell by inspecting the code itself what will happen. Anyone debugging an issue around sharing would have to know when the org was provisioned, or find out whether the earlier update had been applied, always assuming they could get access to production to find out!

Historically, one reason to omit the sharing was to allow the code to inherit the sharing from it's calling Apex. This allowed a class to execute as though :

• with sharing is defined, if called from a class defined as with sharing
• without sharing is defined, if called from a class defined as without sharing

which gives a great degree of flexibility, with the trade-off that the exact same behaviour applies if you forgot the sharing declaration rather than intentionally excluded it. A comment to clarify the intent could help here, but that's something else to remember.

Inherited Sharing

Winter 19 made a great step forward for forgetful programmers with the introduction of the inherited sharing keyword. This explicitly states that the the class will inherit the sharing from the calling code, so no need for anyone to try to infer what the missing sharing keywords might mean.  

A slight wrinkle to this is what does inherited sharing mean when the calling code is not Apex - i.e. when it is the entry point for a transaction and thus executed by the Salesforce platform? A great example of this is an @AuraEnabled class used as a controller for an Aura or Lightning Web Component, aka where we came in to this post! 

The good news is that the Apex docs explicitly call this out - inherited sharing means with sharing when it is the entry point for a transaction - the principle of least privilege again, but clearly documented so that everyone knows what behaviour to expect.

Call to action

So do yourself and your team a favour, and when you are checking your @AuraEnabled classes to see if they will be affected by the Spring 21 update, if you find any without a sharing keyword, add one to make it clear what sharing is being applied. Your future self will thank you, and it also means that Salesforce can flip flop around what the absence of a sharing keyword should be and your code remains unaffected.

Related Posts

• Salesforce Flows, Triggers and CPU - One. More. Time.

Follow @bob_buzzard

Org Documentor - Flag Non-Display Fields

Introduction

Towards the end of 2020, I pushed an update to the Org Documentor plug-in to include details of the page layouts that a field is referenced in. When I posted this on Linked In, I got the following comment from Anand Narasimhan (a blast from the past from the early days of the CTA program) :

Which chimed with some of the comments I'd received when I was asked to add this, around helping to retire old fields that weren't used any more.  This didn't seem like it would take a huge amount of work to implement, so I added an issue to the Github repository and forgot about it until today.

Solution

It certainly didn't take a huge amount of effort. As detailed when adding the page layout reference information, I build up a map of the page layouts that reference a field keyed by the field name. As I'm building a complex JavaScript object to pass to the EJS templating framework, I add the list of page layouts to a field property named pageLayoutInfo.  It was then simply a matter of setting the background colour for the field if the pageLayoutInfo property was empty. The slight complication was that if the field has been determined to be in an error (missing description) or warning (todo, deprecated in the field description) then it would already have a background colour and I wanted to leave that in place. 

All told, this was 4 lines of code (could be reduced to 3 with a wider screen ;):

  if ( (!field.pageLayoutInfo) && 
       (''==field.background) ) {
     field.background='#f5dfea';  
  } 

I then added a field to the sample metadata that isn't present on any page layouts - Internal Description - and regenerated the report, which highlights the field in pink as expected:

Bonus Changes

In response to an issue raised from the community, I also added the ability to configure the name of the report subdirectory for a metadata type via the reportDirectory property in the configuration file. The sample repository has been updated to write the pages pertaining to the objects metadata to the objs directory. If you don't provide the reportDirectory property, it will default to the metadata type name - e.g. objects, triggers. I've also added an issue to document the configuration file properties, as right now there is an example file and I leave everyone to draw their own conclusions.

I also fixed a bug in the aura enabled pages that detail the Apex controller classes for aura components - if the component extended a super component it all went to hell, but now it handles that correctly.

Updated Plug-in

Version 3.4.6 of the plug-in has this new functionality and can be found on NPM. 

If you already have the plug-in installed, just run sfdx plugins:update to upgrade to 3.4.6 - run sfdx plugins once you have done that to check the version.

if you aren't already using it, check out the dedicated page to read more about how to install and configure it.

The source code for the plug-in can be found in the Github repository.

Related Posts

• The plug-in on NPMJS
• Documentation generated from the sample metadata
• Sample metadata repository
• Plug-in source repository
• Org Documentor - Custom Header Colours
• Org Documentor - A Little More Configuration
• Org Documentor - Fields Usage in Page Layout
• Org Documentor and AuraEnabled Classes
• Documentor Plugin - Triggers (and Bootstrap)
• Documenting from the metadata source with a Salesforce CLI Plug-in - Part 5
• Documenting from the metadata source with a Salesforce CLI Plug-in - Part 4
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 3
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 2
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 1
• Offline mobile app template plug-in Dreamforce 18 session
• Salesforce CLI Play-by-Play
• Salesforce CLI Cheat Sheet

Follow @bob_buzzard

How Often Should You Blog?

How often should you blog? This is a question that, while not often asked, has many answers. The reason it's not often asked is probably because you just have to wait a couple of days and it will pop up in one of the newsletters you somehow signed up for years ago and haven't got around to cancelling. The problem is, it will be answering the question from the perspective of someone else - maybe someone that is trying to grow an already large online following, sell online courses, or forge a new career as a writer. It might even be answered from the perspective of a company that is blogging as part of a marketing initiative.

Even if the answer is from someone trying to achieve the exact same thing that you are, they won't be you, shaped by your own experiences and subject to your own personal ups and downs. For this reason I would advise never following someone else's advice slavishly, but pick some approaches based on what appeals to you, and try a selection of them out. You should also apply this to my advice - it's typically based on what has (mostly) worked for me, and I'm not you. 

Every Day

I've seen a number of write ups from people who blog every day. Some reported less traffic, not more - readers deserted them as they weren't able to maintain the quality, or just got overloaded even though the blogger felt that their process had improved. Others found that their engagement went up, sometimes by as much as 1,000%, although the real success stories tend to be a few years ago, possibly because the platforms they were writing on were less crowded so a concerted effort could make a real difference.

Blogging every day definitely isn't for me, as I'm absolutely certain the quality would go downhill. It's easy to underestimate the effort required to write posts at a decent cadence, and I can't tell you the number of times I thought I had a series of 10+ posts on a topic, only to start running out of ideas by part 4 or 5. The only way I could make this happen is by flipping my blog to more of a journal, where I just write about my day, but I'd get bored with that before too long, never mind any readers. 

I am tempted though, as I'm curious if there's a point where it becomes easy to dash out a post during a coffee break, and if in the future I have less demands on my time I might try it. I probably won't try it out on this blog though, I'd likely create a new space on something like Medium, so as not to alienate my current audience. They are likely to be interested in Salesforce, software development and devops (maybe remote working right now), because that's what I've written about for the last decade, and probably wouldn't enjoy the change to a diary approach. That doesn't mean it won't work for you, so it might be worth a try if you think you can take the pace. Most of the accounts of daily blogging I read are about people experimenting with it for 1-3 months, but there are a few that stick with it for years. I doubt they are doing this on top of a day job and a demanding family life, but who knows.

Several Times a Week

Marketing Insider Group recommend 2-4 posts per week to get the top results in terms of traffic and conversions, but this is for companies that are trying to convert blog readers into customers. While I could aim for that, I'm not sure what I'd do with a customer, given the only thing I really have to sell is the Visualforce Development Cookbook.  2-4 posts per week is also a lot given that I'm writing them all myself, and I already have a full time job that consumes quite a bit of my time. I could probably do a couple of posts a week for a short period of time, but I feel like I'd run out of ideas after a few months. I'd also start to resent that I'd put myself in this position and view it as a chore, which never leads to good outcomes in creative endeavours.

Once a Week

This is what I aim for, and I must say it's quite easy to achieve during a pandemic. Looking back at my posts over the last 12 months, I was hitting more than one a week during the periods that we were locked down, or restricted in terms of travel. When we opened up, however, I dropped down to one or two a month as I had more pressing demands on my time.  

When I Have Something to Say

This is my sweet spot. Rather than putting pressure on myself to write at a particular cadence, and beating myself up when I inevitably fall behind, I write longer and more considered posts when I have something to say. If I have something to say then it will typically be about a topic that I am interested in or I care about or that I know a fair bit about. When it's all three, I can't get the words out fast enough, but even if it's one of them then the motivation is there. For a long time I didn't realise this though, and I experimented with a number of other approaches to see if I enjoyed them more, or if they had a positive effect. I reconsider my approach whenever I read a post about blogging every day, every week, or points in between, because what works for me now may not be ideal in a year or two. 

There does seem to be some level of agreement that blogging with a cadence can be helpful, but I'm not sure how well that applies to technical blogs like this one. I can't imagine that if I switched to posting every Friday that there would be a bunch of people out there waiting for the white smoke to indicate a new post had been published, which is why I tend to publish as soon as I'm happy with what I've written. Again, I've tried a number of different approaches to this, trying to find the days and times that get maximum engagement, and I've never really found it makes much difference. Your mileage may vary.

Follow @bob_buzzard