2. Metadata dictionary

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

  • Establish your metadata dictionary approach
  • Consider options to build metadata dictionary
  • Understand how to set up Elements Catalyst metadata dictionary

ANATOMY OF A METADATA DICTIONARY

The best approach is to build and maintain a metadata dictionary where each metadata item in your Salesforce Org(s) (and other systems) has all the related information stored centrally,  in context:

  • Summary
  • Descriptions
  • Created and last updated dates
  • Where used
  • Data population (for fields)
  • Requirements
  • User stories
  • Process maps
  • Notes
  • URL links
  • Specifications
  • Screenshots
  • Photos of whiteboards
  • Help topics
  • ie.  anything that is relevant

This means that the metadata dictionary is not just a listing of all the metadata items in your Org but it is also the central repository for all documentation about the changes that were made. Then it is quicker and easier to conduct the impact analysis to a level where changes can be made with confidence.

METADATA DICTIONARY REQUIREMENTS

Here are some considerations as you set up a metadata dictionary and the org configuration documentation:

  • Which Org metadata is the metadata dictionary created from – Production, one of your Sandboxes and your scratch DX Orgs?.
  • Which metadata types will the metadata dictionary track? It is just the core platform (sales/service cloud and managed packages) or external systems like Pardot, Marketing Cloud, Commerce Cloud and other apps that are integrated?
  • How do you keep the metadata dictionary in sync with the Orgs as new metadata items are created and what happens to the documentation if metadata is deleted? Metadata may be modified by your team, external consultants or by upgrades to Managed Packages.
  • How much “documentation” can be pulled from Salesforce using the MetadataAPI – description, summary, created date, last modified date – and how much can be generated automatically – whereused, risk assessment, field population
  • How do you get the documentation “flow” as metadata is migrated through the Sandboxes to Production, so it is only entered once? The aim is to create documentation when it is fresh in the mind, so as early as possible. If you leave it until later, it will not happen as easily
  • How do you get different teams, each working in their own Sandboxes and scratch DX Orgs to document their work? How do you merge the documentation so that each team can see what everyone else is doing? This is really important where they are working on the same objects concurrently.
  • Where are you going to manage and version control the Org documentation: requirements, user stories, process maps, notes, specifications, screenshots etc?
  • How do you report on the Org Documentation to speed up the impact assessment? How you want to use the Org documentation will determine how you structure and store it.
  • How do you control access to the people who can update, view, collaborate and report on the Metadata Dictionary and Org documentation? Is it just your Admins? What about developers and external consultants?
  • Can some of the Org documentation also be reused for end-user help? If so, how do you provide easy access from within the Salesforce record pages to the master versions of documentation?

TECHNICAL OPTIONS

There are several technical approaches that could be used that are free; spreadsheet, Quip document, custom object in Salesforce. However, the effort associated with trying to keep them in sync with changes to the Org are prohibitive. They also lack any analysis.

Which is why we developed Elements Catalyst. It provides a metadata dictionary that meets the above requirements and can deal with the most complex multi-org environments.

ELEMENTS CATALYST

You install a managed package into your Org and the sync will use the MetadataAPI to pull all in the metadata and build a metadata dictionary in Elements Catalyst. At the same time it will build a ton documentation and analysis for you, such as field %filled, field where used and field impact analysis.

There is a 14 day trial so you can see the power of a managed meta dictionary on your own Org data.

The Quick Start setup wizard is 3 clicks and takes 2-3 mins. The sync varies on the size and complexity of the Org. If you already have an Elements User Account you need to use Manual Setup. The Chrome Extension will enable you to see the meta dictionary in a right panel inside Salesforce Setup and also in a Record layout.

The sync, analysis and documentation will take between 10 mins and 2 hours to complete the first time, depending on how complex your Org is and whether it is a Production or Sandbox Org and Salesforce’s server loading.

NAVIGATING AROUND THE METADATA DICTIONARY 

If you have not sync’d your own Org, you can create a free Elements account  and view our demo Org Model

The Org Model may be the first time you’ve seen a perspective of your Org like this. The reaction may be “WOW”, “OMG” or “Ahhh, that’s why…”.   How big is your Org? We’ll give you a summary on the right panel.

Once the sync is complete you will get an email with a link so that you can open it up. You can also get to it in the Elements app which runs on the AWS platform, not inside Salesforce.  Go to http://Elements.cloud  or http://app.Q9elements.com/signin

Now you have logged into Elements Catalyst you need to open the Org Model. Select Salesforce Orgs in left menu. You will see just one Org Model listed but there could be multiple Org Models each one sync’d to a different Production or Sandbox Org. Click on the name of the Org Model to open it in a new browser tab.

ORG ANALYTICS REPORT

Resist the urge to start opening up the tree structure. Instead, click on the “Launch Salesforce Org Analytics” in the top bar to run the report. It gives you some powerful insights into your Org.The report opens up in a new tab in the browser and can be run at any time as it builds the report from the latest Org Model data. Let’s look at that first.

 

