Merge pull request #1 from jamessimone/v0.0.1

v0.0.1 - Initial package version

.github/workflows/deploy.yml

@@ -1,5 +1,5 @@
 # Unique name for this workflow
-name: Rollup Release Status
+name: Round Robin Release Status
 
 on:
   push:

.gitignore

@@ -7,4 +7,5 @@ debug.log
 DEVHUB_SFDX_URL.txt
 tests/apex
 **/main/default/
-coverage/
+coverage/
+.vscode

.prettierignore

@@ -0,0 +1 @@
+sfdx-project.json

README.md

@@ -3,4 +3,87 @@
 [![Round Robin Release status](https://github.com/jamessimone/salesforce-round-robin/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/jamessimone/salesforce-round-robin/actions/workflows/deploy.yml 'Click to view deployment pipeline history')
 [![License](https://img.shields.io/npm/l/scanner.svg)](https://github.com/jamessimone/salesforce-round-robin/blob/main/package.json)
 
-Easy, configurable round robin assigner!
+## Deployment
+
+<a href="https://login.salesforce.com/packaging/installPackage.apexp?p0=04t6g000008SjNvAAK">
+  <img alt="Deploy to Salesforce"
+       src="./media/deploy-package-to-prod.png">
+</a>
+
+<a href="https://test.salesforce.com/packaging/installPackage.apexp?p0=04t6g000008SjNvAAK">
+  <img alt="Deploy to Salesforce Sandbox"
+       src="./media/deploy-package-to-sandbox.png">
+</a>
+
+<br/>
+<br/>
+
+Between Assignment Rules and OmniChannel, there are plenty of out-of-the-box options for how records get owners assigned to them in Salesforce. As always, there are also many things that require customization. As it has frequently been the case that a "round robin" assignment be part of companies' business rules, Salesforce Round Robin aims to easily add support for round robin-type assignments to both Flow and Apex.
+
+Here are some of the benefits to using this package:
+
+- Ease of setup. All you have to supply (via Flow or Apex) is which records qualify to be part of the round robin (e.g. which records are part of the "ownership pool") and the records you'd like to have owners assigned
+- Speed and transactional safety - there are many pitfalls with naive round robin implementations, but the biggest one is unfair assignment (where some owners receive more records than others). This skew is typically caused by the tracking for how owners have been assigned getting out of date with how many records each person has already received. This package takes advantage of Salesforce's Platform Cache to offer truly fair assignment.
+
+## Round Robin Assignment From Flow
+
+Something to be aware of when using Flow as the starting point - until Apex Invocable actions are supported from the "before create/update" part of Flow, one should be aware of the possibility for recursion when making use of the bundled invocable action with Record-Triggered Flows. Put simply - because this action can only be run _after_ create/update presently, any _other_ parts of your Flow(s) may run twice.
+
+Here's a basic look at what a simple Record Triggered Flow would look like using the action:
+
+![Simple record-triggered flow](./media/round-robin-record-triggered-flow.png)
+
+And then the configuration for the action:
+
+![Setting the invocable properties](./media/round-robin-inside-action.png)
+
+### Invocable Properties To Set
+
+- `Object for "Records to round robin" (Input)` - for Record-Triggered Flows, this should correspond to the object the flow is for. For anything else, this should correspond to the SObject name of the record collection you're looking to pass in
+- `Alternative to query: API name of class that implements RoundRobinAssigner.IAssignmentRepo` (optional) - for Flow developers working with Apex (or with Apex developers), you may have more complicated business rules for which Users or other records qualify to be used in the assignment than the Query property can provide you with. For advanced users only!
+- `Owner Field API Name - defaults to OwnerId` (optional) - which field are you looking to assign to? Not all objects have `OwnerId` as a field (the detail side of M/D relationships, for instance). Use the field's API Name for these cases.
+- `Query Id Field - defaults to Id if not supplied` (optional) - used in conjunction with the `Query To Retrieve Possible Assignees` property, below. If you are using the round robin assigner to assign lookup fields _other_ than `OwnerId`, this allows you to override which field is pulled off of the records that the `Query To Retrieve Possible Assignees` returns.
+- `Query To Retrieve Possible Assignees` (optional) - either this or `Alternative to query ...` must be provided! This query will pull back records - like Users - and grab their `Id` field (or the field stipulated using the `Query Id Field ...` property) that should be included in the "ownership pool" for the given round robin.
+- `Records To Round Robin` (optional, but should always be supplied) - set this equal to a collection variable that is either the output of a `Get Records` call, contains `$Record` in a Record-Triggered flow, etc ...
+- `Update records - defaults to false` (optional) - by default, the collection supplied via the `Records To Round Robin` property aren't updated; set this to `{!$GlobalConstant.True}` to have the action update your records with their newly assigned owners
+
+## Round Robin Assignment From Apex
+
+You have quite a few options when it comes to performing round robin assignments from Apex. I would _highly recommend_ performing round robin assignments in the `BEFORE_UPDATE` Apex trigger context so that owners are assigned prior to being committed to the database.
+
+Here are a few ways that you can perform assignments:
+
+- You can re-use the static method `FlowRoundRobinAssigner.assign` by creating synthetic `FlowRoundRobinAssigner.FlowInput` records
+- You can call use the bundled `QueryAssigner`:
+
+  ```java
+    // in a Trigger/ trigger handler class
+    RoundRobinAssigner.IAssignmentRepo queryRepo = new QueryAssigner('SELECT Id FROM User WHERE Some_Condition__c = true', 'Id');
+    RoundRobinAssigner.Details assignmentDetails = new RoundRobinAssigner.Details();
+    assignmentDetails.assignmentType = 'this is the cache key';
+    new RoundRobinAssigner(queryRepo, assignmentDetails).assignOwners(someListOfSObjectsToBeAssigned);
+  ```
+
+- Or you can supply an implementation of `RoundRobinAssigner.IAssignmentRepo` that retrieves the records that qualify for the ownership pool via the `getAssignmentIds` method:
+
+```java
+// inside RoundRobinAssigner:
+public interface IAssignmentRepo {
+  // note that the provided implementations of IAssignmentRepo
+  // don't make use of the "assignmentType" argument passed here,
+  // but this helps to decouple your logic for returning assignment Ids
+  // in the event that you want to provide a single implementation that
+  // can respond to multiple assignment types!
+  List<Id> getAssignmentIds(String assignmentType);
+}
+```
+
+The `assignmentType` property that comes from the invocable action (`FlowRoundRobinAssigner`) is always the `Object Type.Field Name`; so something like `Lead.OwnerId` for a typical Lead round robin.
+
+Note that the records are _not_ updated by default in `RoundRobinAssigner`; if you are updating a related list of records (where updating them in a `BEFORE_UPDATED` context wouldn't just persist the updated ownership values by default), you should call `update` or `Database.update` on the records after calling the assigner.
+
+## Additional Details & Architectural Notes
+
+Again, this package employs the usage of Platform Cache to ensure fairness across competing transactions. This means that Platform Cache must be _enabled_ in your org in order to successfully install the round robin package. By default, it creates a 1 MB partition within your org cache. That should be plenty for most use-cases; if you have a ton of _different_ round robin assignments you may need to bump that amount up in:
+
+- Setup -> Platform Cache -> Click "Edit" on the `RoundRobinCache` record -> Bump the amount to 2 under the `Provider Free` section

core/classes/AbstractCacheRepo.cls

@@ -4,16 +4,22 @@ public abstract class AbstractCacheRepo implements Cache.CacheBuilder {
   }
 
   public void updateCache(Object cachedItem) {
-    this.getPartition().put(this.getCacheKey(), cachedItem);
+    this.getPartition()?.put(this.getCacheKey(), cachedItem);
   }
 
   protected abstract String getCachePartitionName();
   protected abstract String getCacheKey();
   protected abstract Object populateCache();
 
   protected Object getFromCache() {
-    Cache.OrgPartition partition = this.getPartition();
-    return partition.get(this.getCacheBuilder(), this.getCacheKey());
+    Object cachedItem = this.getPartition()?.get(this.getCacheBuilder(), this.getCacheKey());
+    if (cachedItem == null) {
+      // the item is only null when there's an issue with the packaging org not properly
+      // creating the cache partition; in this case, we "know" what the value will be
+      // and can manually load it
+      cachedItem = this.populateCache();
+    }
+    return cachedItem;
   }
 
   protected virtual Type getCacheBuilder() {
@@ -23,13 +29,14 @@ public abstract class AbstractCacheRepo implements Cache.CacheBuilder {
     return Type.forName(className);
   }
 
-  private Cache.OrgPartition getPartition() {
+@SuppressWarnings('PMD.EmptyCatchBlock')
+private Cache.OrgPartition getPartition() {
     Cache.OrgPartition partition;
     try {
-      Cache.OrgPartition.validatePartitionName(this.getCachePartitionName());
       partition = Cache.Org.getPartition(this.getCachePartitionName());
     } catch (cache.Org.OrgCacheException orgCacheEx) {
-      partition = new Cache.OrgPartition(this.getCachePartitionName());
+      // do nothing - there seem to be some timing dependencies on when
+      // it's possible to use Platform Cache while packaging.
     }
     return partition;
   }

core/classes/FlowRoundRobinAssigner.cls

@@ -1,7 +1,10 @@
 global without sharing class FlowRoundRobinAssigner {
   @TestVisible
-  RoundRobinAssigner.IAssignmentRepo stubAssignmentRepo;
+  private static RoundRobinAssigner.IAssignmentRepo stubAssignmentRepo;
+  @TestVisible
+  private static Boolean hasBeenUpdated = false;
 
+  private static final Set<Id> PROCESSED_RECORD_IDS = new Set<Id>();
   private static final FlowRoundRobinAssigner SELF = new FlowRoundRobinAssigner();
 
   global class FlowInput {
@@ -22,18 +25,40 @@ global without sharing class FlowRoundRobinAssigner {
   @InvocableMethod(category='Round Robin' label='Round robin records')
   global static void assign(List<FlowInput> flowInputs) {
     for (FlowInput input : flowInputs) {
-      if (input.recordsToRoundRobin.isEmpty() == false) {
-        SELF.validateInput(input);
-        RoundRobinAssigner.IAssignmentRepo assignmentRepo = SELF.getAssignmentRepo(input);
-        RoundRobinAssigner.Details assignmentDetails = SELF.getAssignmentDetails(input);
-        new RoundRobinAssigner(assignmentRepo, assignmentDetails).assignOwners(input.recordsToRoundRobin);
+      if (input.recordsToRoundRobin?.isEmpty() == false) {
+        SELF.trackAssignedIds(input);
+        SELF.roundRobin(input);
       }
     }
   }
 
+  private void roundRobin(FlowInput input) {
+    this.validateInput(input);
+    RoundRobinAssigner.IAssignmentRepo assignmentRepo = this.getAssignmentRepo(input);
+    RoundRobinAssigner.Details assignmentDetails = this.getAssignmentDetails(input);
+    new RoundRobinAssigner(assignmentRepo, assignmentDetails).assignOwners(input.recordsToRoundRobin);
+    if (input.updateRecords) {
+      update input.recordsToRoundRobin;
+      hasBeenUpdated = true;
+    }
+  }
+
   private void validateInput(FlowInput input) {
     if (String.isBlank(input.queryToRetrieveAssignees) && String.isBlank(input.assignmentRepoClassName)) {
-      throw new IllegalArgumentException('Query To Retrieve Possible Assignees or API name of class implementing RoundRobinAssigner.IAssignment repo is required!');
+      throw new IllegalArgumentException(
+        'Query To Retrieve Possible Assignees or API name of class implementing RoundRobinAssigner.IAssignment repo is required!'
+      );
+    }
+  }
+
+  private void trackAssignedIds(FlowInput input) {
+    for (Integer reverseIndex = input.recordsToRoundRobin.size() - 1; reverseIndex >= 0; reverseIndex--) {
+      SObject record = input.recordsToRoundRobin[reverseIndex];
+      if (record.Id != null && PROCESSED_RECORD_IDS.contains(record.Id)) {
+        input.recordsToRoundRobin.remove(reverseIndex);
+      } else if (record.Id != null) {
+        PROCESSED_RECORD_IDS.add(record.Id);
+      }
     }
   }
 
@@ -55,19 +80,4 @@ global without sharing class FlowRoundRobinAssigner {
     details.ownerField = input.ownerFieldApiName;
     return details;
   }
-
-  private without sharing class QueryAssigner implements RoundRobinAssigner.IAssignmentRepo {
-    private final List<Id> validAssignmentIds;
-    public QueryAssigner(String query, String assignmentFieldName) {
-      Set<Id> assignmentIds = new Set<Id>();
-      List<SObject> matchingRecords = Database.query(query);
-      for (SObject matchingRecord : matchingRecords) {
-        assignmentIds.add((Id) matchingRecord.get(assignmentFieldName));
-      }
-      this.validAssignmentIds = new List<Id>(assignmentIds);
-    }
-    public List<Id> getAssignmentIds(String assignmentType) {
-      return this.validAssignmentIds;
-    }
-  }
 }

core/classes/FlowRoundRobinAssignerTests.cls

@@ -49,6 +49,7 @@ private class FlowRoundRobinAssignerTests {
   static void updatesRecordsWhenFlagIsPassed() {
     ContactPointAddress cpa = new ContactPointAddress(Name = 'updatesRecordsWhenFlagIsPassed');
     insert cpa;
+    cpa.OwnerId = null;
 
     FlowRoundRobinAssigner.FlowInput input = new FlowRoundRobinAssigner.FlowInput();
     input.updateRecords = true;
@@ -57,6 +58,7 @@ private class FlowRoundRobinAssignerTests {
 
     FlowRoundRobinAssigner.assign(new List<FlowRoundRobinAssigner.FlowInput>{ input });
 
-    System.assertEquals(UserInfo.getUserId(), [SELECT OwnerId FROM ContactPointAddress WHERE Id = :cpa.Id].OwnerId);
+    System.assertEquals(true, FlowRoundRobinAssigner.hasBeenUpdated);
+    System.assertEquals(UserInfo.getUserId(), cpa.OwnerId);
   }
 }

core/classes/QueryAssigner.cls

@@ -0,0 +1,16 @@
+public without sharing class QueryAssigner implements RoundRobinAssigner.IAssignmentRepo {
+  private final List<Id> validAssignmentIds;
+
+  public QueryAssigner(String query, String assignmentFieldName) {
+    Set<Id> assignmentIds = new Set<Id>();
+    List<SObject> matchingRecords = Database.query(query);
+    for (SObject matchingRecord : matchingRecords) {
+      assignmentIds.add((Id) matchingRecord.get(assignmentFieldName));
+    }
+    this.validAssignmentIds = new List<Id>(assignmentIds);
+  }
+
+  public List<Id> getAssignmentIds(String assignmentType) {
+    return this.validAssignmentIds;
+  }
+}

core/classes/QueryAssigner.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>54.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

core/classes/RoundRobinAssigner.cls

@@ -54,6 +54,9 @@ public without sharing class RoundRobinAssigner implements IThreadSafeCacheVisit
   }
 
   private Integer getNextAssignmentIndex(List<Id> assignmentIds, RoundRobin__c cachedAssignment) {
+    if (cachedAssignment.Index__c == null && assignmentIds.isEmpty() == false) {
+      return 0;
+    }
     Integer currentAssignmentIndex = SENTINEL_INDEX;
     for (Integer index = 0; index < assignmentIds.size(); index++) {
       Id assignmentId = assignmentIds[index];

core/classes/RoundRobinRepository.cls

@@ -1,6 +1,6 @@
 public without sharing class RoundRobinRepository extends AbstractCacheRepo {
   private static Map<String, RoundRobin__c> CACHED_ASSIGNMENTS;
-  private static final String SENTINEL_USER_INDEX = getSentinelIndex();
+  private static final String SENTINEL_OWNER_INDEX = getSentinelIndex();
 
   @SuppressWarnings('PMD.ApexCRUDViolation')
   public void accept(IThreadSafeCacheVisitor visitor, List<SObject> records) {
@@ -10,8 +10,6 @@ public without sharing class RoundRobinRepository extends AbstractCacheRepo {
       this.forceRefreshCache();
       this.accept(visitor, records);
     }
-    currentAssignment.LastUpdated__c = System.now();
-    upsert currentAssignment;
   }
 
   /** AbstractCacheRepo overrides */
@@ -48,21 +46,40 @@ public without sharing class RoundRobinRepository extends AbstractCacheRepo {
     this.updateCache(CACHED_ASSIGNMENTS);
   }
 
-  private Boolean commitUpdatedAssignment(RoundRobin__c updatedAssignment) {
+  @SuppressWarnings('PMD.ApexCRUDViolation')
+  private Boolean commitUpdatedAssignment(RoundRobin__c assignment) {
     Boolean wasCommitSuccessful = true;
     Map<String, RoundRobin__c> currentCache = this.getCachedAssignments();
     if (
-      currentCache.containsKey(updatedAssignment.Name) &&
-      currentCache.get(updatedAssignment.Name).LastUpdated__c > CACHED_ASSIGNMENTS.get(updatedAssignment.Name).LastUpdated__c
+      currentCache.containsKey(assignment.Name) &&
+      currentCache.get(assignment.Name).LastUpdated__c > CACHED_ASSIGNMENTS.get(assignment.Name).LastUpdated__c
     ) {
-      updatedAssignment = currentCache.get(updatedAssignment.Name);
+      assignment = currentCache.get(assignment.Name);
       wasCommitSuccessful = false;
     } else {
-      updatedAssignment.LastUpdated__c = System.now();
-      upsert updatedAssignment;
+      assignment.LastUpdated__c = System.now();
+      /**
+       * integration tests with after save Flows have shown something unfortunate:
+       * though the second (recursive) call to the assigner is spawned in a second transaction
+       * the RoundRobin__c.getAll() still doesn't contain the Id of the inserted record (for the times where the assignment
+       * is being run for the first time).
+       * That means that we can't just call "upsert", and instead have to do this goofy
+       * song and dance to ensure the Id is appended correctly
+      */
+      if (assignment.Id == null) {
+        List<RoundRobin__c> existingAssignments = [SELECT Id FROM RoundRobin__c WHERE Name = :assignment.Name];
+        if (existingAssignments.isEmpty() == false) {
+          assignment.Id = existingAssignments[0].Id;
+        }
+      }
+      if (assignment.Id != null) {
+        update assignment;
+      } else {
+        insert assignment;
+      }
     }
 
-    CACHED_ASSIGNMENTS.put(updatedAssignment.Name, updatedAssignment);
+    CACHED_ASSIGNMENTS.put(assignment.Name, assignment);
     return wasCommitSuccessful;
   }
 
@@ -77,7 +94,7 @@ public without sharing class RoundRobinRepository extends AbstractCacheRepo {
         Name = assignmentType,
         // some sentinel value
         LastUpdated__c = Datetime.newInstanceGmt(1970, 1, 1),
-        Index__c = SENTINEL_USER_INDEX
+        Index__c = SENTINEL_OWNER_INDEX
       )
     );
   }
@@ -87,6 +104,6 @@ public without sharing class RoundRobinRepository extends AbstractCacheRepo {
   }
 
   private static String getSentinelIndex() {
-    return User.SObjectType.getDescribe().getKeyPrefix() + '0'.repeat(12);
+    return null;
   }
 }

core/classes/RoundRobinRepositoryTests.cls

@@ -17,13 +17,29 @@ private class RoundRobinRepositoryTests {
     );
   }
 
+  @IsTest
+  static void avoidsRecursiveUpdateIssues() {
+    Datetime someTimeAgo = System.now().addDays(-3);
+    upsert new RoundRobin__c(LastUpdated__c = someTimeAgo, Name = cacheKey);
+    RoundRobinRepository repo = new RoundRobinRepository();
+
+    Lead firstLead = new Lead();
+    Lead secondLead = new Lead();
+
+    repo.accept(new VisitorMock(), new List<SObject>{ firstLead });
+    repo.accept(new VisitorMock(), new List<SObject>{ secondLead });
+
+    RoundRobin__c updatedAssignment = [SELECT Id, Index__c FROM RoundRobin__c];
+    System.assertEquals(UserInfo.getUserId(), updatedAssignment.Index__c);
+  }
+
   private class VisitorMock implements IThreadSafeCacheVisitor {
     public String getVisitKey() {
       return cacheKey;
     }
     @SuppressWarnings('PMD.EmptyStatementBlock')
     public void visitRecords(List<SObject> records, SObject currentCacheRecord) {
-      // no-op
+      currentCacheRecord.put('Index__c', UserInfo.getUserId());
     }
   }
 }