V0.0.2 - JavaDoc comments & Single Record Input for Flow (#2)

* Started adding in javadoc comments in a few places where it will help Apex consumers of the code. Removed a few lingering references to apex-rollup from copied files. Added definitionFile property to sfdx-project.json, though packaging still fails locally when attempting to revert AbstractCacheRepo to non-safeguarded version

* Wrapping some README text that was overflowing

* Finalizing v0.0.2 changes by adding single record input variable as per @rygramer's suggestion

Author: jamessimone

README.md

@@ -5,12 +5,12 @@
 
 ## Deployment
 
-<a href="https://login.salesforce.com/packaging/installPackage.apexp?p0=04t6g000008SjNvAAK">
+<a href="https://login.salesforce.com/packaging/installPackage.apexp?p0=04t6g000008SjOFAA0">
   <img alt="Deploy to Salesforce"
        src="./media/deploy-package-to-prod.png">
 </a>
 
-<a href="https://test.salesforce.com/packaging/installPackage.apexp?p0=04t6g000008SjNvAAK">
+<a href="https://test.salesforce.com/packaging/installPackage.apexp?p0=04t6g000008SjOFAA0">
   <img alt="Deploy to Salesforce Sandbox"
        src="./media/deploy-package-to-sandbox.png">
 </a>
@@ -44,7 +44,8 @@ And then the configuration for the action:
 - `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 ...
+- `Records to round robin - either this or single record is required` (optional) - 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 ...
+- `Single record to round robin - either this or records to round robin is required` (optional) - for Record-Triggered Flows, skip assigning `$Record` to a collection variable and just pass it directly using this input property!
 - `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
@@ -57,8 +58,10 @@ Here are a few ways that you can perform assignments:
 - 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');
+    // 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);

config/pmd-ruleset.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<ruleset name="Apex Rollup Rules"
+<ruleset name="Round Robin Rules"
     xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">

core/classes/AbstractCacheRepo.cls

@@ -7,6 +7,15 @@ public abstract class AbstractCacheRepo implements Cache.CacheBuilder {
     this.getPartition()?.put(this.getCacheKey(), cachedItem);
   }
 
+  /**
+   * We want to prevent downstream consumers from overriding `toString()`
+   * because otherwise they can break the way `getCacheBuilder()` works
+   * within this class
+   */
+  public override String toString() {
+    return super.toString();
+  }
+
   protected abstract String getCachePartitionName();
   protected abstract String getCacheKey();
   protected abstract Object populateCache();
@@ -29,8 +38,8 @@ public abstract class AbstractCacheRepo implements Cache.CacheBuilder {
     return Type.forName(className);
   }
 
-@SuppressWarnings('PMD.EmptyCatchBlock')
-private Cache.OrgPartition getPartition() {
+  @SuppressWarnings('PMD.EmptyCatchBlock')
+  private Cache.OrgPartition getPartition() {
     Cache.OrgPartition partition;
     try {
       partition = Cache.Org.getPartition(this.getCachePartitionName());

core/classes/FlowRoundRobinAssigner.cls

@@ -16,16 +16,18 @@ global without sharing class FlowRoundRobinAssigner {
     global String queryIdField = 'Id';
     @InvocableVariable(label='Owner Field API Name - defaults to OwnerId')
     global String ownerFieldApiName = 'OwnerId';
-    @InvocableVariable(label='Records to round robin')
+    @InvocableVariable(label='Records to round robin - either this or single record is required')
     global List<SObject> recordsToRoundRobin = new List<SObject>();
+    @InvocableVariable(label='Single record to round robin - either this or records to round robin is required')
+    global SObject recordToRoundRobin;
     @InvocableVariable(label='Update records - defaults to false')
     global Boolean updateRecords = false;
   }
 
   @InvocableMethod(category='Round Robin' label='Round robin records')
   global static void assign(List<FlowInput> flowInputs) {
     for (FlowInput input : flowInputs) {
-      if (input.recordsToRoundRobin?.isEmpty() == false) {
+      if (input.recordsToRoundRobin?.isEmpty() == false || input.recordToRoundRobin != null) {
         SELF.trackAssignedIds(input);
         SELF.roundRobin(input);
       }
@@ -49,6 +51,9 @@ global without sharing class FlowRoundRobinAssigner {
         'Query To Retrieve Possible Assignees or API name of class implementing RoundRobinAssigner.IAssignment repo is required!'
       );
     }
+    if (input.recordsToRoundRobin?.isEmpty() != false && input.recordToRoundRobin != null) {
+      input.recordsToRoundRobin = new List<SObject>{ input.recordToRoundRobin };
+    }
   }
 
   private void trackAssignedIds(FlowInput input) {

core/classes/FlowRoundRobinAssignerTests.cls

@@ -38,7 +38,7 @@ private class FlowRoundRobinAssignerTests {
     Exception ex;
     try {
       FlowRoundRobinAssigner.assign(new List<FlowRoundRobinAssigner.FlowInput>{ input });
-    } catch(System.IllegalArgumentException e) {
+    } catch (System.IllegalArgumentException e) {
       ex = e;
     }
 
@@ -54,11 +54,22 @@ private class FlowRoundRobinAssignerTests {
     FlowRoundRobinAssigner.FlowInput input = new FlowRoundRobinAssigner.FlowInput();
     input.updateRecords = true;
     input.recordsToRoundRobin = new List<ContactPointAddress>{ cpa };
-    input.queryToRetrieveAssignees =  'SELECT Id FROM User WHERE Id = \'' + UserInfo.getUserId() + '\'';
+    input.queryToRetrieveAssignees = 'SELECT Id FROM User WHERE Id = \'' + UserInfo.getUserId() + '\'';
 
     FlowRoundRobinAssigner.assign(new List<FlowRoundRobinAssigner.FlowInput>{ input });
 
     System.assertEquals(true, FlowRoundRobinAssigner.hasBeenUpdated);
     System.assertEquals(UserInfo.getUserId(), cpa.OwnerId);
   }
+
+  @IsTest
+  static void singleRecordRoundRobins() {
+    FlowRoundRobinAssigner.FlowInput input = new FlowRoundRobinAssigner.FlowInput();
+    input.recordToRoundRobin = new ContactPointAddress();
+    input.queryToRetrieveAssignees = 'SELECT Id FROM User WHERE Id = \'' + UserInfo.getUserId() + '\'';
+
+    FlowRoundRobinAssigner.assign(new List<FlowRoundRobinAssigner.FlowInput>{ input });
+
+    System.assertEquals(UserInfo.getUserId(), input.recordToRoundRobin.get('OwnerId'));
+  }
 }

core/classes/RoundRobinAssigner.cls

@@ -6,10 +6,21 @@ public without sharing class RoundRobinAssigner implements IThreadSafeCacheVisit
   private static final Integer SENTINEL_INDEX = -1;
   private static final String OWNER_ID = 'OwnerId';
 
+  /**
+   * Implement this interface to define an assignment "pool"
+   * for round robin assigning owners to records
+   */
   public interface IAssignmentRepo {
     List<Id> getAssignmentIds(String assignmentType);
   }
 
+  /**
+   * Data object designed to encapsulate one to two properties associated with assignment
+   * - assignmentType: also used as the cache key, this property is configurable.
+   *   In Flow, defaults to `SObjectType.OwnerFieldName`  (e.g. `Lead.OwnerId`)
+   * - ownerField: (optional), defaults to `OwnerId`. IT's not necessary for this field to be part of the cache key,
+   *   but it might be a nice way to differentiate entries in the cache in a consistent way
+   */
   public class Details {
     public String assignmentType { get; set; }
     public String ownerField {

integration-tests/testSuites/RoundRobinTestSuite.testSuite-meta.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexTestSuite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <testClassName>FlowRoundRobinAssignerTests</testClassName>
+    <testClassName>RoundRobinAssignerTests</testClassName>
+    <testClassName>RoundRobinFlowIntegrationTests</testClassName>
+    <testClassName>RoundRobinRepositoryTests</testClassName>
+</ApexTestSuite>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-round-robin",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Round robin records in Salesforce (SFDC) using Flow or Apex. Performant, fair, fast assignment with configurable user pools",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "prettier": "prettier",
     "scan": "sfdx scanner:run --pmdconfig config/pmd-ruleset.xml --target . --engine pmd --severity-threshold 3",
     "test": "npm run test:apex",
-    "test:apex": "sfdx force:apex:test:run -w 10",
+    "test:apex": "sfdx force:apex:test:run -s RoundRobinTestSuite -w 10",
     "test:lwc": "echo No LWCs so far!"
   }
 }

scripts/build-and-promote-package.ps1

@@ -13,17 +13,13 @@ function Get-Current-Git-Branch() {
 
 function Start-Package-Promotion {
   Write-Debug "Beginning promote script"
-
-  $allReadmes = Get-ChildItem -Exclude node_modules, .sfdx, tests | Get-ChildItem -Filter README.md -Recurse
-  foreach ($readme in $allReadmes) {
-    $readmePackageIdResults = (Select-String -Path $readme 'https:\/\/login.salesforce.com\/packaging\/installPackage.apexp\?p0=.{0,18}')
-    if ($readmePackageIdResults.Matches.Length -gt 0) {
-      $packageIdSplit = $readmePackageIdResults.Matches[0].Value.Split("=")
-      if ($packageIdSplit.Length -eq 2) {
-        $packageId = $packageIdSplit[1]
-        Write-Debug "Promoting $packageId from $readme"
-        npx sfdx force:package:version:promote -p $packageId -n
-      }
+  $readmePackageIdResults = (Select-String -Path "README.md" 'https:\/\/login.salesforce.com\/packaging\/installPackage.apexp\?p0=.{0,18}')
+  if ($readmePackageIdResults.Matches.Length -gt 0) {
+    $packageIdSplit = $readmePackageIdResults.Matches[0].Value.Split("=")
+    if ($packageIdSplit.Length -eq 2) {
+      $packageId = $packageIdSplit[1]
+      Write-Debug "Promoting $packageId from $readme"
+      npx sfdx force:package:version:promote -p $packageId -n
     }
   }
   Write-Debug "Finished package promotion!"

scripts/test.ps1

@@ -73,8 +73,8 @@ if($shouldDeployToSandbox) {
   try {
     # Deploy
     Write-Debug "Deploying source to sandbox ..."
-    npx sfdx force:source:deploy -p rollup
-    npx sfdx force:source:deploy -p extra-tests
+    npx sfdx force:source:deploy -p core
+    npx sfdx force:source:deploy -p integration-tests
     Start-Tests
   } catch {
     throw 'Error deploying to sandbox!'