Apex Rollup

Getting Started

Create simple, fast, scalable custom rollups driven by Custom Metadata in your Salesforce org with Apex Rollup. Aggregate from any one object to another in an almost limitless amount of ways. Apex Rollup can not only mimic the standard Salesforce Master-Detail ROLLUP functionality (SUM, AVG, MIN, MAX) for Lookup relationships, Apex Rollup goes farther. Apex Rollup can count your related data, it can summarize your data by picking out the First or Last record based on conditions that you define. It can concatenate text together for you, and it can flag parent records if all, none, or some of that parent's children meet criteria. In addition, lookup relationships aren't a requirement for data aggregation: from being able to congregate the Contacts of an Account on an Opportunity to being able to being able to relate that one random Product SKU to any matching text on another record. Best of all? This functionality doesn't have to come from Apex! Apex Rollup works in Apex, Custom Metadata, Flows, and LWC.

Want to see examples of the magic? You can dive in depth on Replacing DLRS With Custom Rollup and on Unofficial SF. Looking to replace DLRS with Apex Rollup? We've even got that covered. We have a whole migration section, just for you!

Read below for more on how you can use Apex Rollup in your day-to-day. Please note that there are toggleable dropdown sections used frequently in this document. Keep your eyes peeled for sections entitled "Expand for ...", as tapping on those will produce much more in the way of documentation. If visual learning is more your style, make sure to check out the YouTube setup walkthroughs:

YouTube Video Tutorials

• Setup & Full Recalc Walkthrough
• Record Triggered Flow Setup
• Apex Setup with one line of code!
• Rollup Control custom metadata configuration
• Unit testing Apex Rollup

As well, don't miss the Wiki, which includes even more info for common topics like setting up Task/Event/User rollups.

Deployment & Setup

• For a namespaced version of Apex Rollup, check the installation links here
• Don't miss the links to install the Rollup plugins!.

Before proceeding further, Apex Rollup ships with a custom hierarchy setting, Rollup Settings, which you will have to create an Org Wide Default entry for by going to:

1. Setup
2. Custom Settings
3. Click Manage next to the Rollup Settings entry
4. Click New at the top to enter the Org Wide Defaults section - make sure Is Enabled is marked true and click Save

While you can still enable/disable individual rollups from running with the use of the Rollup Control CMDT (more details on that further on in the Readme), using a custom setting allows for several features that CMDT-based solutions currently lack:

• ease of installation/upgrade. Previously some users had issues when installing/upgrading due to pre-existing automation in their orgs interfering with the Apex Rollup tests
• granularity of control. Want to disable rollups from running for a specific user or profile? Easy as pie!

If you are writing your own Apex unit tests to validate that Apex Rollup is writing the values you expect for your rollups, please ensure you add the following snippet to your @TestSetup method:

@TestSetup
static void setup() {
  upsert new RollupSettings__c(IsEnabled__c = true);
}

On the subject of unit testing rollups (which I highly recommend), since Apex Rollup runs asynchronously by default, you should also wrap the action(s) in your tests that you expect to call Apex Rollup in Test.startTest(); and Test.stopTest();.

Features

You have several different options when it comes to making use of Apex Rollup:

CMDT-based Rollup Solution

Custom Metadata Type (CMDT) records are the preferred way to configure and organize your rollups. There are some limitations to this approach, particularly for popular objects like Task and Event - if you don't see the object you'd like to use in either the parent or child dropdown(s), use the "Text" version of that field (eg Child Object (Text)).

Rollup Custom Metadata Field Breakdown

Configure Custom Orderings With Rollup Order By Metadata

Configure Rollup Settings with Control Metadata

Flow / Process Builder Invocable

Invoking the Apex Rollup process from a Flow is simple, and for most use-cases is the easiest way for admins to get started. If, however, you are using Account, Case, Contact or Lead as the parent for a rollup operation and merges on those objects are supported in your org, the best practice is instead going to be using the Apex trigger one-liner to implement Apex Rollup. Expand the Special Considerations section and then navigate to Parent Level Merges for more info.

This is also the preferred method for scheduling; while I do expose the option to schedule a rollup from Apex, I find the ease of use in creating Scheduled Flows in conjunction with the deep power of properly configured Invocables to be much more scalable than the "Scheduled Jobs" of old. This also gives you the chance to do some truly crazy rollups — be it from a Scheduled Flow, an Autolaunched Flow, or a Platform Event-Triggered Flow.

Considerations For Scheduled Flows

In order to prevent blowing through the Flow Interview limit for each day, it's important to note that the use of Apex Rollup with a specific SObject in the scheduled flow's start node will run a flow interview for every record retrieved. However, if the scheduled flow is run without a specific SObject having been selected in the start node, the process is bulkified successfully and you only consume a single flow interview per batch of records.

