Learn MOAR in Spring ’20 with Tooling for the Dependency API

Join us and discover the new Spring ’20 Release features for developers. We know each release brings with it lots of amazing new functionality, and there can be a lot to digest. With Learn MOAR, we’re packaging the release and delivering feature highlights curated just for you.

Learn MOAR

It’s easy to get started. First, dive into the Trailhead Trailmixes with key release highlights for Admins or Developers, or both! (Don’t forget to hit Follow.)

Then, check in over the next few days (January xx) to read our favorite Spring ’20 Release features on both the Salesforce Admin and Salesforce Developer blogs.

Lastly, find your local Trailblazer Community Group and attend a meeting to learn about the release in person. Learn, network, and share your experience with us using #LearnMOAR.

Be sure to follow and complete the trailmixes by March 31, 2020 to earn a special community badge and unlock a $10 donation to FIRST®, a non-profit robotics community that prepares young people for the future.

We’re excited to announce the new Dependencies API in beta for the Spring ’20 release. This API helps you gather information about how the metadata in your Salesforce org is interconnected, which helps you to better understand and maintain your environments. In addition, we open sourced some helpful tooling that allows you to dig through the results of the API, which we’ll cover in this blog post.

Dependency management

When it comes to Salesforce development, no matter if you follow an org-based, package-based, or change set-based approach, you’ll have to identify your dependencies. It doesn’t matter if you’re a customer, a partner or ISV. Managing dependencies is hard on any platform, and without good tooling one might opt to include everything in a single large monolithic package instead. While that practice can work—we even coined the phrase “Happy Soup” to describe it—it does not make for great software development. That’s because Happy Soup limits:

feature adoption
code re-use
deployment agility
and backwards compatibility.

As your Salesforce org grows you’ll want to have great maintainability, avoid dead code, and orphaned objects. We encourage you to dig through the Dependencies API and learn what it provides. We also encourage you to try out the tooling, so you can learn first hand how it benefits your org environments.

The Dependencies API Plugin

To add the plugin to your existing SFDX CLI, get it from npmjs.com with

sfdx plugins:install dependencies-cli

Then you authenticate with your production org

sfdx force:auth:web:login

or your sandbox org

sfdx force:auth:web:login -r https://test.salesforce.com

and start using the plugin. For additional details see the README at our git repo.

The Dependencies API tool set is designed to help developers adopt new practices and move away from Happy Soup. We recommend you try the tooling first. Use the output of the plugin and a charting library, like D3.js, to gain insights around how to:

analyze package and object level dependencies in their orgs
untangle large monolithic orgs to split packages into smaller (more manageable) packages
identify and extract base packages with shared objects
and identify package level version dependencies.

Let’s review some scenarios to help you understand how tooling can improve dependency management.

Scenario 1 – Analyzing your deployed components

In the first scenario we inspect an existing org and run a component:report command from the dependency plugin. The output is a JSON file that includes all:

covered objects (as documented with the Metadata API)
relevant dependencies objects have on other objects.

The JSON file output represents a graph and can be rendered with many graphing tools and libraries, like Gelphi or D3.js.

We added a sample Node.js application with D3.js as an open source contribution to our code repo. The application is also running as an Heroku app called Metadata Dependency Graph.

Loading the JSON file produced above you can start to iterate through a process that allows you to untangle your large monolithic application by:

introspecting your org to understand object relationships
identifying objects shared by multiple domains, suitable to produce a shared base package with
identifying domain specific components, suitable to produce domain specific packages with
producing subgraphs for every base package and every domain specific package
replacing missing object references through package level references
and constructing package manifests for every subgraph.

Scenario 2 – Analyzing your package dependencies

In the process of breaking your Happy Soup into smaller packages, you’ll likely end up with multiple versions of your base and domain packages. Like all development this is a highly iterative process.

Semantic Versioning is widely considered the best practice for package versioning. In the project manifest sfdx-project.json you list all package level dependencies at their respective versions. And packages are just metadata components with unique Ids, one per package and version.
With sfdx dependency:package:version you can produce a directed graph suitable for rendering as an SVG and visualization of your package level dependencies. The package mode of the dependency plugin allows you to query and manipulate your package manifests.

While the graph is not interactive today, it’s possible to convert it to a JSON formatted output and load it with the Metadata Dependency Graph again. Fortunately, package dependency graphs are not as large as object dependency graphs and require fewer options to collapse or filter nodes as you can see here in the output of our Easy Spaces sample application.

Related Work

While the dependencies plugin is meant to provide tooling to analyze org metadata and metadata dependencies, the officially maintained APIs remain the Dependency API and the Metadata API. Multiple tools and methods have been developed already by the community around the Dependency API to date, including

Daniel Ballinger’s Understand your Org shape via visualization of Metadata Component Dependencies
Lucas Ennouchi’s A Journey with Salesforce DX Packages at Enterprise Scale

You’ll also find more information on the Salesforce Developer Blog, and from Salesforce product managers and developer evangelists, including Andrew Fawcett and René Winkelmeyer.

For a great writeup on how to build your own SFDX CLI plugin head over to Create Your First Salesforce CLI Plugin.

Your Next Steps

In this blog we reviewed just a few examples of how you can leverage the new Dependency API with our provided plugin. For all other functions of the plugin please refer to the context help and documentation. There are many ways to improve the plugin and you have a better understanding of your unique requirements.

For that very reason we decided to open source the project and open it up for community contribution. There are a number of ways for you to engage:

Use the latest released plugin version from npmjs.com
Raise issues related to the plugin code directly in GitHub. (For unrelated questions please work with your partner or success manager)
Clone the plugin code, which is MIT licensed, for unreleased versions and make your changes
Contribute your changes back to the repo by opening pull-requests (checkout our Code of Conduct first).

Some ideas for how you can help, include:

Export a package manifest directly from the graphing tool to include only selected objects/dependencies. This could go as far as test deploying the packages to find broken dependencies.
Build an npm style version dependency management for packages where we not only report version dependencies but compute a drift that warns of back level dependencies and upcoming incompatibilities. The drift could be computed based on major/minor changes for all packages based on Semantic Versioning

We can’t wait to see what you build!

About the Author

Holger Kache works as a Principal Member of Technical Staff at Salesforce. His current focus is on Salesforce Commerce Cloud where he works as an architect on a microservices platform lifted from a single monolithic “Happy Soup”. You can contact him on LinkedIn.