Take a quick look at the contents on the left of the report to see what is currently provided. Click on any item in the contents panel to go to that section. The report is interactive. You can filter and sort the graphs. This is more detailed than Salesforce Optimizer and is focused on the configuration of your Org and how well documented it is. The analysis in the Org Model and the Org Analytics report has been designed to help you focus your efforts on clean-up and documentation. It reduces the detective and analysis work for you.

NAVIGATING THE ORG MODEL EXPLORER VIEW

Let’s go back to the Org Model in the other tab and start to drill into the Org Model.  You can see that it is a tree structure and if you click on the arrow alongside any item (we call them nodes) you can expand it to see the next level of detail (child nodes) and so on down multiple levels.

The node has the name of the metadata item (e.g. the Object name) and in italics the description field is pulled from Salesforce, if a description field exists for that type of customization. Not everything in Salesforce has a description field, such as Apex Classes or Lightning pages.

The columns – Tags, Status, GDPR, # of links – can be dragged to change position and size.

You can automate the sync to run nightly. If an item in Salesforce is deleted, then the next time the sync runs the Org Model shows the Status as deleted but keeps it in the tree structure along with any documentation you may have linked to it.

ORG MODEL RIGHT PANEL

Top Level

Click on the top level of the Org Model (the top row of the tree “Salesforce Production”) and the right panel gives you an overview of all customizations in both the core and managed packages, if you have added managed packages to the sync. The right panel scrolls so you can see more information.  If you click on the SYNC HISTORY tab you can see the history of the previous syncs but you can also kick off a new sync from here.

For each node (metadata item)

For every node in the right panel there is are DETAILS, DOCUMENTATION and COMMENTS tabs.

DETAILS tab has the information that is available through the Salesforce APIs. It varies for each type of node in the Org Model. There is also a link to open up that customization in Salesforce Setup if a setup page exists for it.

DOCUMENTATION tab is where you can add documentation. This can be notes, URL links, Data Tables (metadata on metadata), process diagrams and requirements. More on this later.

COMMENTS is like a Chatter stream for every node where you can @mention colleagues.  BTW the free Viewer licenses allow posting of comments.

Open up the Objects section. There will be a Standard Objects section and if you have custom objects then there will be a Custom Objects section.

Example – custom object – Project

Click on an Object and the right panel gives a summary of the object including the number of records by record type. Just keep scrolling down the right panel to see “Records by Record Type” and “Field Impact Analysis” and “Help Topic Ratings”

DOCUMENTATION tab is where you can add documentation. This can be notes, URL links, Data Tables (metadata on metadata), process diagrams and requirements. More on this later.

 

 

Objects have an additional tab USAGE. This shows which fields (system, standard, custom) have data in them.  Remember all those custom fields that were asked for? Now you can see if they were even used. You can filter to just see Standard or Custom fields.

By default the analysis is done based on the last 10k record for every custom and standard field for every custom and standard object. There is an option to run the analysis on the last 1M or last 50M records by clicking on Update.

For analysis on managed packages you need to click Update %population in the right panel for each managed package.

Example – custom fields – Project object

In the right explorer view scroll down to fields and open up the list of fields.  Select a field.

 

 

Fields have several additional tabs;

  • USAGE shows how populated fields are by record type and also where fields are used.
  • ACCESS tab shows the field access by user for permission sets and profiles. This needs to be requested on demand as it is a huge analysis task.  That’s why it is not done for every field in every object every time the sync is run. There is a link in the tab to kick off the analysis and collect the data which is done asynchronously.
  • GDPR collects the data required for GDPR compliance (outside scope of this training – see other knowledge articles or engage with us at success@elements.cloud)

The USAGE and ACCESS analysis would be impossible to do manually and keep up-to-date.

INSIDE SALESFORCE SETUP

Every metadata item that can be opened in Salesforce Setup has small blue cloud icon which will launch a new tab in the specific page in Setup. This saves so many clicks, time and frustration. Plus the Elements Catalyst right panel is shown in the Salesforce Setup pages.

Here you can see the Elements right panel inside Salesforce Setup using the Chrome Extension.

INSIDE SALESFORCE RECORD PAGES

It is very difficult to remove fields from record pages with confidence because you don’t know if they are used. Often the field labels are not the same as the field API names which is doubly confusing. Consequently fields just keep being added so you end up with record pages that look like CVS receipts.  Click on the Chrome Extension icon in the browser top bar and select  “Show”. This pops the right panel in a record page so that you can inspect any field by clicking on the small Elements icon to the left of the field.

You see that this is only available in Classic as it is far easier for the Chrome Extension to work out the identity of the fields on a page layout in this view. Lightning pages can be highly configurable.  BTW This is only for Admins, so doesn’t impact your end users.

 

Next up, how you use the metadata dictionary to document your Org.

=======================================================================

NEXT: Org clean up – quick wins