Perform Rollup on records Invocable Action

Perform Rollup__mdt-based rollup Invocable Action

Process Deferred Rollups Invocable

Used in conjunction with the Perform rollup on records or Perform Rollup__mdt-based rollup invocables above when the Defer Processing input is set to {!$GlobalConstant.True} (the default on the CMDT invocable, opt-in for the vanilla Perform rollup on records action). Kicks off the actual rollup process when there are rollups with deferred processing.

Full Recalc CMDT-driven Invocable

Run full recalculation rollups directly from flow by passing in a comma-separated input variable with the API names of Rollup__mdt records. Functionality contributed by @dschibster!

Calculating Rollups After Install

Use the included app and permission set (See Rollup App) permission set to uncover the Apex Rollup app - a single-page-application where you can manually kick off rollup jobs. This is important because Apex Rollup works on an ongoing basis; in order for your rollups to be correct, unless the child object you're starting to rollup has no rows when you implement Apex Rollup, a one-off full recalculation is necessary. Here's how you would fill out the page to get things started:

You can also kick off full recalculations by using your already-configured Rollup__mdt CMDT records:

In either case, if you fill out the form values or start the full recalculation via your selected CMDT records, the screen will lock until the rollup recalculation has finished. There's a small piece of text at the bottom with information about what the recalculation job's status is, and the screen will only unlock after it has either finished, failed, or been manually aborted by you.

Using The Parent Record Recalc Button

There is an included Lightning Web Component (LWC) that will show up in the "Custom" section of the Lightning App Builder under the heading Recalc Rollups Button. As promised, you can drop this button anywhere on a parent SObject's record flexipage to enable users to recalculate the rollups just for that parent on the fly:

Special notes on the recalc button

• It relies on your rollups being configured using the Rollup__mdt CMDT. Unfortunately this means that it won't work for Rollups that are configured via the base Invocable Action
• The button will not display on the flexipage at all until at least one Rollup__mdt.LookupObject__c field matches the SObject whose record flexipage you're dropping the button on
• The button will display even if a given parent record has no matching children associated with the rollup(s) in question.
• This particular rollup runs synchronously, so it won't eat into your Asynchronous Job limits for the day; it also refreshes any Aura/page-layout sections of the page (LWC-based sections of the page should update automatically).
• Editing Rollup__mdt records with a parent record's page open can lead to unexpected behavior. This is because the Rollup__mdt records are cached on page load, so any updates made to those records will require a page refresh prior to clicking the Recalc Rollup button
• Triggering recalcs from a grandparent record is supported, but polymorphic grandparents (for example, an Account rollup that starts from Task -> Opportunity -> Account through the WhatId is not yet supported).

Scheduled Jobs

I would highly recommend scheduling through Scheduled Flows.

That being said, Apex Rollup exposes the option to use Scheduled Jobs if that's more your style. You can use the following Anonymous Apex script to schedule rollups:

// Method signature: (String jobName, String cronExp, String query, String rollupObjectName, Evaluator eval)
Rollup.schedule(
  'My example job name',
  'my cron expression, like 0 0 0 * * ?',
  'my SOQL query, like SELECT Id, Amount FROM Opportunity WHERE CreatedDate > YESTERDAY',
  'The API name of the SObject associated with Rollup__mdt records configuring the rollup operation',
  null
);

That last argument - the null value - has to implement an interface called Evaluator (or it can just be left null). More on that below.

Note that the third argument - the String rollupObjectName should be one of two values:

• the API name of the object(s) where rollups are started from the parent (where Is Rollup Started From Parent on Rollup__mdt is checked off) OR
• the API name of the object(s) where rollups are started from the child object

In either case, the SOQL query needs to correspond to either the parent or the children records that you'd like to operate on.

Grandparent (Or Greater) Rollups

Custom Apex Rollups

Migrating from DLRS

If you are converting from DLRS to Rollup, you can automatically convert all of your DLRS rules using the included Apex scripts:

1. scripts/convert-dlrs-rules.apex. Simply run this script in your org, and most DLRS rules (stored in dlrs__LookupRollupSummary2__mdt) will be converted to Rollup__mdt records and automatically deployed to the current org. There are exclusions as described in the Notes On The Use Of CMDT To Control Your Rollups, for these the script will write out how to implement the flow action equivalent in the debug logs for more information see here.
2. scripts/deactivate-converted-dlrs-rules.apex. Once you've converted your dlrs__LookupRollupSummary2__mdt records into Rollup__mdt records, you can run this script to deactivate any converted DLRS rules in the current org. Please note that this script does not delete the existing DLRS rules, nor does it uninstall DLRS for you - after running it, you'll still have to clean up and remove DLRS from your org.

