4. Org clean up – deep clean

 After completing this unit, you’ll be able to:

  • Understand a more rigorous approach to clean up

This is similar to the approach suggested in the Org Documentation training

PREREQUISITESYou will need the Elements Catalyst Org Model (metadata dictionary) set up and there is a  14 day trial.


It is not realistic to look at your Org, which may have 10,000 or even 75,000 metadata items, and try to work out what everything does and document it. You know you would never get started. Just focusing on one area – i.e. all Apex Classes or all Process Builder Workflows – is also challenging as the customizations are so interconnected.

The best approach is to come at it from an operational perspective. Think of a Salesforce object and focus on how it works. For example, the Opportunity or Case object. Think about the lifecycle of an opportunity – from raised to closed won, or a case – from issue to resolution. Document that as a process diagram and find all the customizations related to making it work. Then take another area, “the lifecycle of an case” and document that.

So we have a simple 3-step approach that is practical, achievable and helps you make measurable process.

  1. HOW : How does this part of the Org/business work?
  2. WHAT : What did you change in Salesforce to support it?
  3. WHY : Why were changes made and where is the documentation that describes why and how you changed Salesforce?

 Here is a process diagram that describes that process. In the worked example you will be following this process to document the lifecycle of the Opportunity object

First you need to work out what area to focus on. So, take a small area that’s relevant to the work you are doing. You probably have a very clear view of the top 3 hit list. Here are some examples that we hear about from customers:

  • To migrate to Lightning we need to understand how to simplify page layouts, validation rules and automation, and fix the migration issues
  • Users are complaining about slow page loads and busy page layouts so we need to look at that Object and how to reduce the fields on the page layouts
  • We’ve reached field limits on Objects so need to work out which we can delete
  • So many of the reports have never been used. Which ones can we delete?
  • We are working through all the Apex triggers trying to understand their interactions and if they are all used
  • There are multiple process builder workflows that all seem to do the same thing

In this training we will map the Opportunity lifecycle as a process diagram; from qualified lead to closed opportunity. This is the HOW.

We are then going to create links from each step in the process diagram to the things that were used in Salesforce. This is the WHAT.

And then for each link we make we are going to add documentation. The WHY.

Don’t worry. This is a lot easier than you think.

Step 1. HOW

First the HOW.  This is all about understanding how the business operates and is best described as a simple process diagram. It is how the users use Salesforce to get their job done. It is how that automation or integration works behind the scenes.

The Opportunity process diagram

Here is the process diagram that describes the lifecycle of an opportunity. This is the drill down from the top level diagram.   You can see that each step also has drill downs to lower level diagrams. There is no limit to the number of levels that you can drill down.

Now you can understand the opportunity process that we have developed for you.  Your process is probably very different, so you can edit your copy. It is simple drag and drop.

The process diagram that you see above describes “a process”. It may not be the process that everyone follows. It may not be the process that everyone believes happens. The power of process mapping is getting shared agreement and then communicating the process to everyone. As you go through the mapping you will probably identified some quick wins.  This always happens when people start seeing the process and the handoffs between each other.

Don’t be scared if the diagram becomes large with 20+ activities. Later you can simplify by taking a group of activity boxes and “sending them to child” which means taking them and creating a lower level diagram.

Sometimes, where the process is well understood but not documented, this is really quick to do. In other cases, documenting the process highlights the fact that there is some disagreement how the process works (or should work) – and it takes a slightly longer.

But don’t underestimate the value of this mapping. We’ve got years of experience process mapping. Getting everyone on the same page – literally – is so empowering.

 Step 2. WHAT

You will go through the process diagram process step by step and ask the question “What in Salesforce do we use to deliver this step?”

To make the link you add an Org Model node to a process step. You find the node in the Org Model. This could be an object, field, page layout, email template, process builder workflow etc etc.  All the metadata in your Org – both core and managed packages – is in the Org Model tree structure.

In the right panel in the DOCUMENTATION tab click on “Copy node link”. Alternatively right mouse click on the node in the tree and select “Copy node link”.  This will save the node in the clipboard. Then go to the process step and right mouse click and select “Add links” and “Org Model Node”.

Don’t be surprised when you find the same nodes are linked to a number of different process steps and are used by different departments. This is where the Org Model becomes a critical resource for impact analysis for any new changes.