Special Considerations

Rollup Plugins

Rollup Logging Plugins

You have several options for custom logging plugins for Rollup (all Rollup Plugin CMDT records should point to the Org_Default Rollup Control record). It's possible to use all of these options simultaneously - log to all the places!

1. Nebula Logger is an extremely popular open-source logging library. If you use Nebula Logger, you can install the rollup logging adapter for using Nebula Logger!
2. A lightweight custom logger that's also part of this repository; it's just bundled as a separate unmanaged package
3. Using the classic Apex debug logs - by adding an entry in the Rollup Plugin CMDT (Setup -> Custom Metadata Types -> Manage Records next to Rollup Plugin -> New) with the Rollup Plugin Name set to RollupLogger (included by default; can be removed)
4. If logging to the debug logs is enough for your purposes, use option #3. However, if you want to customize things further, or log errors to your own custom object/external logging destination (like Rollbar or Loggly), you can do so! The included RollupLogger class also includes an interface:

public class RollupLogger {

  public interface ILogger {
    void log(String logString, System.LoggingLevel logLevel);
    void log(String logString, Object logObject, System.LoggingLevel logLevel);
    void save();
    ILogger updateRollupControl(RollupControl__mdt control);
  }
}

You can implement RollupLogger.ILogger with your own code and specify that class name in the Rollup Plugin CMDT records. Alternatively, you can also extend RollupLogger itself and override its own logging methods; this gives you the benefit of built-in message formatting through the use of the protected method getLogStringFromObject, found in RollupLogger.cls. For more info, refer to that class and its methods. Either way, the API name for the CMDT record must include Logger in order to work (eg: RollupCustomObjectLogger, RollupNebulaLoggerAdapter).

You can use the included Rollup Plugin Parameter CMDT record Logging Debug Level to fine-tune the logging level you'd like to use when making use of Apex debug logs (from method #3, above). Valid entries conform to the System.LoggingLevel enum: ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST. FINEST provides the highest level of detail; ERROR provides the least. INFO will provide a high-level overview, while DEBUG will contain data about individual parent records being rolled up. The granularity of the data logged will continue to get finer as you move towards FINEST as the logging level.

Other Rollup Plugins

• To perform additional asynchronous post-processing on the newly updated parent records, a "callback" plugin is also now available as a 2GP unmanaged package. For more information, check out the Readme, as there are a variety of options available when it comes to post-processing.

• To customize the Database.DMLOptions before records are updated, or to perform additional synchronous pre & post-processing on the newly updated parent records, you can add a Rollup Plugin Parameter CMDT record linked to the Rollup Pre And Post Updater Rollup Plugin record. By default, an implementation is included if your org would like to exclude rollup updates from being considered in validation rules by using $Setup.RollupSettings__c.BypassValidationRules__c = false, as this value will only be true when Apex Rollup is updating records. To use the default implementation, set the Value for the Plugin Parameter record linked to the Pre/Post Updater plugin to RollupSObjectUpdater.PreAndPostUpdater (or the namespaced version of that class name, please.RollupSObjectUpdater.PreAndPostUpdater if you are using the namespaced version of Apex Rollup). Otherwise, you can provide your own implementation so long as it implements RollupSObjectUpdater.IPrePostUpdater (or please.RollupSObjectUpdater.IPrePostUpdater for the namespaced version):

// in RollupSObjectUpdater
global interface IPrePostUpdater {
  void preUpdate(List<SObject> recordsToUpdate, Database.DMLOptions options);
  void postUpdate(List<SObject> recordsToUpate);
}

• If you need to generate additional test code coverage for apex-rollup (which might be necessary in a highly declarative org), you can install the Extra Code Coverage plugin, which automatically gets updated any time I make changes to tests here.

• To customize how updates are made to the parent-level records in Rollup, create a Rollup Plugin custom metadata record with the name field set to RollupCustomUpdater. Create an Apex class with the same name and implement the IUpdater interface from RollupSObjectUpdater:

public class RollupCustomUpdater implements RollupSObjectUpdater.IUpdater {
  public void performUpdate(List<SObject> recordsToUpdate, Database.DMLOptions options) {
      // do whatever you'd like, and don't forget to commit using
      // something like Database.update!
      // assuming you have a TriggerHandler framework with a static "disable" method
      // to bypass other logic
      TriggerHandler.disable();
      Database.update(recordsToUpdate, options);
      TriggerHandler.enable();
    }
}

Commit History

This repository comes after the result of dozens of commits on my working repository. You can view the full history of the evolution of Apex Rollup there.

Contributing

Covered in the Contributing doc.

Contact Info

Drop me a line, contact me online or start a discussion here with questions.