There is no “right and wrong” here, but decide on an approach and be consistent to help people leverage this. For example, many people link the highest levels of their process map to the Objects involved. e.g. the top level box with “Issue to Resolution” or “Resolve Customer Issue” is linked to Case object, but also, Account, contact, perhaps Opportunity and maybe some custom objects that support the process.

Then at the detailed level, individual steps may have links to validation rules, specific triggers, or a detailed automated activity that was created in Process builder or Flow. The details of “Why” that process builder was built in the way that it was may not be best described in a process step – hence step 3…

Step 3. WHY

For each node that you link to a process step, you will then need to add the “Why” documentation. Often the most valuable documentation is the Why. What was the thinking behind the configuration and why was it configured in that way?

As you start linking items in the Org Model to the processes, look for anything that was created that describes why changes were made and what was updated: requirements, user stories, process sketches, ERD/data models, videos, specifications, screenshots, wire diagrams, photos of whiteboards, notes, audio clips from the developer.

The mantra is “if you created it, link it”.

We know this is hard, so we are thinking of ways to make it feel easier and more immediate. We’ve built a mobile app, so you can take a photo when you are in the meeting and post it straight to the item in the Org Model, dictate a note using Siri or add a URL link. Just like we all do with social media (The mobile app is in beta and going through Apple AppStore review).

Link types


Documentation can just be notes. You discovered something about how this item was configured or why and you want a place to record it. Quickly add a note, bearing in mind that a note is tied to a single item in the Org Model.

Documentation in cloud storage: 

This the evidence of why you made those changes to Salesforce; Specifications, notes, photos of whiteboards, screenshots, wireframes, data models/ERD, URL links to wikis, apps and files in cloud storage, wireframe designs…and the list goes on. Documentation can be stored anywhere – GoogleDrive, Box, Sharepoint, GitHub, wikis, webpages. The links can be stored in our central URL Links Library to make it easier to use any URL link to multiple places. And if the URL destination moves, you only have one place to change it – in the library. Everywhere that references it is immediately up-to-date. This is really important if you are linking to screens in Salesforce and you are moved from one instance to another i.e. NA32 to NA69 or you implement MyDomain and then rebrand.


Add a screenshot or photo of a whiteboard.  These are compressed and stored against a Org Model item.  If you want to link to multiple items either save in cloud storage and use URL link (above) or just attach multiple places.

Metadata on metadata; 

Data tables are an extremely powerful feature. You can use them to add custom fields to any item in a Org Model and then report on the data. When you set up a data table, you define how you want the data to be entered. You add the data table form to the Org Model item and then you can capture data. You have control of the types of fields: free text, checkboxes, picklists, nested lists. You can even say which are mandatory to be filled in and which are optional.

For example: you want to capture which fields in objects are used in integrations with 3rd party systems. We have created a Data Table called “Salesforce Integrations”. There is another called “Salesforce Lightning Migration” where you can track the migration of any item. BTW, you can link a data table to any item in a Org Model (and also processes steps, requirements & user stories).

Data models/ERD

Ideally, the data models are drawn in Elements, then you can link them just like you linked process steps. But they could also be PDFs of Visio, Powerpoint, Draw.io, Lucidchart or photos of whiteboards stored in cloud storage. It doesn’t matter what the format is. What does matter is that the diagrams were drawn because a data model is arguably the FIRST thing you should be doing before you jump into customizing Salesforce.


Adding tags means you can report on items later, filter and sort. Tags could be “Release36” and could also be “delete” or “reviewed”. If you use tags to identify which items are used by departments you can use them to identify training needs. Tagging will also help you understand the conflicts in changes to any item. You can then report on items by tag and filter, sort and group on any column.

And any report can be exported to XLS. So, you can use this as dynamic release notes highlighting everything that will be changed in a release, and which parts of your organization are going to be impacted.


If you are going through and deleting metadata, you should be backing it up before you make the changes in case there is some impact that you have not considered and you need to roll back. Perhaps a field is used in a 3rd party integration that was not documented. Or is a key field in an Einstein prediction. OwnBackup is able to back your metadata and could be a life saver down the road.  ownbackup.com


You may need to do a number of these mini-projects to clean up parts of the Org.  But the key thing is to implement the other ideas in this training  – Impact Assessment & Org documentation – to make sure that you are staying in control of your Org.


NEXT: Great documentation habits