Merged dev into feature/workflows-support

Feature/cleanup deprecated calls

.circleci/collect-jacoco-reports.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+############################################################################
+## Script to collect all JaCoCo reports from different modules into a
+## single directory for easier artifact storage in CI.
+############################################################################
+
+mkdir -p /home/circleci/jacoco-reports/
+
+##############################################################
+## Find all module directories that have target/site/jacoco ##
+##############################################################
+for module_dir in */; do
+  if [ -d "${module_dir}target/site/jacoco" ]; then
+    module_name=$(basename "${module_dir%/}")
+    target_dir="/home/circleci/jacoco-reports/${module_name}"
+    
+    echo "Collecting JaCoCo reports for module: ${module_name}"
+    
+    cp -r "${module_dir}target/site/jacoco" "${target_dir}"
+    
+    echo "Copied JaCoCo reports for ${module_name} to ${target_dir}"
+  fi
+done
+
+echo "All JaCoCo reports collected to /home/circleci/jacoco-reports/" 

.circleci/concatenate-test-output.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+############################################################################
+## Script to concatenate all .txt files in the surefire-reports directory
+## into a single artifact that can be stored in CI.
+############################################################################
+
+mkdir -p /home/circleci/test-output-artifacts/
+
+###################################################################
+## Find all module directories that have target/surefire-reports ##
+###################################################################
+for module_dir in */; do
+  if [ -d "${module_dir}target/surefire-reports" ]; then
+    module_name=$(basename "${module_dir%/}")
+    output_file="/home/circleci/test-output-artifacts/${module_name}-test-output.txt"
+    
+    echo "Processing module: ${module_name}"
+    echo "Output file: ${output_file}"
+    
+    ##################################################################
+    ## Concatenate all .txt files in the surefire-reports directory ##
+    ##################################################################
+    if [ -n "$(find "${module_dir}target/surefire-reports" -name "*.txt" -type f)" ]; then
+      echo "=== Test Output for ${module_name} ===" > "${output_file}"
+      echo "Generated at: $(date)" >> "${output_file}"
+      echo "==========================================" >> "${output_file}"
+      echo "" >> "${output_file}"
+      
+      ##############################################
+      ## Sort files to ensure consistent ordering ##
+      ##############################################
+      find "${module_dir}target/surefire-reports" -name "*.txt" -type f | sort | while read -r txt_file; do
+        echo "--- File: $(basename "${txt_file}") ---" >> "${output_file}"
+        cat "${txt_file}" >> "${output_file}"
+        echo "" >> "${output_file}"
+        echo "--- End of $(basename "${txt_file}") ---" >> "${output_file}"
+        echo "" >> "${output_file}"
+        echo "" >> "${output_file}"
+        echo "" >> "${output_file}"
+      done
+      
+      echo "Concatenated test output for ${module_name} to ${output_file}"
+    else
+      echo "No .txt files found in ${module_dir}target/surefire-reports"
+    fi
+  fi
+done 

.circleci/config.yml

@@ -5,35 +5,7 @@ orbs:
   browser-tools: circleci/browser-tools@1.4.7
 
 commands:
-  store_jacoco_site:
-    parameters:
-      module:
-        type: string
-    steps:
-      - store_artifacts:
-          path: << parameters.module >>/target/site/jacoco/index.html
-          when: always
-      - store_artifacts:
-          path: << parameters.module >>/target/site/jacoco/jacoco-resources
-          when: always
-
-  install_java17:
-    steps:
-      - run:
-          name: Install Java 17
-          command: |
-            sudo apt-get update
-            sudo apt install -y openjdk-17-jdk
-            sudo rm /etc/alternatives/java
-            sudo ln -s /usr/lib/jvm/java-17-openjdk-amd64/bin/java /etc/alternatives/java
-      - run:
-          ## used by jacoco uncovered class reporting in pom.xml
-          name: Install html2text
-          command: |
-            sudo apt-get update
-            sudo apt-get install -y html2text
-
-  mvn_verify:
+  mvn_build:
     steps:
       - checkout
       - restore_cache:
@@ -45,30 +17,41 @@ commands:
           name: Write .env
           command: |
             echo "RDBMS_PASSWORD=$RDBMS_PASSWORD" >> qqq-sample-project/.env
+      - run:
+          name: Run Maven Compile
+          command: |
+            mvn -s .circleci/mvn-settings.xml -T4 --no-transfer-progress compile
+      - save_cache:
+          paths:
+            - ~/.m2
+          key: v1-dependencies-{{ checksum "pom.xml" }}
+
+  mvn_verify:
+    steps:
+      - checkout
+      - restore_cache:
+          keys:
+            - v1-dependencies-{{ checksum "pom.xml" }}
       - run:
           name: Run Maven Verify
           command: |
-            mvn -s .circleci/mvn-settings.xml -T4 verify
-      - store_jacoco_site:
-          module: qqq-backend-core
-      - store_jacoco_site:
-          module: qqq-backend-module-filesystem
-      - store_jacoco_site:
-          module: qqq-backend-module-rdbms
-      - store_jacoco_site:
-          module: qqq-backend-module-api
-      - store_jacoco_site:
-          module: qqq-middleware-api
-      - store_jacoco_site:
-          module: qqq-middleware-javalin
-      - store_jacoco_site:
-          module: qqq-middleware-picocli
-      - store_jacoco_site:
-          module: qqq-middleware-slack
-      - store_jacoco_site:
-          module: qqq-language-support-javascript
-      - store_jacoco_site:
-          module: qqq-sample-project
+            mvn -s .circleci/mvn-settings.xml -T4 --no-transfer-progress verify
+      - run:
+          name: Collect JaCoCo reports
+          command: .circleci/collect-jacoco-reports.sh
+          when: always
+      - store_artifacts:
+          path: /home/circleci/jacoco-reports
+          destination: jacoco-reports
+          when: always
+      - run:
+          name: Concatenate test output files
+          command: .circleci/concatenate-test-output.sh
+          when: always
+      - store_artifacts:
+          path: /home/circleci/test-output-artifacts
+          destination: test-output
+          when: always
       - run:
           name: Save test results
           command: |
@@ -77,10 +60,6 @@ commands:
           when: always
       - store_test_results:
           path: ~/test-results
-      - save_cache:
-          paths:
-            - ~/.m2
-          key: v1-dependencies-{{ checksum "pom.xml" }}
 
   check_middleware_api_versions:
       steps:
@@ -91,8 +70,8 @@ commands:
         - run:
             name: Build and Run ValidateApiVersions
             command: |
-              mvn -s .circleci/mvn-settings.xml -T4 install -DskipTests
-              mvn -s .circleci/mvn-settings.xml -pl qqq-middleware-javalin package appassembler:assemble -DskipTests
+              mvn -s .circleci/mvn-settings.xml -T4 --no-transfer-progress install -DskipTests
+              mvn -s .circleci/mvn-settings.xml -T4 --no-transfer-progress -pl qqq-middleware-javalin package appassembler:assemble -DskipTests
               qqq-middleware-javalin/target/appassembler/bin/ValidateApiVersions -r $(pwd)
 
   mvn_jar_deploy:
@@ -108,7 +87,7 @@ commands:
       - run:
           name: Run Maven Jar Deploy
           command: |
-            mvn -s .circleci/mvn-settings.xml -T4 flatten:flatten jar:jar deploy:deploy
+            mvn -s .circleci/mvn-settings.xml -T4 --no-transfer-progress flatten:flatten jar:jar deploy:deploy
       - save_cache:
           paths:
             - ~/.m2
@@ -135,19 +114,25 @@ commands:
           when: always
 
 jobs:
-  mvn_test:
+  build:
+    executor: localstack/default
+    steps:
+      - mvn_build
+
+  test:
     executor: localstack/default
     steps:
-      ## - localstack/startup
-      - install_java17
       - mvn_verify
+
+  api_version_check:
+    executor: localstack/default
+    steps:
       - check_middleware_api_versions
 
   mvn_deploy:
     executor: localstack/default
     steps:
-      ## - localstack/startup
-      - install_java17
+      - mvn_build
       - mvn_verify
       - check_middleware_api_versions
       - mvn_jar_deploy
@@ -161,13 +146,31 @@ jobs:
 workflows:
   test_only:
     jobs:
-      - mvn_test:
+      - build:
           context: [ qqq-maven-registry-credentials, build-qqq-sample-app ]
           filters:
             branches:
               ignore: /(dev|integration.*)/
             tags:
               ignore: /(version|snapshot)-.*/
+      - test:
+          context: [ qqq-maven-registry-credentials, build-qqq-sample-app ]
+          requires:
+            - build
+          filters:
+            branches:
+              ignore: /(dev|integration.*)/
+            tags:
+              ignore: /(version|snapshot)-.*/
+      - api_version_check:
+          context: [ qqq-maven-registry-credentials, build-qqq-sample-app ]
+          requires:
+            - build
+          filters:
+            branches:
+              ignore: /(dev|integration.*)/
+            tags:
+              ignore: /(version|snapshot)-.*/
 
   deploy:
     jobs:

README.md

@@ -30,6 +30,20 @@ There are a few useful IntelliJ settings files, under `qqq-dev-tools/intellij`:
 One will likely also want the [Kingsrook Commentator
 Plugin](https://plugins.jetbrains.com/plugin/19325-kingsrook-commentator).
 
+## Test Logging
+By default, when ran from the command line, mvn surefire will make each test's
+output (e.g., System.out, err, printStackTrace, and all logger calls) go into a 
+file under target/surefire-reports/${className}.txt. 
+
+The system property `-DtestOutputToFile=false` can be given on the command line
+to get all of this output on the console.
+
+In the IDE (e.g,. IntelliJ), output goes to the Console.
+
+In CircleCI, output goes to files, and those files are concatenated together and 
+stored as artifacts.
+
+
 ## License
 QQQ - Low-code Application Framework for Engineers. \
 Copyright (C) 2020-2024.  Kingsrook, LLC \

docs/Introduction.adoc

@@ -91,7 +91,7 @@ And then having a bug in the check permission logic on the _Light Bulb Inventory
 No!
 
 All of the (really important, even though application developers hate doing it) aspects of security - you don't need to write ANY code for dealing with that.
-Just tell QQQ what Authentication provider you want to use (e.g., https://auth0.com/[Auth0]), and - to paraphrase the old https://www.youtube.com/watch?v=YHzM4avGrKI[iMac ad] - there's no step 2.
+Just tell QQQ what Authentication provider you want to use (e.g., OAuth2 or https://auth0.com/[Auth0]), and - to paraphrase the old https://www.youtube.com/watch?v=YHzM4avGrKI[iMac ad] - there's no step 2.
 QQQ just does it.
 
 ''''

docs/index.adoc

@@ -31,11 +31,9 @@ include::metaData/PermissionRules.adoc[leveloffset=+1]
 
 == Services
 
+include::misc/Javalin.adoc[leveloffset=+1]
 include::misc/ScheduledJobs.adoc[leveloffset=+1]
 
-=== Web server (Javalin)
-#todo#
-
 === API server (OpenAPI)
 #todo#
 

docs/misc/Javalin.adoc

@@ -0,0 +1,109 @@
+== QQQ Middleware:  Javalin web server
+include::../variables.adoc[]
+
+QQQ provides a standard implementation of a middleware layer - that is - code that exists between the
+QQQ backend and user interface.  This implementation is a web server built using the https://javalin.io/[Javalin framework],
+packaged and deployed in the `qqq-middleware-javalin` maven module
+
+The de facto way to create a QQQ application server is to write a class which uses an instance of one of the
+subclasses of `QApplicationJavalinServer`.
+
+For example, if your application metadata is defined in a directory of yaml files, your server class could be implemented as:
+
+[source,java]
+.ConfigFileBasedQQQApplication usage example
+----
+public static void main(String[] args)
+{
+   try
+   {
+      String path = "src/main/resources/metadata";
+      ConfigFilesBasedQQQApplication application = new ConfigFilesBasedQQQApplication(path);
+      QApplicationJavalinServer javalinServer = new QApplicationJavalinServer(application);
+      javalinServer.start();
+   }
+   catch(Exception e)
+   {
+      LOG.error("Failed to start javalin server.  See stack trace for details.", e);
+   }
+}
+----
+
+A similar class exists if your metadata is produced by a package of Java MetaDataProducer objects:  `MetaDataProducerBasedQQQApplication`.
+
+=== QApplicationJavalinServer
+This class provides the bridge between your QQQ Application (e.g., your metadata) and the QQQ Middleware layer
+served by a Javalin web server.  It has several properties to control behaviors:
+
+* `Integer port` - (default `8000`) - port to use for serving HTTP.
+* `boolean serveFrontendMaterialDashboard` - (default `true`) whether to serve the javascript frontend provided
+in the maven artifact `qqq-frontend-material-dashboard`.
+* `boolean serveLegacyUnversionedMiddlewareAPI` - (default `true`) whether to serve a version the original implementation
+of the QQQ middleware, which current version of `qqq-frontend-material-dashboard` are compatible with.
+* `List<AbstractMiddlewareVersion> middlewareVersionList` - (default contains `MiddlewareVersionV1`) - list of
+newer, formally versioned implementations of the QQQ middleware interface to be served.
+* `Consumer<Javalin> javalinConfigurationCustomizer` - (default `null`) - optional hook to customize the
+javalin service object before it is started.
+* `List<QJavalinRouteProviderInterface> additionalRouteProviders` - (default `null`) - list of fully custom
+implementations of `QJavalinRouteProviderInterface`, to add additional endpoints to the javalin server.
+** _Note, you may first want to consider using JavalinRouteProviderMetaData instead - see below._
+* `QJavalinMetaData javalinMetaData` - (default `null`) - optional alternative place to define `JavalinMetaData` (vs.
+defining it in the `QInstance`). _Note that if it is set in both places, the one in the QApplicationJavalinServer
+is used._
+
+=== JavalinMetaData
+Certain behaviors of a QQQ Javalin server are configured in a declarative manner by adding a `QJavalinMetaData`
+object to the `supplementalMetaData` in your `QInstance` (or, as mentioned above, by setting it directly on the
+`QApplicationJavalinServer`):
+
+* `List<JavalinRouteProviderMetaData> routeProviders` - (default `null`) optional list of custom route providers to
+add to the Javalin server.  See below for details.
+* `String uploadedFileArchiveTableName` - (default `null`) - reference to a QQQ Table in your application instance,
+needed to support the Bulk Load process, as well as any other processes which need to accept an uploaded file
+as input.
+* `boolean loggerDisabled` - (default `false`)
+* `Function<QJavalinAccessLogger.LogEntry, Boolean> logFilter` - (default `null`)
+* `boolean queryWithoutLimitAllowed` - (default `false`)
+* `Integer queryWithoutLimitDefault` - (default `1000`)
+* `Level queryWithoutLimitLogLevel` - (default `INFO`)
+
+==== JavalinRouteProviderMetaData
+This type of metadata allows you to add additional http route providers to your Javalin instance, e.g., for
+serving static files or for running custom code from your application (in the form of QQQ Processes) to respond
+to HTTP requests.
+
+* `String hostedPath` - (required)
+* `String fileSystemPath` - (required for a static router)
+* `String processName` - required for a dynamic, process-based router.  Must be a process name within the QQQ Instance.
+See below for additional details
+* `List<String> methods` - required list of HTTP methods (verbs) that are served by the route provider
+* `QCodeReference routeAuthenticator - Optional reference to a class that implements `RouteAuthenticatorInterface`,
+to provide security authentication to all requests handled by the route provider.
+** A default implementation is provided as `SimpleRouteAuthenticator`, which requires that a user session be present
+to access paths served by the route provider.
+
+===== Process-based route provider processes
+If you define a `JavalinRouteProviderMetaData` with a `processName` (e.g., to serve dynamic HTTP responses from your javalin
+server), the process that you implement will be called to respond to any HTTP requests received by the javalin
+server which match the `hostedPath` and `methods` that are specified in the metadata.
+
+The QQQ javalin server will marshal request data from the javalin context into the process's payload, conforming to
+the shape of the `ProcessBasedRouterPayload` class.  Similarly, the http response will be built by taking values from
+the process's output/state conforming to the fields in that class.  As such, it is recommended to use a
+`ProcessBasedRouterPayload`  instance, as show in this example:
+
+[source,java]
+.Process-based router usage example (including ProcessBasedRouterPayload)
+----
+public class MyDynamicSiteProcessStep implements BackendStep
+{
+   @Override
+   public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+   {
+      ProcessBasedRouterPayload payload = input.getProcessPayload(ProcessBasedRouterPayload.class);
+      String path = payload.getPath();
+      payload.setResponseString("You requested: " + path);
+      output.setProcessPayload(payload);
+   }
+}
+----

pom.xml

@@ -48,7 +48,7 @@
    </modules>
 
    <properties>
-      <revision>0.24.0</revision>
+      <revision>0.26.0-SNAPSHOT</revision>
 
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
@@ -59,6 +59,7 @@
       <coverage.instructionCoveredRatioMinimum>0.80</coverage.instructionCoveredRatioMinimum>
       <coverage.classCoveredRatioMinimum>0.95</coverage.classCoveredRatioMinimum>
       <plugin.shade.phase>none</plugin.shade.phase>
+      <testOutputToFile>true</testOutputToFile>
    </properties>
 
    <profiles>
@@ -141,6 +142,8 @@
             <configuration>
                <!-- Sets the VM argument line used when integration tests are run. -->
                <argLine>@{jaCoCoArgLine}</argLine>
+               <!-- Reduce console output for cleaner JUnit output -->
+               <redirectTestOutputToFile>${testOutputToFile}</redirectTestOutputToFile>
             </configuration>
          </plugin>
          <plugin>
@@ -244,30 +247,29 @@ if [ ! -e target/site/jacoco/index.html ]; then
 fi
 
 echo
-echo "Jacoco coverage summary report:"
+echo "Jacoco coverage summary report for module: ${project.artifactId}"
 echo "   See also target/site/jacoco/index.html"
 echo "   and https://www.jacoco.org/jacoco/trunk/doc/counters.html"
 echo "------------------------------------------------------------"
 
-if which xpath > /dev/null 2>&1; then
-   echo "Element\nInstructions Missed\nInstruction Coverage\nBranches Missed\nBranch Coverage\nComplexity Missed\nComplexity Hit\nLines Missed\nLines Hit\nMethods Missed\nMethods Hit\nClasses Missed\nClasses Hit\n" > /tmp/$$.headers
-   xpath -n -q -e '/html/body/table/tfoot/tr[1]/td/text()' target/site/jacoco/index.html > /tmp/$$.values
+# Parse Jacoco HTML coverage summary 
+if [ -f target/site/jacoco/index.html ]; then
+   echo -e "Instructions Missed\nInstruction Coverage\nBranches Missed\nBranch Coverage\nComplexity Missed\nComplexity Hit\nLines Missed\nLines Hit\nMethods Missed\nMethods Hit\nClasses Missed\nClasses Hit\n" > /tmp/$$.headers
+   sed 's/<\/\w\+>/&\n/g' target/site/jacoco/index.html | grep -A 12 '<tfoot>' | grep '<td' | sed 's/<td class="\w\+\d*">\([^<]*\)<\/td>/\1/' | grep -v Total > /tmp/$$.values
    paste /tmp/$$.headers /tmp/$$.values | tail +2 | awk -v FS='\t' '{printf("%-20s %s\n",$1,$2)}'
    rm /tmp/$$.headers /tmp/$$.values
 else
-   echo "xpath is not installed.  Jacoco coverage summary will not be produced here...";
+   echo "Jacoco coverage summary was not found.";
 fi
+echo "-----------------------------"
+echo
 
-if which html2text > /dev/null 2>&1; then
-   echo "Untested classes, per Jacoco:"
-   echo "-----------------------------"
-   for i in target/site/jacoco/*/index.html; do
-      html2text -width 500 -nobs $i | sed '1,/^Total/d;' | grep -v Created | sed 's/ \+/ /g' | sed 's/ [[:digit:]]$//' | grep -v 0$ | cut -d' ' -f1;
-   done;
-   echo
-else
-   echo "html2text is not installed.  Untested classes from Jacoco will not be printed here...";
-fi
+echo "Untested classes, per Jacoco for module: ${project.artifactId}"
+echo "-----------------------------"
+# Parse Jacoco XML reports directly to find classes with 0% coverage
+sed 's/<classs .*\?>/&\n/g;s/<\/class>/&\n/g' target/site/jacoco/jacoco.xml | grep -v 'counter type="CLASS" missed="0"' | sed 's/>.*//;s/.*\///;s/".*//'
+echo "-----------------------------"
+echo
 
                            ]]>
                         </argument>

qqq-backend-core/pom.xml

@@ -65,7 +65,11 @@
          <artifactId>aws-java-sdk-secretsmanager</artifactId>
          <version>1.12.385</version>
       </dependency>
-
+      <dependency>
+         <groupId>com.ibm.icu</groupId>
+         <artifactId>icu4j</artifactId>
+         <version>77.1</version>
+      </dependency>
       <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-databind</artifactId>
@@ -117,6 +121,11 @@
          <artifactId>poi-ooxml</artifactId>
          <version>5.2.5</version>
       </dependency>
+      <dependency>
+         <groupId>org.commonmark</groupId>
+         <artifactId>commonmark</artifactId>
+         <version>0.25.0</version>
+      </dependency>
 
       <!-- adding to help FastExcel -->
       <dependency>
@@ -125,10 +134,16 @@
          <version>2.16.0</version>
       </dependency>
 
+      <dependency>
+         <groupId>com.nimbusds</groupId>
+         <artifactId>oauth2-oidc-sdk</artifactId>
+         <version>11.23.1</version>
+      </dependency>
+
       <dependency>
          <groupId>com.auth0</groupId>
          <artifactId>auth0</artifactId>
-         <version>2.1.0</version>
+         <version>2.18.0</version>
       </dependency>
       <dependency>
          <groupId>com.auth0</groupId>
@@ -138,12 +153,12 @@
       <dependency>
          <groupId>com.auth0</groupId>
          <artifactId>jwks-rsa</artifactId>
-         <version>0.22.0</version>
+         <version>0.22.1</version>
       </dependency>
       <dependency>
          <groupId>io.github.cdimascio</groupId>
-         <artifactId>java-dotenv</artifactId>
-         <version>5.2.2</version>
+         <artifactId>dotenv-java</artifactId>
+         <version>3.2.0</version>
       </dependency>
       <dependency>
          <groupId>org.apache.velocity</groupId>
@@ -151,16 +166,21 @@
          <version>2.3</version>
       </dependency>
 
-      <!-- the next 2 deps are for html to pdf - per https://www.baeldung.com/java-html-to-pdf -->
+      <!-- the next 3 deps are for html to pdf -->
       <dependency>
          <groupId>org.jsoup</groupId>
          <artifactId>jsoup</artifactId>
          <version>1.15.3</version>
       </dependency>
       <dependency>
-         <groupId>org.xhtmlrenderer</groupId>
-         <artifactId>flying-saucer-pdf-openpdf</artifactId>
-         <version>9.1.22</version>
+         <groupId>com.openhtmltopdf</groupId>
+         <artifactId>openhtmltopdf-core</artifactId>
+         <version>1.0.10</version>
+      </dependency>
+      <dependency>
+         <groupId>com.openhtmltopdf</groupId>
+         <artifactId>openhtmltopdf-pdfbox</artifactId>
+         <version>1.0.10</version>
       </dependency>
 
       <!-- the next 3 deps are being added for google drive support -->

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/audits/AuditAction.java

@@ -291,6 +291,7 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
             /////////////////////////////
             InsertInput insertInput = new InsertInput();
             insertInput.setTableName("audit");
+            insertInput.setTransaction(input.getTransaction());
             insertInput.setRecords(auditRecords);
             InsertOutput insertOutput = new InsertAction().execute(insertInput);
 
@@ -318,6 +319,7 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
             {
                insertInput = new InsertInput();
                insertInput.setTableName("auditDetail");
+               insertInput.setTransaction(input.getTransaction());
                insertInput.setRecords(auditDetailRecords);
                new InsertAction().execute(insertInput);
             }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/audits/DMLAuditAction.java

@@ -124,6 +124,7 @@ public class DMLAuditAction extends AbstractQActionFunction<DMLAuditInput, DMLAu
          String contextSuffix = getContentSuffix(input);
 
          AuditInput auditInput = new AuditInput();
+         auditInput.setTransaction(input.getTransaction());
          if(auditLevel.equals(AuditLevel.RECORD) || (auditLevel.equals(AuditLevel.FIELD) && !dmlType.supportsFields))
          {
             ////////////////////////////////////////////////////////////////////////////////////////////////////////////

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/automation/CustomTableTriggerRecordAutomationHandler.java

@@ -0,0 +1,38 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.automation;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.automation.RecordAutomationInput;
+
+
+/*******************************************************************************
+ ** interface to be implemented by one that wishes to execute custom table triggers
+ *******************************************************************************/
+public interface CustomTableTriggerRecordAutomationHandler extends RecordAutomationHandlerInterface
+{
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   boolean handlesThisInput(RecordAutomationInput recordAutomationInput) throws QException;
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/automation/RecordAutomationHandler.java

@@ -22,19 +22,11 @@
 package com.kingsrook.qqq.backend.core.actions.automation;
 
 
-import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.automation.RecordAutomationInput;
-
-
 /*******************************************************************************
  ** Base class for custom-codes to run as an automation action
  *******************************************************************************/
-public abstract class RecordAutomationHandler
+@Deprecated(since = "0.26.0 - when RecordAutomationHandlerInterface was introduced")
+public abstract class RecordAutomationHandler implements RecordAutomationHandlerInterface
 {
 
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   public abstract void execute(RecordAutomationInput recordAutomationInput) throws QException;
-
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/automation/RecordAutomationHandlerInterface.java

@@ -0,0 +1,40 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.automation;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.automation.RecordAutomationInput;
+
+
+/*******************************************************************************
+ ** Interface for custom-codes to run as an automation action
+ *******************************************************************************/
+public interface RecordAutomationHandlerInterface
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   void execute(RecordAutomationInput recordAutomationInput) throws QException;
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/automation/RunCustomTableTriggerRecordAutomationHandler.java

@@ -0,0 +1,89 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.automation;
+
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.automation.RecordAutomationInput;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** RecordAutomationHandler implementation that is called by automation runner
+ ** that doesn't know to deal with a TableTrigger record that it received.
+ **
+ ** e.g., if an app has altered that table (e.g., workflows-qbit).
+ *******************************************************************************/
+public class RunCustomTableTriggerRecordAutomationHandler implements RecordAutomationHandlerInterface
+{
+   private static final QLogger LOG = QLogger.getLogger(RunCustomTableTriggerRecordAutomationHandler.class);
+
+   private static Map<String, QCodeReference> handlers = new LinkedHashMap<>();
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static void registerHandler(String name, QCodeReference codeReference)
+   {
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // if there's already a value mapped for this name, warn about it (unless it's for the same code reference) //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      if(handlers.containsKey(name))
+      {
+         if(handlers.get(name).getName().equals(codeReference.getName()))
+         {
+            LOG.warn("Registering a CustomTableTriggerRecordAutomationHandler for a name that is already registered", logPair("name", name));
+         }
+      }
+
+      handlers.put(name, codeReference);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void execute(RecordAutomationInput recordAutomationInput) throws QException
+   {
+      for(QCodeReference codeReference : handlers.values())
+      {
+         CustomTableTriggerRecordAutomationHandler customHandler = QCodeLoader.getAdHoc(CustomTableTriggerRecordAutomationHandler.class, codeReference);
+         if(customHandler.handlesThisInput(recordAutomationInput))
+         {
+            customHandler.execute(recordAutomationInput);
+            return;
+         }
+      }
+
+      throw (new QException("No custom record automation handler was found for " + recordAutomationInput));
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/automation/RunRecordScriptAutomationHandler.java

@@ -51,7 +51,7 @@ import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 /*******************************************************************************
  **
  *******************************************************************************/
-public class RunRecordScriptAutomationHandler extends RecordAutomationHandler
+public class RunRecordScriptAutomationHandler implements RecordAutomationHandlerInterface
 {
    private static final QLogger LOG = QLogger.getLogger(RunRecordScriptAutomationHandler.class);
 
@@ -83,7 +83,7 @@ public class RunRecordScriptAutomationHandler extends RecordAutomationHandler
       }
 
       QRecord scriptRevision = queryOutput.getRecords().get(0);
-      LOG.info("Running script against records", logPair("scriptRevisionId", scriptRevision.getValue("id")), logPair("scriptId", scriptRevision.getValue("scriptIdd")));
+      LOG.debug("Running script against records", logPair("scriptRevisionId", scriptRevision.getValue("id")), logPair("scriptId", scriptRevision.getValue("scriptIdd")));
 
       RunAdHocRecordScriptInput input = new RunAdHocRecordScriptInput();
       input.setCodeReference(new AdHocScriptCodeReference().withScriptRevisionRecord(scriptRevision));

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/automation/polling/PollingAutomationPerTableRunner.java

@@ -33,8 +33,9 @@ import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncRecordPipeLoop;
 import com.kingsrook.qqq.backend.core.actions.automation.AutomationStatus;
-import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandler;
+import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandlerInterface;
 import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationStatusUpdater;
+import com.kingsrook.qqq.backend.core.actions.automation.RunCustomTableTriggerRecordAutomationHandler;
 import com.kingsrook.qqq.backend.core.actions.automation.RunRecordScriptAutomationHandler;
 import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
 import com.kingsrook.qqq.backend.core.actions.processes.QProcessCallback;
@@ -442,15 +443,33 @@ public class PollingAutomationPerTableRunner implements Runnable
                   }
                }
 
-               rs.add(new TableAutomationAction()
-                  .withName("Script:" + tableTrigger.getScriptId())
+               TableAutomationAction tableAutomationAction = new TableAutomationAction()
                   .withFilter(filter)
                   .withTriggerEvent(triggerEvent)
                   .withPriority(tableTrigger.getPriority())
-                  .withCodeReference(new QCodeReference(RunRecordScriptAutomationHandler.class))
-                  .withValues(MapBuilder.of("scriptId", tableTrigger.getScriptId()))
-                  .withIncludeRecordAssociations(true)
-               );
+                  .withIncludeRecordAssociations(true);
+
+               ///////////////////////////////////////////////////////////////////////////////////////////////////////
+               // if the table trigger has a script id on it, then we know how to run that here in qqq-backend-core //
+               ///////////////////////////////////////////////////////////////////////////////////////////////////////
+               if(tableTrigger.getScriptId() != null)
+               {
+                  rs.add(tableAutomationAction
+                     .withName("Script:" + tableTrigger.getScriptId())
+                     .withValues(MapBuilder.of("scriptId", tableTrigger.getScriptId()))
+                     .withCodeReference(new QCodeReference(RunRecordScriptAutomationHandler.class)));
+               }
+               else
+               {
+                  ////////////////////////////////////////////////////////////////////////////////////////////////
+                  // but - the app may have added an extension to the TableTrigger table (e.g., workflows qbit) //
+                  // so, defer to RunCustomRecordAutomationHandler for unrecognized triggers                    //
+                  ////////////////////////////////////////////////////////////////////////////////////////////////
+                  rs.add(tableAutomationAction
+                     .withName("Custom Trigger:" + tableTrigger.getScriptId())
+                     .withValues(MapBuilder.of("tableTriggerId", tableTrigger.getId()))
+                     .withCodeReference(new QCodeReference(RunCustomTableTriggerRecordAutomationHandler.class)));
+               }
             }
             catch(Exception e)
             {
@@ -526,7 +545,7 @@ public class PollingAutomationPerTableRunner implements Runnable
          // note - this method - will re-query the objects, so we should have confidence that their data is fresh... //
          //////////////////////////////////////////////////////////////////////////////////////////////////////////////
          List<QRecord> matchingQRecords = getRecordsMatchingActionFilter(table, records, action);
-         LOG.debug("Of the [" + records.size() + "] records that were pending automations, [" + matchingQRecords.size() + "] of them match the filter on the action:" +  action);
+         LOG.debug("Of the [" + records.size() + "] records that were pending automations, [" + matchingQRecords.size() + "] of them match the filter on the action:" + action);
          if(CollectionUtils.nullSafeHasContents(matchingQRecords))
          {
             LOG.debug("  Processing " + matchingQRecords.size() + " records in " + table + " for action " + action);
@@ -649,7 +668,7 @@ public class PollingAutomationPerTableRunner implements Runnable
          input.setRecordList(records);
          input.setAction(action);
 
-         RecordAutomationHandler recordAutomationHandler = QCodeLoader.getRecordAutomationHandler(action);
+         RecordAutomationHandlerInterface recordAutomationHandler = QCodeLoader.getAdHoc(RecordAutomationHandlerInterface.class, action.getCodeReference());
          recordAutomationHandler.execute(input);
       }
    }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/customizers/MultiCustomizer.java

@@ -0,0 +1,226 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.InitializableViaCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReferenceWithProperties;
+import com.kingsrook.qqq.backend.core.utils.collections.MapBuilder;
+
+
+/*******************************************************************************
+ ** Implementation of TableCustomizerInterface that runs multiple other customizers
+ *******************************************************************************/
+public class MultiCustomizer implements InitializableViaCodeReference, TableCustomizerInterface
+{
+   private static final String KEY_CODE_REFERENCES = "codeReferences";
+
+   private List<TableCustomizerInterface> customizers = new ArrayList<>();
+
+
+   /***************************************************************************
+    * Factory method that builds a {@link QCodeReferenceWithProperties} that will
+    * allow this multi-customizer to be assigned to a table, and to track
+    * in that code ref's properties, the "sub" QCodeReferences to be used.
+    *
+    * Added to a table as in:
+    * <pre>
+    * table.withCustomizer(TableCustomizers.POST_INSERT_RECORD,
+    *    MultiCustomizer.of(QCodeReference(x), QCodeReference(y)));
+    * </pre>
+    *
+    * @param codeReferences
+    * one or more {@link QCodeReference objects} to run when this customizer
+    * runs.  note that they will run in the order provided in this list.
+    ***************************************************************************/
+   public static QCodeReferenceWithProperties of(QCodeReference... codeReferences)
+   {
+      ArrayList<QCodeReference> list = new ArrayList<>(Arrays.stream(codeReferences).toList());
+      return (new QCodeReferenceWithProperties(MultiCustomizer.class, MapBuilder.of(KEY_CODE_REFERENCES, list)));
+   }
+
+
+   /***************************************************************************
+    * Add an additional table customizer code reference to an existing
+    * codeReference, e.g., constructed by the `of` factory method.
+    *
+    * @see #of(QCodeReference...)
+    ***************************************************************************/
+   public static void addTableCustomizer(QCodeReferenceWithProperties existingMultiCustomizerCodeReference, QCodeReference codeReference)
+   {
+      ArrayList<QCodeReference> list = (ArrayList<QCodeReference>) existingMultiCustomizerCodeReference.getProperties().computeIfAbsent(KEY_CODE_REFERENCES, key -> new ArrayList<>());
+      list.add(codeReference);
+   }
+
+
+
+   /***************************************************************************
+    * When this class is instantiated by the QCodeLoader, initialize the
+    * sub-customizer objects.
+    ***************************************************************************/
+   @Override
+   public void initialize(QCodeReference codeReference)
+   {
+      if(codeReference instanceof QCodeReferenceWithProperties codeReferenceWithProperties)
+      {
+         Serializable codeReferencesPropertyValue = codeReferenceWithProperties.getProperties().get(KEY_CODE_REFERENCES);
+         if(codeReferencesPropertyValue instanceof List<?> list)
+         {
+            for(Object o : list)
+            {
+               if(o instanceof QCodeReference reference)
+               {
+                  TableCustomizerInterface customizer = QCodeLoader.getAdHoc(TableCustomizerInterface.class, reference);
+                  customizers.add(customizer);
+               }
+            }
+         }
+         else
+         {
+            LOG.warn("Property KEY_CODE_REFERENCES [" + KEY_CODE_REFERENCES + "] must be a List<QCodeReference>.");
+         }
+      }
+
+      if(customizers.isEmpty())
+      {
+         LOG.info("No TableCustomizers were specified for MultiCustomizer.");
+      }
+   }
+
+
+
+   /***************************************************************************
+    * run postQuery method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postQuery(QueryOrGetInputInterface queryInput, List<QRecord> records) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.postQuery(queryInput, records);
+      }
+      return records;
+   }
+
+
+
+   /***************************************************************************
+    * run preInsert method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> preInsert(InsertInput insertInput, List<QRecord> records, boolean isPreview) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.preInsert(insertInput, records, isPreview);
+      }
+      return records;
+   }
+
+
+
+   /***************************************************************************
+    * run postInsert method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postInsert(InsertInput insertInput, List<QRecord> records) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.postInsert(insertInput, records);
+      }
+      return records;
+   }
+
+
+
+   /***************************************************************************
+    * run preUpdate method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> preUpdate(UpdateInput updateInput, List<QRecord> records, boolean isPreview, Optional<List<QRecord>> oldRecordList) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.preUpdate(updateInput, records, isPreview, oldRecordList);
+      }
+      return records;
+   }
+
+
+
+   /***************************************************************************
+    * run postUpdate method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postUpdate(UpdateInput updateInput, List<QRecord> records, Optional<List<QRecord>> oldRecordList) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.postUpdate(updateInput, records, oldRecordList);
+      }
+      return records;
+   }
+
+
+
+   /***************************************************************************
+    * run preDelete method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> preDelete(DeleteInput deleteInput, List<QRecord> records, boolean isPreview) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.preDelete(deleteInput, records, isPreview);
+      }
+      return records;
+   }
+
+
+
+   /***************************************************************************
+    * run postDelete method over all sub-customizers
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postDelete(DeleteInput deleteInput, List<QRecord> records) throws QException
+   {
+      for(TableCustomizerInterface customizer : customizers)
+      {
+         records = customizer.postDelete(deleteInput, records);
+      }
+      return records;
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/customizers/OldRecordHelper.java

@@ -0,0 +1,88 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.io.Serializable;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.utils.collections.TypeTolerantKeyMap;
+
+
+/*******************************************************************************
+ ** utility class to help table customizers working with the oldRecordList.
+ ** Usage is just 2 lines:
+ ** outside of loop-over-records:
+ **   - OldRecordHelper oldRecordHelper = new OldRecordHelper(updateInput.getTableName(), oldRecordList);
+ ** then inside the record loop:
+ **   - Optional<QRecord> oldRecord = oldRecordHelper.getOldRecord(record);
+ *******************************************************************************/
+public class OldRecordHelper
+{
+   private String     primaryKeyField;
+   private QFieldType primaryKeyType;
+
+   private Optional<List<QRecord>>    oldRecordList;
+   private Map<Serializable, QRecord> oldRecordMap;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public OldRecordHelper(String tableName, Optional<List<QRecord>> oldRecordList)
+   {
+      this.primaryKeyField = QContext.getQInstance().getTable(tableName).getPrimaryKeyField();
+      this.primaryKeyType = QContext.getQInstance().getTable(tableName).getField(primaryKeyField).getType();
+
+      this.oldRecordList = oldRecordList;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public Optional<QRecord> getOldRecord(QRecord record)
+   {
+      if(oldRecordMap == null)
+      {
+         if(oldRecordList.isPresent())
+         {
+            oldRecordMap = new TypeTolerantKeyMap<>(primaryKeyType);
+            oldRecordList.get().forEach(r -> oldRecordMap.put(r.getValue(primaryKeyField), r));
+         }
+         else
+         {
+            oldRecordMap = Collections.emptyMap();
+         }
+      }
+
+      return (Optional.ofNullable(oldRecordMap.get(record.getValue(primaryKeyField))));
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/customizers/QCodeLoader.java

@@ -24,17 +24,11 @@ package com.kingsrook.qqq.backend.core.actions.customizers;
 
 import java.lang.reflect.Constructor;
 import java.util.Optional;
-import java.util.function.Function;
-import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandler;
-import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
-import com.kingsrook.qqq.backend.core.actions.values.QCustomPossibleValueProvider;
-import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.code.InitializableViaCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeType;
-import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TableAutomationAction;
 import com.kingsrook.qqq.backend.core.utils.lambdas.UnsafeFunction;
 import com.kingsrook.qqq.backend.core.utils.memoization.Memoization;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
@@ -43,9 +37,7 @@ import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 /*******************************************************************************
  ** Utility to load code for running QQQ customizers.
  **
- ** TODO - redo all to go through method that memoizes class & constructor
- ** lookup.  That memoziation causes 1,000,000 such calls to go from ~500ms
- ** to ~100ms.
+ ** That memoization causes 1,000,000 such calls to go from ~500ms to ~100ms.
  *******************************************************************************/
 public class QCodeLoader
 {
@@ -70,84 +62,6 @@ public class QCodeLoader
 
 
 
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   @SuppressWarnings("unchecked")
-   public static <T, R> Function<T, R> getFunction(QCodeReference codeReference)
-   {
-      if(codeReference == null)
-      {
-         return (null);
-      }
-
-      if(!codeReference.getCodeType().equals(QCodeType.JAVA))
-      {
-         ///////////////////////////////////////////////////////////////////////////////////////
-         // todo - 1) support more languages, 2) wrap them w/ java Functions here, 3) profit! //
-         ///////////////////////////////////////////////////////////////////////////////////////
-         throw (new IllegalArgumentException("Only JAVA customizers are supported at this time."));
-      }
-
-      try
-      {
-         Class<?> customizerClass = Class.forName(codeReference.getName());
-         return ((Function<T, R>) customizerClass.getConstructor().newInstance());
-      }
-      catch(Exception e)
-      {
-         LOG.error("Error initializing customizer", e, logPair("codeReference", codeReference));
-
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////
-         // return null here - under the assumption that during normal run-time operations, we'll never hit here //
-         // as we'll want to validate all functions in the instance validator at startup time (and IT will throw //
-         // if it finds an invalid code reference                                                                //
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////
-         return (null);
-      }
-   }
-
-
-
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   @SuppressWarnings("unchecked")
-   public static <T extends BackendStep> T getBackendStep(Class<T> expectedType, QCodeReference codeReference)
-   {
-      if(codeReference == null)
-      {
-         return (null);
-      }
-
-      if(!codeReference.getCodeType().equals(QCodeType.JAVA))
-      {
-         ///////////////////////////////////////////////////////////////////////////////////////
-         // todo - 1) support more languages, 2) wrap them w/ java Functions here, 3) profit! //
-         ///////////////////////////////////////////////////////////////////////////////////////
-         throw (new IllegalArgumentException("Only JAVA BackendSteps are supported at this time."));
-      }
-
-      try
-      {
-         Class<?> customizerClass = Class.forName(codeReference.getName());
-         return ((T) customizerClass.getConstructor().newInstance());
-      }
-      catch(Exception e)
-      {
-         LOG.error("Error initializing customizer", e, logPair("codeReference", codeReference));
-
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////
-         // return null here - under the assumption that during normal run-time operations, we'll never hit here //
-         // as we'll want to validate all functions in the instance validator at startup time (and IT will throw //
-         // if it finds an invalid code reference                                                                //
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////
-         return (null);
-      }
-   }
-
-
-
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -177,7 +91,17 @@ public class QCodeLoader
 
          if(constructor.isPresent())
          {
-            return ((T) constructor.get().newInstance());
+            T t = (T) constructor.get().newInstance();
+
+            ////////////////////////////////////////////////////////////////
+            // if the object is initializable, then, well, initialize it! //
+            ////////////////////////////////////////////////////////////////
+            if(t instanceof InitializableViaCodeReference initializableViaCodeReference)
+            {
+               initializableViaCodeReference.initialize(codeReference);
+            }
+
+            return t;
          }
          else
          {
@@ -187,7 +111,7 @@ public class QCodeLoader
       }
       catch(Exception e)
       {
-         LOG.error("Error initializing customizer", e, logPair("codeReference", codeReference));
+         LOG.error("Error initializing codeReference", e, logPair("codeReference", codeReference));
 
          //////////////////////////////////////////////////////////////////////////////////////////////////////////
          // return null here - under the assumption that during normal run-time operations, we'll never hit here //
@@ -198,67 +122,4 @@ public class QCodeLoader
       }
    }
 
-
-
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   public static RecordAutomationHandler getRecordAutomationHandler(TableAutomationAction action) throws QException
-   {
-      try
-      {
-         QCodeReference codeReference = action.getCodeReference();
-         if(!codeReference.getCodeType().equals(QCodeType.JAVA))
-         {
-            ///////////////////////////////////////////////////////////////////////////////////////
-            // todo - 1) support more languages, 2) wrap them w/ java Functions here, 3) profit! //
-            ///////////////////////////////////////////////////////////////////////////////////////
-            throw (new IllegalArgumentException("Only JAVA customizers are supported at this time."));
-         }
-
-         Class<?> codeClass  = Class.forName(codeReference.getName());
-         Object   codeObject = codeClass.getConstructor().newInstance();
-         if(!(codeObject instanceof RecordAutomationHandler recordAutomationHandler))
-         {
-            throw (new QException("The supplied code [" + codeClass.getName() + "] is not an instance of RecordAutomationHandler"));
-         }
-         return (recordAutomationHandler);
-      }
-      catch(QException qe)
-      {
-         throw (qe);
-      }
-      catch(Exception e)
-      {
-         throw (new QException("Error getting record automation handler for action [" + action.getName() + "]", e));
-      }
-   }
-
-
-
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   public static QCustomPossibleValueProvider getCustomPossibleValueProvider(QPossibleValueSource possibleValueSource) throws QException
-   {
-      try
-      {
-         Class<?> codeClass  = Class.forName(possibleValueSource.getCustomCodeReference().getName());
-         Object   codeObject = codeClass.getConstructor().newInstance();
-         if(!(codeObject instanceof QCustomPossibleValueProvider customPossibleValueProvider))
-         {
-            throw (new QException("The supplied code [" + codeClass.getName() + "] is not an instance of QCustomPossibleValueProvider"));
-         }
-         return (customPossibleValueProvider);
-      }
-      catch(QException qe)
-      {
-         throw (qe);
-      }
-      catch(Exception e)
-      {
-         throw (new QException("Error getting custom possible value provider for PVS [" + possibleValueSource.getName() + "]", e));
-      }
-   }
-
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/dashboard/AbstractHTMLWidgetRenderer.java

@@ -161,7 +161,7 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
    public static String linkTableCreateWithDefaultValues(RenderWidgetInput input, String tableName, Map<String, Serializable> defaultValues) throws QException
    {
       String tablePath = QContext.getQInstance().getTablePath(tableName);
-      return (tablePath + "/create#defaultValues=" + URLEncoder.encode(JsonUtils.toJson(defaultValues), Charset.defaultCharset()));
+      return (tablePath + "/create#defaultValues=" + URLEncoder.encode(JsonUtils.toJson(defaultValues), StandardCharsets.UTF_8));
    }
 
 
@@ -229,7 +229,7 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
       }
 
       filter = QQueryFilterDeduper.dedupeFilter(filter);
-      return (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), Charset.defaultCharset()));
+      return (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), StandardCharsets.UTF_8));
    }
 
 
@@ -290,7 +290,18 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
    /*******************************************************************************
     **
     *******************************************************************************/
+   @Deprecated(since = "call one that doesn't take input param")
    public static String linkRecordEdit(AbstractActionInput input, String tableName, Serializable recordId) throws QException
+   {
+      return linkRecordEdit(tableName, recordId);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkRecordEdit(String tableName, Serializable recordId) throws QException
    {
       String tablePath = QContext.getQInstance().getTablePath(tableName);
       return (tablePath + "/" + recordId + "/edit");
@@ -317,7 +328,17 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
    /*******************************************************************************
     **
     *******************************************************************************/
+   @Deprecated(since = "call one that doesn't take input param")
    public static String linkProcessForFilter(AbstractActionInput input, String processName, QQueryFilter filter) throws QException
+   {
+      return linkProcessForFilter(processName, filter);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkProcessForFilter(String processName, QQueryFilter filter) throws QException
    {
       QProcessMetaData process = QContext.getQInstance().getProcess(processName);
       if(process == null)
@@ -337,10 +358,21 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
 
 
 
+
    /*******************************************************************************
     **
     *******************************************************************************/
+   @Deprecated(since = "call one that doesn't take input param")
    public static String linkProcessForRecord(AbstractActionInput input, String processName, Serializable recordId) throws QException
+   {
+      return linkProcessForRecord(processName, recordId);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkProcessForRecord(String processName, Serializable recordId) throws QException
    {
       QProcessMetaData process   = QContext.getQInstance().getProcess(processName);
       String           tableName = process.getTableName();

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/dashboard/widgets/ChildRecordListRenderer.java

@@ -25,11 +25,14 @@ package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 import java.io.Serializable;
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import com.google.gson.reflect.TypeToken;
 import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
 import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
@@ -45,6 +48,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
@@ -65,6 +69,7 @@ import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.JsonUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+import com.kingsrook.qqq.backend.core.utils.collections.MutableList;
 import org.apache.commons.lang.BooleanUtils;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
@@ -176,6 +181,18 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
          return (this);
       }
 
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public Builder withOmitFieldNames(List<String> omitFieldNames)
+      {
+         ArrayList<String> arrayList = CollectionUtils.useOrWrap(omitFieldNames, new TypeToken<>() {});
+         widgetMetaData.withDefaultValue("omitFieldNames", arrayList);
+         return (this);
+      }
+
    }
 
 
@@ -195,14 +212,25 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
          QTableMetaData leftTable   = QContext.getQInstance().getTable(join.getLeftTable());
          QTableMetaData rightTable  = QContext.getQInstance().getTable(join.getRightTable());
 
+         Map<String, Serializable> widgetMetaDataDefaultValues = input.getWidgetMetaData().getDefaultValues();
+         List<String> omitFieldNames = (List<String>) widgetMetaDataDefaultValues.get("omitFieldNames");
+         if(omitFieldNames == null)
+         {
+            omitFieldNames = new ArrayList<>();
+         }
+         else
+         {
+            omitFieldNames = new MutableList<>(omitFieldNames);
+         }
+
          Integer maxRows = null;
          if(StringUtils.hasContent(input.getQueryParams().get("maxRows")))
          {
             maxRows = ValueUtils.getValueAsInteger(input.getQueryParams().get("maxRows"));
          }
-         else if(input.getWidgetMetaData().getDefaultValues().containsKey("maxRows"))
+         else if(widgetMetaDataDefaultValues.containsKey("maxRows"))
          {
-            maxRows = ValueUtils.getValueAsInteger(input.getWidgetMetaData().getDefaultValues().get("maxRows"));
+            maxRows = ValueUtils.getValueAsInteger(widgetMetaDataDefaultValues.get("maxRows"));
          }
 
          //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -234,8 +262,19 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
             for(JoinOn joinOn : join.getJoinOns())
             {
                filter.addCriteria(new QFilterCriteria(joinOn.getRightField(), QCriteriaOperator.EQUALS, List.of(primaryRecord.getValue(joinOn.getLeftField()))));
+               omitFieldNames.add(joinOn.getRightField());
             }
-            filter.setOrderBys(join.getOrderBys());
+
+            Serializable orderBy = widgetMetaDataDefaultValues.get("orderBy");
+            if(orderBy instanceof List orderByList && !orderByList.isEmpty() && orderByList.get(0) instanceof QFilterOrderBy)
+            {
+               filter.setOrderBys(orderByList);
+            }
+            else
+            {
+               filter.setOrderBys(join.getOrderBys());
+            }
+
             filter.setLimit(maxRows);
 
             QueryInput queryInput = new QueryInput();
@@ -262,9 +301,10 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
          }
 
          String tablePath   = QContext.getQInstance().getTablePath(rightTable.getName());
-         String viewAllLink = tablePath == null ? null : (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), Charset.defaultCharset()));
+         String viewAllLink = tablePath == null ? null : (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), StandardCharsets.UTF_8));
 
          ChildRecordListData widgetData = new ChildRecordListData(widgetLabel, queryOutput, rightTable, tablePath, viewAllLink, totalRows);
+         widgetData.setOmitFieldNames(omitFieldNames);
 
          if(BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(input.getQueryParams().get("canAddChildRecord"))))
          {
@@ -284,11 +324,10 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
 
             widgetData.setDefaultValuesForNewChildRecords(defaultValuesForNewChildRecords);
 
-            Map<String, Serializable> widgetValues = input.getWidgetMetaData().getDefaultValues();
-            if(widgetValues.containsKey("disabledFieldsForNewChildRecords"))
+            if(widgetMetaDataDefaultValues.containsKey("disabledFieldsForNewChildRecords"))
             {
                @SuppressWarnings("unchecked")
-               Set<String> disabledFieldsForNewChildRecords = (Set<String>) widgetValues.get("disabledFieldsForNewChildRecords");
+               Set<String> disabledFieldsForNewChildRecords = (Set<String>) widgetMetaDataDefaultValues.get("disabledFieldsForNewChildRecords");
                widgetData.setDisabledFieldsForNewChildRecords(disabledFieldsForNewChildRecords);
             }
             else
@@ -308,10 +347,10 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
                }
             }
 
-            if(widgetValues.containsKey("defaultValuesForNewChildRecordsFromParentFields"))
+            if(widgetMetaDataDefaultValues.containsKey("defaultValuesForNewChildRecordsFromParentFields"))
             {
                @SuppressWarnings("unchecked")
-               Map<String, String> defaultValuesForNewChildRecordsFromParentFields = (Map<String, String>) widgetValues.get("defaultValuesForNewChildRecordsFromParentFields");
+               Map<String, String> defaultValuesForNewChildRecordsFromParentFields = (Map<String, String>) widgetMetaDataDefaultValues.get("defaultValuesForNewChildRecordsFromParentFields");
                widgetData.setDefaultValuesForNewChildRecordsFromParentFields(defaultValuesForNewChildRecordsFromParentFields);
             }
          }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/dashboard/widgets/RecordListWidgetRenderer.java

@@ -24,6 +24,7 @@ package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.util.HashMap;
 import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
@@ -194,7 +195,7 @@ public class RecordListWidgetRenderer extends AbstractWidgetRenderer
          }
 
          String tablePath   = QContext.getQInstance().getTablePath(tableName);
-         String viewAllLink = tablePath == null ? null : (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), Charset.defaultCharset()));
+         String viewAllLink = tablePath == null ? null : (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), StandardCharsets.UTF_8));
 
          ChildRecordListData widgetData = new ChildRecordListData(input.getQueryParams().get("widgetLabel"), queryOutput, table, tablePath, viewAllLink, totalRows);
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/metadata/AllowAllMetaDataFilter.java

@@ -33,6 +33,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 /*******************************************************************************
  ** a default implementation of MetaDataFilterInterface, that allows all the things
  *******************************************************************************/
+@Deprecated(since = "migrated to metaDataCustomizer")
 public class AllowAllMetaDataFilter implements MetaDataFilterInterface
 {
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/metadata/DefaultNoopMetaDataActionCustomizer.java

@@ -0,0 +1,92 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.metadata;
+
+
+import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** a default implementation of MetaDataFilterInterface, that is all noop.
+ *******************************************************************************/
+public class DefaultNoopMetaDataActionCustomizer implements MetaDataActionCustomizerInterface
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public boolean allowTable(MetaDataInput input, QTableMetaData table)
+   {
+      return (true);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public boolean allowProcess(MetaDataInput input, QProcessMetaData process)
+   {
+      return (true);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public boolean allowReport(MetaDataInput input, QReportMetaData report)
+   {
+      return (true);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public boolean allowApp(MetaDataInput input, QAppMetaData app)
+   {
+      return (true);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public boolean allowWidget(MetaDataInput input, QWidgetMetaDataInterface widget)
+   {
+      return (true);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/metadata/MetaDataAction.java

@@ -23,10 +23,12 @@ package com.kingsrook.qqq.backend.core.actions.metadata;
 
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
 import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
 import com.kingsrook.qqq.backend.core.actions.permissions.PermissionCheckResult;
@@ -34,6 +36,7 @@ import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QRuntimeException;
+import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
 import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataOutput;
@@ -65,7 +68,7 @@ public class MetaDataAction
 {
    private static final QLogger LOG = QLogger.getLogger(MetaDataAction.class);
 
-   private static Memoization<QInstance, MetaDataFilterInterface> metaDataFilterMemoization = new Memoization<>();
+   private static Memoization<QInstance, MetaDataActionCustomizerInterface> metaDataActionCustomizerMemoization = new Memoization<>();
 
 
 
@@ -79,7 +82,7 @@ public class MetaDataAction
       MetaDataOutput           metaDataOutput = new MetaDataOutput();
       Map<String, AppTreeNode> treeNodes      = new LinkedHashMap<>();
 
-      MetaDataFilterInterface filter = getMetaDataFilter();
+      MetaDataActionCustomizerInterface customizer = getMetaDataActionCustomizer();
 
       /////////////////////////////////////
       // map tables to frontend metadata //
@@ -90,7 +93,7 @@ public class MetaDataAction
          String         tableName = entry.getKey();
          QTableMetaData table     = entry.getValue();
 
-         if(!filter.allowTable(metaDataInput, table))
+         if(!customizer.allowTable(metaDataInput, table))
          {
             continue;
          }
@@ -119,7 +122,7 @@ public class MetaDataAction
          String           processName = entry.getKey();
          QProcessMetaData process     = entry.getValue();
 
-         if(!filter.allowProcess(metaDataInput, process))
+         if(!customizer.allowProcess(metaDataInput, process))
          {
             continue;
          }
@@ -144,7 +147,7 @@ public class MetaDataAction
          String          reportName = entry.getKey();
          QReportMetaData report     = entry.getValue();
 
-         if(!filter.allowReport(metaDataInput, report))
+         if(!customizer.allowReport(metaDataInput, report))
          {
             continue;
          }
@@ -169,7 +172,7 @@ public class MetaDataAction
          String                   widgetName = entry.getKey();
          QWidgetMetaDataInterface widget     = entry.getValue();
 
-         if(!filter.allowWidget(metaDataInput, widget))
+         if(!customizer.allowWidget(metaDataInput, widget))
          {
             continue;
          }
@@ -206,7 +209,7 @@ public class MetaDataAction
             continue;
          }
 
-         if(!filter.allowApp(metaDataInput, app))
+         if(!customizer.allowApp(metaDataInput, app))
          {
             continue;
          }
@@ -292,11 +295,24 @@ public class MetaDataAction
          metaDataOutput.setBranding(QContext.getQInstance().getBranding());
       }
 
-      metaDataOutput.setEnvironmentValues(QContext.getQInstance().getEnvironmentValues());
+      metaDataOutput.setEnvironmentValues(Objects.requireNonNullElse(QContext.getQInstance().getEnvironmentValues(), Collections.emptyMap()));
 
-      metaDataOutput.setHelpContents(QContext.getQInstance().getHelpContent());
+      metaDataOutput.setHelpContents(Objects.requireNonNullElse(QContext.getQInstance().getHelpContent(), Collections.emptyMap()));
 
-      // todo post-customization - can do whatever w/ the result if you want?
+      metaDataOutput.setSupplementalInstanceMetaData(QContext.getQInstance().getSupplementalMetaData());
+
+      try
+      {
+         customizer.postProcess(metaDataOutput);
+      }
+      catch(QUserFacingException e)
+      {
+         LOG.debug("User-facing exception thrown in meta-data customizer post-processing", e);
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Unexpected error thrown in meta-data customizer post-processing", e);
+      }
 
       return metaDataOutput;
    }
@@ -306,26 +322,38 @@ public class MetaDataAction
    /***************************************************************************
     **
     ***************************************************************************/
-   private MetaDataFilterInterface getMetaDataFilter()
+   private MetaDataActionCustomizerInterface getMetaDataActionCustomizer()
    {
-      return metaDataFilterMemoization.getResult(QContext.getQInstance(), i ->
+      return metaDataActionCustomizerMemoization.getResult(QContext.getQInstance(), i ->
       {
-         MetaDataFilterInterface filter                  = null;
-         QCodeReference          metaDataFilterReference = QContext.getQInstance().getMetaDataFilter();
-         if(metaDataFilterReference != null)
+         MetaDataActionCustomizerInterface actionCustomizer                  = null;
+         QCodeReference                    metaDataActionCustomizerReference = QContext.getQInstance().getMetaDataActionCustomizer();
+         if(metaDataActionCustomizerReference != null)
          {
-            filter = QCodeLoader.getAdHoc(MetaDataFilterInterface.class, metaDataFilterReference);
-            LOG.debug("Using new meta-data filter of type: " + filter.getClass().getSimpleName());
+            actionCustomizer = QCodeLoader.getAdHoc(MetaDataActionCustomizerInterface.class, metaDataActionCustomizerReference);
          }
 
-         if(filter == null)
+         if(actionCustomizer == null)
          {
-            filter = new AllowAllMetaDataFilter();
-            LOG.debug("Using new default (allow-all) meta-data filter");
+            /////////////////////////////////////////////////////////////////////////////////////
+            // check if QInstance is still using the now-deprecated getMetaDataFilter approach //
+            /////////////////////////////////////////////////////////////////////////////////////
+            @SuppressWarnings("deprecation")
+            QCodeReference metaDataFilterReference = QContext.getQInstance().getMetaDataFilter();
+            if(metaDataFilterReference != null)
+            {
+               LOG.warn("QInstance.metaDataFilter is deprecated in favor of metaDataActionCustomizer.");
+               actionCustomizer = QCodeLoader.getAdHoc(MetaDataActionCustomizerInterface.class, metaDataFilterReference);
+            }
          }
 
-         return (filter);
-      }).orElseThrow(() -> new QRuntimeException("Error getting metaDataFilter"));
+         if(actionCustomizer == null)
+         {
+            actionCustomizer = new DefaultNoopMetaDataActionCustomizer();
+         }
+
+         return (actionCustomizer);
+      }).orElseThrow(() -> new QRuntimeException("Error getting MetaDataActionCustomizer"));
    }
 
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/metadata/MetaDataActionCustomizerInterface.java

@@ -0,0 +1,78 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.metadata;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
+import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Interface for customizations that can be injected by an application into
+ ** the MetaDataAction - e.g., loading applicable meta-data for a user into a
+ ** frontend.
+ *******************************************************************************/
+public interface MetaDataActionCustomizerInterface
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   boolean allowTable(MetaDataInput input, QTableMetaData table);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   boolean allowProcess(MetaDataInput input, QProcessMetaData process);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   boolean allowReport(MetaDataInput input, QReportMetaData report);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   boolean allowApp(MetaDataInput input, QAppMetaData app);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   boolean allowWidget(MetaDataInput input, QWidgetMetaDataInterface widget);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   default void postProcess(MetaDataOutput metaDataOutput) throws QException
+   {
+      /////////////////////
+      // noop by default //
+      /////////////////////
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/metadata/MetaDataFilterInterface.java

@@ -22,43 +22,11 @@
 package com.kingsrook.qqq.backend.core.actions.metadata;
 
 
-import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
-import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
-import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-
-
 /*******************************************************************************
  **
  *******************************************************************************/
-public interface MetaDataFilterInterface
+@Deprecated(since = "migrated to metaDataCustomizer")
+public interface MetaDataFilterInterface extends MetaDataActionCustomizerInterface
 {
 
-   /***************************************************************************
-    **
-    ***************************************************************************/
-   boolean allowTable(MetaDataInput input, QTableMetaData table);
-
-   /***************************************************************************
-    **
-    ***************************************************************************/
-   boolean allowProcess(MetaDataInput input, QProcessMetaData process);
-
-   /***************************************************************************
-    **
-    ***************************************************************************/
-   boolean allowReport(MetaDataInput input, QReportMetaData report);
-
-   /***************************************************************************
-    **
-    ***************************************************************************/
-   boolean allowApp(MetaDataInput input, QAppMetaData app);
-
-   /***************************************************************************
-    **
-    ***************************************************************************/
-   boolean allowWidget(MetaDataInput input, QWidgetMetaDataInterface widget);
-
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/processes/RunBackendStepAction.java

@@ -36,6 +36,8 @@ import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
@@ -46,6 +48,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaD
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFunctionInputMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 
 
@@ -188,21 +191,40 @@ public class RunBackendStepAction
       {
          if(CollectionUtils.nullSafeIsEmpty(runBackendStepInput.getRecords()))
          {
-            QueryInput queryInput = new QueryInput();
-            queryInput.setTableName(inputMetaData.getRecordListMetaData().getTableName());
+            QTableMetaData table      = QContext.getQInstance().getTable(inputMetaData.getRecordListMetaData().getTableName());
+            QueryInput     queryInput = new QueryInput();
+            queryInput.setTableName(table.getName());
 
-            // todo - handle this being async (e.g., http)
-            // seems like it just needs to throw, breaking this flow, and to send a response to the frontend, directing it to prompt the user for the needed data
-            // then this step can re-run, hopefully with the needed data.
-
-            QProcessCallback callback = runBackendStepInput.getCallback();
-            if(callback == null)
+            //////////////////////////////////////////////////
+            // look for record ids in the input data values //
+            //////////////////////////////////////////////////
+            String recordIds = runBackendStepInput.getValueString("recordIds");
+            if(recordIds == null)
             {
-               throw (new QUserFacingException("Missing input records.",
-                  new QException("Function is missing input records, but no callback was present to request fields from a user")));
+               recordIds = runBackendStepInput.getValueString("recordId");
             }
 
-            queryInput.setFilter(callback.getQueryFilter());
+            ///////////////////////////////////////////////////////////
+            // if records were found, add as criteria to query input //
+            ///////////////////////////////////////////////////////////
+            if(recordIds != null)
+            {
+               queryInput.setFilter(new QQueryFilter(new QFilterCriteria(table.getPrimaryKeyField(), QCriteriaOperator.IN, recordIds.split(","))));
+            }
+            else
+            {
+               // todo - handle this being async (e.g., http)
+               // seems like it just needs to throw, breaking this flow, and to send a response to the frontend, directing it to prompt the user for the needed data
+               // then this step can re-run, hopefully with the needed data.
+               QProcessCallback callback = runBackendStepInput.getCallback();
+               if(callback == null)
+               {
+                  throw (new QUserFacingException("Missing input records.",
+                     new QException("Function is missing input records, but no callback was present to request fields from a user")));
+               }
+
+               queryInput.setFilter(callback.getQueryFilter());
+            }
 
             //////////////////////////////////////////////////////////////////////////////////////////
             // if process has a max-no of records, set a limit on the process of that number plus 1 //
@@ -210,7 +232,7 @@ public class RunBackendStepAction
             //////////////////////////////////////////////////////////////////////////////////////////
             if(process.getMaxInputRecords() != null)
             {
-               if(callback.getQueryFilter() == null)
+               if(queryInput.getFilter() == null)
                {
                   queryInput.setFilter(new QQueryFilter());
                }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/reporting/ExportStreamerInterface.java

@@ -54,6 +54,14 @@ public interface ExportStreamerInterface
       // noop in base class
    }
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   default void setExportStyleCustomizer(ExportStyleCustomizerInterface exportStyleCustomizer)
+   {
+      // noop in base class
+   }
+
    /*******************************************************************************
     ** Called once per sheet, before any rows are available.  Meant to write a
     ** header, for example.

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/reporting/ExportStyleCustomizerInterface.java

@@ -0,0 +1,35 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.reporting;
+
+
+/*******************************************************************************
+ ** interface for classes that can be used to customize visual style aspects of
+ ** exports/reports.
+ **
+ ** Anticipates very different sub-interfaces based on the file type being generated,
+ ** and the capabilities of each.  e.g., excel (bolds, fonts, cell merging) vs
+ ** json (different structure of objects).
+ *******************************************************************************/
+public interface ExportStyleCustomizerInterface
+{
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/reporting/GenerateReportAction.java

@@ -163,6 +163,17 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
          reportStreamer = reportFormat.newReportStreamer();
       }
 
+      if(reportInput.getExportStyleCustomizer() != null)
+      {
+         ExportStyleCustomizerInterface styleCustomizer = QCodeLoader.getAdHoc(ExportStyleCustomizerInterface.class, reportInput.getExportStyleCustomizer());
+         reportStreamer.setExportStyleCustomizer(styleCustomizer);
+      }
+      else if(report.getExportStyleCustomizer() != null)
+      {
+         ExportStyleCustomizerInterface styleCustomizer = QCodeLoader.getAdHoc(ExportStyleCustomizerInterface.class, report.getExportStyleCustomizer());
+         reportStreamer.setExportStyleCustomizer(styleCustomizer);
+      }
+
       reportStreamer.preRun(reportInput.getReportDestination(), views);
 
       ////////////////////////////////////////////////////////////////////////////////////////////////
@@ -211,7 +222,8 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
                /////////////////////////////////////////////////////////////////////////////////////////
                if(dataSourceTableView.getViewCustomizer() != null)
                {
-                  Function<QReportView, QReportView> viewCustomizerFunction = QCodeLoader.getFunction(dataSourceTableView.getViewCustomizer());
+                  @SuppressWarnings("unchecked")
+                  Function<QReportView, QReportView> viewCustomizerFunction = QCodeLoader.getAdHoc(Function.class, dataSourceTableView.getViewCustomizer());
                   if(viewCustomizerFunction instanceof ReportViewCustomizer reportViewCustomizer)
                   {
                      reportViewCustomizer.setReportInput(reportInput);
@@ -660,7 +672,7 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
          ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          // if any fields are 'showPossibleValueLabel', then move display values for them into the record's values map //
          ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-         for(QReportField column : tableView.getColumns())
+         for(QReportField column : CollectionUtils.nonNullList(tableView.getColumns()))
          {
             if(column.getShowPossibleValueLabel())
             {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/reporting/excel/poi/ExcelPoiBasedStreamingExportStreamer.java

@@ -46,6 +46,7 @@ import java.util.zip.ZipEntry;
 import java.util.zip.ZipInputStream;
 import java.util.zip.ZipOutputStream;
 import com.kingsrook.qqq.backend.core.actions.reporting.ExportStreamerInterface;
+import com.kingsrook.qqq.backend.core.actions.reporting.ExportStyleCustomizerInterface;
 import com.kingsrook.qqq.backend.core.actions.reporting.ReportUtils;
 import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
 import com.kingsrook.qqq.backend.core.instances.QInstanceEnricher;
@@ -77,6 +78,7 @@ import org.apache.poi.xssf.usermodel.XSSFPivotTable;
 import org.apache.poi.xssf.usermodel.XSSFRow;
 import org.apache.poi.xssf.usermodel.XSSFSheet;
 import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -112,9 +114,10 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
    public static final String EXCEL_DATE_FORMAT      = "yyyy-MM-dd";
    public static final String EXCEL_DATE_TIME_FORMAT = "yyyy-MM-dd H:mm:ss";
 
-   private PoiExcelStylerInterface    poiExcelStylerInterface = getStylerInterface();
+   private ExcelPoiBasedStreamingStyleCustomizerInterface styleCustomizerInterface;
+
    private Map<String, String>        excelCellFormats;
-   private Map<String, XSSFCellStyle> styles                  = new HashMap<>();
+   private Map<String, XSSFCellStyle> styles = new HashMap<>();
 
    private int rowNo      = 0;
    private int sheetIndex = 1;
@@ -402,6 +405,7 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
       dateTimeStyle.setDataFormat(createHelper.createDataFormat().getFormat(EXCEL_DATE_TIME_FORMAT));
       styles.put("datetime", dateTimeStyle);
 
+      PoiExcelStylerInterface poiExcelStylerInterface = getStylerInterface();
       styles.put("title", poiExcelStylerInterface.createStyleForTitle(workbook, createHelper));
       styles.put("header", poiExcelStylerInterface.createStyleForHeader(workbook, createHelper));
       styles.put("footer", poiExcelStylerInterface.createStyleForFooter(workbook, createHelper));
@@ -413,6 +417,11 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
       XSSFCellStyle footerDateTimeStyle = poiExcelStylerInterface.createStyleForFooter(workbook, createHelper);
       footerDateTimeStyle.setDataFormat(createHelper.createDataFormat().getFormat(EXCEL_DATE_TIME_FORMAT));
       styles.put("footer-datetime", footerDateTimeStyle);
+
+      if(styleCustomizerInterface != null)
+      {
+         styleCustomizerInterface.customizeStyles(styles, workbook, createHelper);
+      }
    }
 
 
@@ -458,7 +467,7 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
          }
          else
          {
-            sheetWriter.beginSheet();
+            sheetWriter.beginSheet(view, styleCustomizerInterface);
 
             ////////////////////////////////////////////////
             // put the title and header rows in the sheet //
@@ -560,6 +569,16 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static void setStyleForField(QRecord record, String fieldName, String styleName)
+   {
+      record.setDisplayValue(fieldName + ":excelStyle", styleName);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -567,12 +586,12 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
    {
       sheetWriter.insertRow(rowNo++);
 
-      int styleIndex         = -1;
+      int baseStyleIndex     = -1;
       int dateStyleIndex     = styles.get("date").getIndex();
       int dateTimeStyleIndex = styles.get("datetime").getIndex();
       if(isFooter)
       {
-         styleIndex = styles.get("footer").getIndex();
+         baseStyleIndex = styles.get("footer").getIndex();
          dateStyleIndex = styles.get("footer-date").getIndex();
          dateTimeStyleIndex = styles.get("footer-datetime").getIndex();
       }
@@ -582,6 +601,13 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
       {
          Serializable value = qRecord.getValue(field.getName());
 
+         String overrideStyleName = qRecord.getDisplayValue(field.getName() + ":excelStyle");
+         int    styleIndex        = baseStyleIndex;
+         if(overrideStyleName != null)
+         {
+            styleIndex = styles.get(overrideStyleName).getIndex();
+         }
+
          if(value != null)
          {
             if(value instanceof String s)
@@ -706,7 +732,7 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
       {
          if(!ReportType.PIVOT.equals(currentView.getType()))
          {
-            sheetWriter.endSheet();
+            sheetWriter.endSheet(currentView, styleCustomizerInterface);
          }
 
          activeSheetWriter.flush();
@@ -815,7 +841,29 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
     *******************************************************************************/
    protected PoiExcelStylerInterface getStylerInterface()
    {
+      if(styleCustomizerInterface != null)
+      {
+         return styleCustomizerInterface.getExcelStyler();
+      }
+
       return (new PlainPoiExcelStyler());
    }
 
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public void setExportStyleCustomizer(ExportStyleCustomizerInterface exportStyleCustomizer)
+   {
+      if(exportStyleCustomizer instanceof ExcelPoiBasedStreamingStyleCustomizerInterface poiExcelStylerInterface)
+      {
+         this.styleCustomizerInterface = poiExcelStylerInterface;
+      }
+      else
+      {
+         LOG.debug("Supplied export style customizer is not an instance of ExcelPoiStyleCustomizerInterface, so will not be used for an excel export", logPair("exportStyleCustomizerClass", exportStyleCustomizer.getClass().getSimpleName()));
+      }
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/reporting/excel/poi/ExcelPoiBasedStreamingStyleCustomizerInterface.java

@@ -0,0 +1,81 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.reporting.excel.poi;
+
+
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.reporting.ExportStyleCustomizerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportView;
+import org.apache.poi.ss.usermodel.CreationHelper;
+import org.apache.poi.xssf.usermodel.XSSFCellStyle;
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+
+
+/*******************************************************************************
+ ** style customization points for Excel files generated via our streaming POI.
+ *******************************************************************************/
+public interface ExcelPoiBasedStreamingStyleCustomizerInterface extends ExportStyleCustomizerInterface
+{
+   /***************************************************************************
+    ** slightly legacy way we did excel styles - but get an instance of object
+    ** that defaults "default" styles (header, footer, etc).
+    ***************************************************************************/
+   default PoiExcelStylerInterface getExcelStyler()
+   {
+      return (new PlainPoiExcelStyler());
+   }
+
+
+   /***************************************************************************
+    ** either change "default" styles put in the styles map, or create new ones
+    ** which can then be applied to row/field values (cells) via:
+    ** ExcelPoiBasedStreamingExportStreamer.setStyleForField(row, fieldName, styleName);
+    ***************************************************************************/
+   default void customizeStyles(Map<String, XSSFCellStyle> styles, XSSFWorkbook workbook, CreationHelper createHelper)
+   {
+      //////////////////
+      // noop default //
+      //////////////////
+   }
+
+
+   /***************************************************************************
+    ** for a given view (sheet), return a list of custom column widths.
+    ** any nulls in the list are ignored (so default width is used).
+    ***************************************************************************/
+   default List<Integer> getColumnWidthsForView(QReportView view)
+   {
+      return (null);
+   }
+
+
+   /***************************************************************************
+    ** for a given view (sheet), return a list of any ranges which should be
+    ** merged, as in "A1:C1" (first three cells in first row).
+    ***************************************************************************/
+   default List<String> getMergedRangesForView(QReportView view)
+   {
+      return (null);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/reporting/excel/poi/StreamedSheetWriter.java

@@ -25,7 +25,10 @@ package com.kingsrook.qqq.backend.core.actions.reporting.excel.poi;
 import java.io.IOException;
 import java.io.Writer;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
+import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportView;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import org.apache.poi.ss.util.CellReference;
 
 
@@ -53,13 +56,33 @@ public class StreamedSheetWriter
    /*******************************************************************************
     **
     *******************************************************************************/
-   public void beginSheet() throws IOException
+   public void beginSheet(QReportView view, ExcelPoiBasedStreamingStyleCustomizerInterface styleCustomizerInterface) throws IOException
    {
       writer.write("""
          <?xml version="1.0" encoding="UTF-8"?>
-            <worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
-               <sheetData>""");
+            <worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">""");
 
+      if(styleCustomizerInterface != null && view != null)
+      {
+         List<Integer> columnWidths = styleCustomizerInterface.getColumnWidthsForView(view);
+         if(CollectionUtils.nullSafeHasContents(columnWidths))
+         {
+            writer.write("<cols>");
+            for(int i = 0; i < columnWidths.size(); i++)
+            {
+               Integer width = columnWidths.get(i);
+               if(width != null)
+               {
+                  writer.write("""
+                     <col min="%d" max="%d" width="%d" customWidth="1"/>
+                     """.formatted(i + 1, i + 1, width));
+               }
+            }
+            writer.write("</cols>");
+         }
+      }
+
+      writer.write("<sheetData>");
    }
 
 
@@ -67,11 +90,25 @@ public class StreamedSheetWriter
    /*******************************************************************************
     **
     *******************************************************************************/
-   public void endSheet() throws IOException
+   public void endSheet(QReportView view, ExcelPoiBasedStreamingStyleCustomizerInterface styleCustomizerInterface) throws IOException
    {
-      writer.write("""
-            </sheetData>
-         </worksheet>""");
+      writer.write("</sheetData>");
+
+      if(styleCustomizerInterface != null && view != null)
+      {
+         List<String> mergedRanges = styleCustomizerInterface.getMergedRangesForView(view);
+         if(CollectionUtils.nullSafeHasContents(mergedRanges))
+         {
+            writer.write(String.format("<mergeCells count=\"%d\">", mergedRanges.size()));
+            for(String range : mergedRanges)
+            {
+               writer.write(String.format("<mergeCell ref=\"%s\"/>", range));
+            }
+            writer.write("</mergeCells>");
+         }
+      }
+
+      writer.write("</worksheet>");
    }
 
 
@@ -151,7 +188,7 @@ public class StreamedSheetWriter
             {
                rs.append("&quot;");
             }
-            else if (c < 32 && c != '\t' && c != '\n')
+            else if(c < 32 && c != '\t' && c != '\n')
             {
                rs.append(' ');
             }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/scripts/QJavaExecutor.java

@@ -53,7 +53,8 @@ public class QJavaExecutor implements QCodeExecutor
       Serializable output;
       try
       {
-         Function<Map<String, Object>, Serializable> function = QCodeLoader.getFunction(codeReference);
+         @SuppressWarnings("unchecked")
+         Function<Map<String, Object>, Serializable> function = QCodeLoader.getAdHoc(Function.class, codeReference);
          output = function.apply(context);
       }
       catch(Exception e)

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/tables/DeleteAction.java

@@ -246,6 +246,7 @@ public class DeleteAction
       {
          DMLAuditInput dmlAuditInput = new DMLAuditInput()
             .withTableActionInput(deleteInput)
+            .withTransaction(deleteInput.getTransaction())
             .withAuditContext(deleteInput.getAuditContext());
          oldRecordList.ifPresent(l -> dmlAuditInput.setRecordList(l));
          new DMLAuditAction().execute(dmlAuditInput);
@@ -401,6 +402,7 @@ public class DeleteAction
          if(CollectionUtils.nullSafeHasContents(associatedKeys))
          {
             DeleteInput nextLevelDeleteInput = new DeleteInput();
+            nextLevelDeleteInput.setFlags(deleteInput.getFlags());
             nextLevelDeleteInput.setTransaction(deleteInput.getTransaction());
             nextLevelDeleteInput.setTableName(association.getAssociatedTableName());
             nextLevelDeleteInput.setPrimaryKeys(associatedKeys);

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/tables/InsertAction.java

@@ -34,7 +34,6 @@ import java.util.Set;
 import java.util.stream.Collectors;
 import com.kingsrook.qqq.backend.core.actions.AbstractQActionFunction;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
-import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.actions.audits.DMLAuditAction;
 import com.kingsrook.qqq.backend.core.actions.automation.AutomationStatus;
 import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationStatusUpdater;
@@ -54,6 +53,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
@@ -157,7 +157,7 @@ public class InsertAction extends AbstractQActionFunction<InsertInput, InsertOut
       //////////////////////////////////////////////////
       // insert any associations in the input records //
       //////////////////////////////////////////////////
-      manageAssociations(table, insertOutput.getRecords(), insertInput.getTransaction());
+      manageAssociations(table, insertOutput.getRecords(), insertInput);
 
       //////////////////
       // do the audit //
@@ -170,13 +170,26 @@ public class InsertAction extends AbstractQActionFunction<InsertInput, InsertOut
       {
          new DMLAuditAction().execute(new DMLAuditInput()
             .withTableActionInput(insertInput)
+            .withTransaction(insertInput.getTransaction())
             .withAuditContext(insertInput.getAuditContext())
             .withRecordList(insertOutput.getRecords()));
       }
 
-      //////////////////////////////////////////////////////////////
-      // finally, run the post-insert customizer, if there is one //
-      //////////////////////////////////////////////////////////////
+      ////////////////////////////////////////////////////////////////
+      // finally, run the post-insert customizers, if there are any //
+      ////////////////////////////////////////////////////////////////
+      runPostInsertCustomizers(insertInput, table, insertOutput);
+
+      return insertOutput;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static void runPostInsertCustomizers(InsertInput insertInput, QTableMetaData table, InsertOutput insertOutput)
+   {
       Optional<TableCustomizerInterface> postInsertCustomizer = QCodeLoader.getTableCustomizer(table, TableCustomizers.POST_INSERT_RECORD.getRole());
       if(postInsertCustomizer.isPresent())
       {
@@ -193,7 +206,25 @@ public class InsertAction extends AbstractQActionFunction<InsertInput, InsertOut
          }
       }
 
-      return insertOutput;
+      ///////////////////////////////////////////////
+      // run all of the instance-level customizers //
+      ///////////////////////////////////////////////
+      List<QCodeReference> tableCustomizerCodes = QContext.getQInstance().getTableCustomizers(TableCustomizers.POST_INSERT_RECORD);
+      for(QCodeReference tableCustomizerCode : tableCustomizerCodes)
+      {
+         try
+         {
+            TableCustomizerInterface tableCustomizer = QCodeLoader.getAdHoc(TableCustomizerInterface.class, tableCustomizerCode);
+            insertOutput.setRecords(tableCustomizer.postInsert(insertInput, insertOutput.getRecords()));
+         }
+         catch(Exception e)
+         {
+            for(QRecord record : insertOutput.getRecords())
+            {
+               record.addWarning(new QWarningMessage("An error occurred after the insert: " + e.getMessage()));
+            }
+         }
+      }
    }
 
 
@@ -308,6 +339,19 @@ public class InsertAction extends AbstractQActionFunction<InsertInput, InsertOut
             insertInput.setRecords(preInsertCustomizer.get().preInsert(insertInput, insertInput.getRecords(), isPreview));
          }
       }
+
+      ///////////////////////////////////////////////
+      // run all of the instance-level customizers //
+      ///////////////////////////////////////////////
+      List<QCodeReference> tableCustomizerCodes = QContext.getQInstance().getTableCustomizers(TableCustomizers.PRE_INSERT_RECORD);
+      for(QCodeReference tableCustomizerCode : tableCustomizerCodes)
+      {
+         TableCustomizerInterface tableCustomizer = QCodeLoader.getAdHoc(TableCustomizerInterface.class, tableCustomizerCode);
+         if(whenToRun.equals(tableCustomizer.whenToRunPreInsert(insertInput, isPreview)))
+         {
+            insertInput.setRecords(tableCustomizer.preInsert(insertInput, insertInput.getRecords(), isPreview));
+         }
+      }
    }
 
 
@@ -342,7 +386,7 @@ public class InsertAction extends AbstractQActionFunction<InsertInput, InsertOut
    /*******************************************************************************
     **
     *******************************************************************************/
-   private void manageAssociations(QTableMetaData table, List<QRecord> insertedRecords, QBackendTransaction transaction) throws QException
+   private void manageAssociations(QTableMetaData table, List<QRecord> insertedRecords, InsertInput insertInput) throws QException
    {
       for(Association association : CollectionUtils.nonNullList(table.getAssociations()))
       {
@@ -375,7 +419,8 @@ public class InsertAction extends AbstractQActionFunction<InsertInput, InsertOut
          if(CollectionUtils.nullSafeHasContents(nextLevelInserts))
          {
             InsertInput nextLevelInsertInput = new InsertInput();
-            nextLevelInsertInput.setTransaction(transaction);
+            nextLevelInsertInput.withFlags(insertInput.getFlags());
+            nextLevelInsertInput.setTransaction(insertInput.getTransaction());
             nextLevelInsertInput.setTableName(association.getAssociatedTableName());
             nextLevelInsertInput.setRecords(nextLevelInserts);
             InsertOutput nextLevelInsertOutput = new InsertAction().execute(nextLevelInsertInput);

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/tables/ReplaceAction.java

@@ -126,6 +126,7 @@ public class ReplaceAction extends AbstractQActionFunction<ReplaceInput, Replace
          InsertInput insertInput = new InsertInput();
          insertInput.setTableName(table.getName());
          insertInput.setRecords(insertList);
+         insertInput.withFlags(input.getFlags());
          insertInput.setTransaction(transaction);
          insertInput.setOmitDmlAudit(input.getOmitDmlAudit());
          InsertOutput insertOutput = new InsertAction().execute(insertInput);
@@ -135,6 +136,7 @@ public class ReplaceAction extends AbstractQActionFunction<ReplaceInput, Replace
          UpdateInput updateInput = new UpdateInput();
          updateInput.setTableName(table.getName());
          updateInput.setRecords(updateList);
+         updateInput.withFlags(input.getFlags());
          updateInput.setTransaction(transaction);
          updateInput.setOmitDmlAudit(input.getOmitDmlAudit());
          UpdateOutput updateOutput = new UpdateAction().execute(updateInput);
@@ -151,6 +153,7 @@ public class ReplaceAction extends AbstractQActionFunction<ReplaceInput, Replace
             DeleteInput deleteInput = new DeleteInput();
             deleteInput.setTableName(table.getName());
             deleteInput.setQueryFilter(deleteFilter);
+            deleteInput.withFlags(input.getFlags());
             deleteInput.setTransaction(transaction);
             deleteInput.setOmitDmlAudit(input.getOmitDmlAudit());
             DeleteOutput deleteOutput = new DeleteAction().execute(deleteInput);

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/tables/UpdateAction.java

@@ -57,6 +57,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.DynamicDefaultValueBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
@@ -189,6 +190,7 @@ public class UpdateAction
       else
       {
          DMLAuditInput dmlAuditInput = new DMLAuditInput()
+            .withTransaction(updateInput.getTransaction())
             .withTableActionInput(updateInput)
             .withRecordList(updateOutput.getRecords())
             .withAuditContext(updateInput.getAuditContext());
@@ -199,6 +201,18 @@ public class UpdateAction
       //////////////////////////////////////////////////////////////
       // finally, run the post-update customizer, if there is one //
       //////////////////////////////////////////////////////////////
+      runPostUpdateCustomizers(updateInput, table, updateOutput, oldRecordList);
+
+      return updateOutput;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static void runPostUpdateCustomizers(UpdateInput updateInput, QTableMetaData table, UpdateOutput updateOutput, Optional<List<QRecord>> oldRecordList)
+   {
       Optional<TableCustomizerInterface> postUpdateCustomizer = QCodeLoader.getTableCustomizer(table, TableCustomizers.POST_UPDATE_RECORD.getRole());
       if(postUpdateCustomizer.isPresent())
       {
@@ -215,7 +229,49 @@ public class UpdateAction
          }
       }
 
-      return updateOutput;
+      ///////////////////////////////////////////////
+      // run all of the instance-level customizers //
+      ///////////////////////////////////////////////
+      List<QCodeReference> tableCustomizerCodes = QContext.getQInstance().getTableCustomizers(TableCustomizers.POST_UPDATE_RECORD);
+      for(QCodeReference tableCustomizerCode : tableCustomizerCodes)
+      {
+         try
+         {
+            TableCustomizerInterface tableCustomizer = QCodeLoader.getAdHoc(TableCustomizerInterface.class, tableCustomizerCode);
+            updateOutput.setRecords(tableCustomizer.postUpdate(updateInput, updateOutput.getRecords(), oldRecordList));
+         }
+         catch(Exception e)
+         {
+            for(QRecord record : updateOutput.getRecords())
+            {
+               record.addWarning(new QWarningMessage("An error occurred after the update: " + e.getMessage()));
+            }
+         }
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static void runPreUpdateCustomizers(UpdateInput updateInput, QTableMetaData table, Optional<List<QRecord>> oldRecordList, boolean isPreview) throws QException
+   {
+      Optional<TableCustomizerInterface> preUpdateCustomizer = QCodeLoader.getTableCustomizer(table, TableCustomizers.PRE_UPDATE_RECORD.getRole());
+      if(preUpdateCustomizer.isPresent())
+      {
+         updateInput.setRecords(preUpdateCustomizer.get().preUpdate(updateInput, updateInput.getRecords(), isPreview, oldRecordList));
+      }
+
+      ///////////////////////////////////////////////
+      // run all of the instance-level customizers //
+      ///////////////////////////////////////////////
+      List<QCodeReference> tableCustomizerCodes = QContext.getQInstance().getTableCustomizers(TableCustomizers.PRE_UPDATE_RECORD);
+      for(QCodeReference tableCustomizerCode : tableCustomizerCodes)
+      {
+         TableCustomizerInterface tableCustomizer = QCodeLoader.getAdHoc(TableCustomizerInterface.class, tableCustomizerCode);
+         updateInput.setRecords(tableCustomizer.preUpdate(updateInput, updateInput.getRecords(), isPreview, oldRecordList));
+      }
    }
 
 
@@ -278,11 +334,7 @@ public class UpdateAction
       ///////////////////////////////////////////////////////////////////////////
       // after all validations, run the pre-update customizer, if there is one //
       ///////////////////////////////////////////////////////////////////////////
-      Optional<TableCustomizerInterface> preUpdateCustomizer = QCodeLoader.getTableCustomizer(table, TableCustomizers.PRE_UPDATE_RECORD.getRole());
-      if(preUpdateCustomizer.isPresent())
-      {
-         updateInput.setRecords(preUpdateCustomizer.get().preUpdate(updateInput, updateInput.getRecords(), isPreview, oldRecordList));
-      }
+      runPreUpdateCustomizers(updateInput, table, oldRecordList, isPreview);
    }
 
 
@@ -405,7 +457,7 @@ public class UpdateAction
                   QFieldType   fieldType = table.getField(lock.getFieldName()).getType();
                   Serializable lockValue = ValueUtils.getValueAsFieldType(fieldType, oldRecord.getValue(lock.getFieldName()));
 
-                  List<QErrorMessage> errors = ValidateRecordSecurityLockHelper.validateRecordSecurityValue(table, lock, lockValue, fieldType, ValidateRecordSecurityLockHelper.Action.UPDATE, Collections.emptyMap());
+                  List<QErrorMessage> errors = ValidateRecordSecurityLockHelper.validateRecordSecurityValue(table, lock, lockValue, fieldType, ValidateRecordSecurityLockHelper.Action.UPDATE, Collections.emptyMap(), QContext.getQSession());
                   if(CollectionUtils.nullSafeHasContents(errors))
                   {
                      errors.forEach(e -> record.addError(e));
@@ -554,6 +606,7 @@ public class UpdateAction
                {
                   LOG.debug("Deleting associatedRecords", logPair("associatedTable", associatedTable.getName()), logPair("noOfRecords", queryOutput.getRecords().size()));
                   DeleteInput deleteInput = new DeleteInput();
+                  deleteInput.setFlags(updateInput.getFlags());
                   deleteInput.setTransaction(updateInput.getTransaction());
                   deleteInput.setTableName(association.getAssociatedTableName());
                   deleteInput.setPrimaryKeys(queryOutput.getRecords().stream().map(r -> r.getValue(associatedTable.getPrimaryKeyField())).collect(Collectors.toList()));
@@ -566,6 +619,7 @@ public class UpdateAction
                LOG.debug("Updating associatedRecords", logPair("associatedTable", associatedTable.getName()), logPair("noOfRecords", nextLevelUpdates.size()));
                UpdateInput nextLevelUpdateInput = new UpdateInput();
                nextLevelUpdateInput.setTransaction(updateInput.getTransaction());
+               nextLevelUpdateInput.setFlags(updateInput.getFlags());
                nextLevelUpdateInput.setTableName(association.getAssociatedTableName());
                nextLevelUpdateInput.setRecords(nextLevelUpdates);
                UpdateOutput nextLevelUpdateOutput = new UpdateAction().execute(nextLevelUpdateInput);
@@ -576,6 +630,7 @@ public class UpdateAction
                LOG.debug("Inserting associatedRecords", logPair("associatedTable", associatedTable.getName()), logPair("noOfRecords", nextLevelUpdates.size()));
                InsertInput nextLevelInsertInput = new InsertInput();
                nextLevelInsertInput.setTransaction(updateInput.getTransaction());
+               nextLevelInsertInput.setFlags(updateInput.getFlags());
                nextLevelInsertInput.setTableName(association.getAssociatedTableName());
                nextLevelInsertInput.setRecords(nextLevelInserts);
                InsertOutput nextLevelInsertOutput = new InsertAction().execute(nextLevelInsertInput);

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/tables/helpers/QueryActionCacheHelper.java

@@ -41,6 +41,7 @@ import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
 import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
@@ -569,7 +570,7 @@ public class QueryActionCacheHelper
 
          QQueryFilter filter = new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR);
          sourceQueryInput.setFilter(filter);
-         sourceQueryInput.setCommonParamsFrom(cacheQueryInput);
+         ((QueryOrGetInputInterface) sourceQueryInput).setCommonParamsFrom(cacheQueryInput);
 
          for(List<Serializable> uniqueKeyValue : uniqueKeyValues)
          {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/tables/helpers/ValidateRecordSecurityLockHelper.java

@@ -50,6 +50,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.security.QSecurityKeyType;
 import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLockFilters;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.model.statusmessages.PermissionDeniedMessage;
 import com.kingsrook.qqq.backend.core.model.statusmessages.QErrorMessage;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
@@ -102,7 +103,7 @@ public class ValidateRecordSecurityLockHelper
       // actually check lock values //
       ////////////////////////////////
       Map<Serializable, RecordWithErrors> errorRecords = new HashMap<>();
-      evaluateRecordLocks(table, records, action, locksToCheck, errorRecords, new ArrayList<>(), madeUpPrimaryKeys, transaction);
+      evaluateRecordLocks(table, records, action, locksToCheck, errorRecords, new ArrayList<>(), madeUpPrimaryKeys, transaction, QContext.getQSession());
 
       /////////////////////////////////
       // propagate errors to records //
@@ -124,6 +125,29 @@ public class ValidateRecordSecurityLockHelper
 
 
 
+   /***************************************************************************
+    ** return boolean if given session can read given record
+    ***************************************************************************/
+   public static boolean allowedToReadRecord(QTableMetaData table, QRecord record, QSession qSession, QBackendTransaction transaction) throws QException
+   {
+      MultiRecordSecurityLock locksToCheck = getRecordSecurityLocks(table, Action.SELECT);
+      if(locksToCheck == null || CollectionUtils.nullSafeIsEmpty(locksToCheck.getLocks()))
+      {
+         return (true);
+      }
+
+      Map<Serializable, RecordWithErrors> errorRecords = new HashMap<>();
+      evaluateRecordLocks(table, List.of(record), Action.SELECT, locksToCheck, errorRecords, new ArrayList<>(), Collections.emptyMap(), transaction, qSession);
+      if(errorRecords.containsKey(record.getValue(table.getPrimaryKeyField())))
+      {
+         return (false);
+      }
+
+      return (true);
+   }
+
+
+
    /*******************************************************************************
     ** For a list of `records` from a `table`, and a given `action`, evaluate a
     ** `recordSecurityLock` (which may be a multi-lock) - populating the input map
@@ -142,7 +166,7 @@ public class ValidateRecordSecurityLockHelper
     ** BUT - WRITE locks - in their case, we read the record no matter what, and in
     ** here we need to verify we have a key that allows us to WRITE the record.
     *******************************************************************************/
-   private static void evaluateRecordLocks(QTableMetaData table, List<QRecord> records, Action action, RecordSecurityLock recordSecurityLock, Map<Serializable, RecordWithErrors> errorRecords, List<Integer> treePosition, Map<Serializable, QRecord> madeUpPrimaryKeys, QBackendTransaction transaction) throws QException
+   private static void evaluateRecordLocks(QTableMetaData table, List<QRecord> records, Action action, RecordSecurityLock recordSecurityLock, Map<Serializable, RecordWithErrors> errorRecords, List<Integer> treePosition, Map<Serializable, QRecord> madeUpPrimaryKeys, QBackendTransaction transaction, QSession qSession) throws QException
    {
       if(recordSecurityLock instanceof MultiRecordSecurityLock multiRecordSecurityLock)
       {
@@ -153,7 +177,7 @@ public class ValidateRecordSecurityLockHelper
          for(RecordSecurityLock childLock : CollectionUtils.nonNullList(multiRecordSecurityLock.getLocks()))
          {
             treePosition.add(i);
-            evaluateRecordLocks(table, records, action, childLock, errorRecords, treePosition, madeUpPrimaryKeys, transaction);
+            evaluateRecordLocks(table, records, action, childLock, errorRecords, treePosition, madeUpPrimaryKeys, transaction, qSession);
             treePosition.remove(treePosition.size() - 1);
             i++;
          }
@@ -165,7 +189,7 @@ public class ValidateRecordSecurityLockHelper
       // if this lock has an all-access key, and the user has that key, then there can't be any errors here, so return early //
       /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
       QSecurityKeyType securityKeyType = QContext.getQInstance().getSecurityKeyType(recordSecurityLock.getSecurityKeyType());
-      if(StringUtils.hasContent(securityKeyType.getAllAccessKeyName()) && QContext.getQSession().hasSecurityKeyValue(securityKeyType.getAllAccessKeyName(), true, QFieldType.BOOLEAN))
+      if(StringUtils.hasContent(securityKeyType.getAllAccessKeyName()) && qSession.hasSecurityKeyValue(securityKeyType.getAllAccessKeyName(), true, QFieldType.BOOLEAN))
       {
          return;
       }
@@ -193,7 +217,7 @@ public class ValidateRecordSecurityLockHelper
             }
 
             Serializable        recordSecurityValue = record.getValue(field.getName());
-            List<QErrorMessage> recordErrors        = validateRecordSecurityValue(table, recordSecurityLock, recordSecurityValue, field.getType(), action, madeUpPrimaryKeys);
+            List<QErrorMessage> recordErrors        = validateRecordSecurityValue(table, recordSecurityLock, recordSecurityValue, field.getType(), action, madeUpPrimaryKeys, qSession);
             if(CollectionUtils.nullSafeHasContents(recordErrors))
             {
                errorRecords.computeIfAbsent(record.getValue(primaryKeyField), (k) -> new RecordWithErrors(record)).addAll(recordErrors, treePosition);
@@ -339,7 +363,7 @@ public class ValidateRecordSecurityLockHelper
 
                   for(QRecord inputRecord : inputRecords)
                   {
-                     List<QErrorMessage> recordErrors = validateRecordSecurityValue(table, recordSecurityLock, recordSecurityValue, field.getType(), action, madeUpPrimaryKeys);
+                     List<QErrorMessage> recordErrors = validateRecordSecurityValue(table, recordSecurityLock, recordSecurityValue, field.getType(), action, madeUpPrimaryKeys, qSession);
                      if(CollectionUtils.nullSafeHasContents(recordErrors))
                      {
                         errorRecords.computeIfAbsent(inputRecord.getValue(primaryKeyField), (k) -> new RecordWithErrors(inputRecord)).addAll(recordErrors, treePosition);
@@ -446,7 +470,7 @@ public class ValidateRecordSecurityLockHelper
    /*******************************************************************************
     **
     *******************************************************************************/
-   public static List<QErrorMessage> validateRecordSecurityValue(QTableMetaData table, RecordSecurityLock recordSecurityLock, Serializable recordSecurityValue, QFieldType fieldType, Action action, Map<Serializable, QRecord> madeUpPrimaryKeys)
+   public static List<QErrorMessage> validateRecordSecurityValue(QTableMetaData table, RecordSecurityLock recordSecurityLock, Serializable recordSecurityValue, QFieldType fieldType, Action action, Map<Serializable, QRecord> madeUpPrimaryKeys, QSession qSession)
    {
       if(recordSecurityValue == null || (madeUpPrimaryKeys != null && madeUpPrimaryKeys.containsKey(recordSecurityValue)))
       {
@@ -461,7 +485,7 @@ public class ValidateRecordSecurityLockHelper
       }
       else
       {
-         if(!QContext.getQSession().hasSecurityKeyValue(recordSecurityLock.getSecurityKeyType(), recordSecurityValue, fieldType))
+         if(!qSession.hasSecurityKeyValue(recordSecurityLock.getSecurityKeyType(), recordSecurityValue, fieldType))
          {
             if(CollectionUtils.nullSafeHasContents(recordSecurityLock.getJoinNameChain()))
             {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/templates/ConvertHtmlToPdfAction.java

@@ -26,22 +26,32 @@ import java.nio.file.Path;
 import java.util.Map;
 import com.kingsrook.qqq.backend.core.actions.AbstractQActionFunction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.templates.ConvertHtmlToPdfInput;
 import com.kingsrook.qqq.backend.core.model.actions.templates.ConvertHtmlToPdfOutput;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.openhtmltopdf.css.constants.IdentValue;
+import com.openhtmltopdf.pdfboxout.PdfBoxFontResolver;
+import com.openhtmltopdf.pdfboxout.PdfBoxRenderer;
+import com.openhtmltopdf.pdfboxout.PdfRendererBuilder;
 import org.jsoup.Jsoup;
+import org.jsoup.helper.W3CDom;
 import org.jsoup.nodes.Document;
-import org.xhtmlrenderer.layout.SharedContext;
-import org.xhtmlrenderer.pdf.ITextRenderer;
 
 
 /*******************************************************************************
  ** Action to convert a string of HTML to a PDF!
  **
  ** Much credit to https://www.baeldung.com/java-html-to-pdf
- *******************************************************************************/
+ **
+ ** Updated in March 2025 to go from flying-saucer-pdf-openpdf lib to openhtmltopdf,
+ ** mostly to get support for max-height on images...
+ ********************************************************************************/
 public class ConvertHtmlToPdfAction extends AbstractQActionFunction<ConvertHtmlToPdfInput, ConvertHtmlToPdfOutput>
 {
+   private static final QLogger LOG = QLogger.getLogger(ConvertHtmlToPdfAction.class);
+
+
 
    /*******************************************************************************
     **
@@ -58,35 +68,37 @@ public class ConvertHtmlToPdfAction extends AbstractQActionFunction<ConvertHtmlT
          //////////////////////////////////////////////////////////////////
          Document document = Jsoup.parse(input.getHtml());
          document.outputSettings().syntax(Document.OutputSettings.Syntax.xml);
+         org.w3c.dom.Document w3cDoc = new W3CDom().fromJsoup(document);
 
          //////////////////////////////
          // convert the XHTML to PDF //
          //////////////////////////////
-         ITextRenderer renderer      = new ITextRenderer();
-         SharedContext sharedContext = renderer.getSharedContext();
-         sharedContext.setPrint(true);
-         sharedContext.setInteractive(false);
+         PdfRendererBuilder builder = new PdfRendererBuilder();
+         builder.toStream(input.getOutputStream());
+         builder.useFastMode();
+         builder.withW3cDocument(w3cDoc, input.getBasePath() == null ? "./" : input.getBasePath().toUri().toString());
 
-         if(input.getBasePath() != null)
+         try(PdfBoxRenderer pdfBoxRenderer = builder.buildPdfRenderer())
          {
-            String baseUrl = input.getBasePath().toUri().toURL().toString();
-            renderer.setDocumentFromString(document.html(), baseUrl);
-         }
-         else
-         {
-            renderer.setDocumentFromString(document.html());
-         }
+            pdfBoxRenderer.layout();
+            pdfBoxRenderer.getSharedContext().setPrint(true);
+            pdfBoxRenderer.getSharedContext().setInteractive(false);
 
-         //////////////////////////////////////////////////
-         // register any custom fonts the input supplied //
-         //////////////////////////////////////////////////
-         for(Map.Entry<String, Path> entry : CollectionUtils.nonNullMap(input.getCustomFonts()).entrySet())
-         {
-            renderer.getFontResolver().addFont(entry.getValue().toAbsolutePath().toString(), entry.getKey(), "UTF-8", true, null);
-         }
+            for(Map.Entry<String, Path> entry : CollectionUtils.nonNullMap(input.getCustomFonts()).entrySet())
+            {
+               LOG.warn("Note:  Custom fonts appear to not be working in this class at this time...");
+               pdfBoxRenderer.getFontResolver().addFont(
+                  entry.getValue().toAbsolutePath().toFile(), // Path to the TrueType font file
+                  entry.getKey(),                             // Font family name to use in CSS
+                  400,                                        // Font weight (e.g., 400 for normal, 700 for bold)
+                  IdentValue.NORMAL,                          // Font style (e.g., NORMAL, ITALIC)
+                  true,                                       // Whether to subset the font
+                  PdfBoxFontResolver.FontGroup.MAIN           // ??
+               );
+            }
 
-         renderer.layout();
-         renderer.createPDF(input.getOutputStream());
+            pdfBoxRenderer.createPDF();
+         }
 
          return (output);
       }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/values/BasicCustomPossibleValueProvider.java

@@ -0,0 +1,91 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.values;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.values.SearchPossibleValueSourceInput;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
+
+
+/*******************************************************************************
+ ** Basic implementation of a possible value provider, for where there's a limited
+ ** set of possible source objects - so you just have to define how to make one
+ ** PV from a source object, how to list all of the source objects, and how to
+ ** look up a PV from an id.
+ *******************************************************************************/
+public abstract class BasicCustomPossibleValueProvider<S, ID extends Serializable> implements QCustomPossibleValueProvider<ID>
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   protected abstract QPossibleValue<ID> makePossibleValue(S sourceObject);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   protected abstract S getSourceObject(Serializable id) throws QException;
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   protected abstract List<S> getAllSourceObjects() throws QException;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QPossibleValue<ID> getPossibleValue(Serializable idValue) throws QException
+   {
+      S sourceObject = getSourceObject(idValue);
+      if(sourceObject == null)
+      {
+         return (null);
+      }
+
+      return makePossibleValue(sourceObject);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public List<QPossibleValue<ID>> search(SearchPossibleValueSourceInput input) throws QException
+   {
+      List<QPossibleValue<ID>> allPossibleValues = new ArrayList<>();
+      List<S>                  allSourceObjects  = getAllSourceObjects();
+      for(S sourceObject : allSourceObjects)
+      {
+         allPossibleValues.add(makePossibleValue(sourceObject));
+      }
+
+      return completeCustomPVSSearch(input, allPossibleValues);
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/values/QCustomPossibleValueProvider.java

@@ -45,7 +45,7 @@ public interface QCustomPossibleValueProvider<T extends Serializable>
    /*******************************************************************************
     **
     *******************************************************************************/
-   QPossibleValue<T> getPossibleValue(Serializable idValue);
+   QPossibleValue<T> getPossibleValue(Serializable idValue) throws QException;
 
    /*******************************************************************************
     **

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/values/QPossibleValueTranslator.java

@@ -341,7 +341,7 @@ public class QPossibleValueTranslator
 
       try
       {
-         QCustomPossibleValueProvider customPossibleValueProvider = QCodeLoader.getCustomPossibleValueProvider(possibleValueSource);
+         QCustomPossibleValueProvider<?> customPossibleValueProvider = QCodeLoader.getAdHoc(QCustomPossibleValueProvider.class, possibleValueSource.getCustomCodeReference());
          return (formatPossibleValue(possibleValueSource, customPossibleValueProvider.getPossibleValue(value)));
       }
       catch(Exception e)

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/values/QValueFormatter.java

@@ -310,6 +310,19 @@ public class QValueFormatter
 
 
 
+   /*******************************************************************************
+    ** For a list of records, set their recordLabels and display values - including
+    ** record label (e.g., from the table meta data).
+    *******************************************************************************/
+   public static void setDisplayValuesInRecordsIncludingPossibleValueTranslations(QTableMetaData table, List<QRecord> records)
+   {
+      QPossibleValueTranslator possibleValueTranslator = new QPossibleValueTranslator(QContext.getQInstance(), QContext.getQSession());
+      possibleValueTranslator.translatePossibleValuesInRecords(table, records);
+      setDisplayValuesInRecords(table, records);
+   }
+
+
+
    /*******************************************************************************
     ** For a list of records, set their recordLabels and display values - including
     ** record label (e.g., from the table meta data).

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/values/SearchPossibleValueSourceAction.java

@@ -424,7 +424,7 @@ public class SearchPossibleValueSourceAction
    {
       try
       {
-         QCustomPossibleValueProvider customPossibleValueProvider = QCodeLoader.getCustomPossibleValueProvider(possibleValueSource);
+         QCustomPossibleValueProvider customPossibleValueProvider = QCodeLoader.getAdHoc(QCustomPossibleValueProvider.class, possibleValueSource.getCustomCodeReference());
          List<QPossibleValue<?>>      possibleValues              = customPossibleValueProvider.search(input);
 
          SearchPossibleValueSourceOutput output = new SearchPossibleValueSourceOutput();

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/AbstractMetaDataProducerBasedQQQApplication.java

@@ -29,7 +29,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 
 /*******************************************************************************
  ** Version of AbstractQQQApplication that assumes all meta-data is produced
- ** by MetaDataProducers in a single package.
+ ** by MetaDataProducers in (or under) a single package.
  *******************************************************************************/
 public abstract class AbstractMetaDataProducerBasedQQQApplication extends AbstractQQQApplication
 {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/ConfigFilesBasedQQQApplication.java

@@ -0,0 +1,61 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.instances.loaders.MetaDataLoaderHelper;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** Version of AbstractQQQApplication that assumes all meta-data is defined in
+ ** config files (yaml, json, etc) under a given directory path.
+ *******************************************************************************/
+public class ConfigFilesBasedQQQApplication extends AbstractQQQApplication
+{
+   private final String path;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public ConfigFilesBasedQQQApplication(String path)
+   {
+      this.path = path;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QInstance defineQInstance() throws QException
+   {
+      QInstance qInstance = new QInstance();
+      MetaDataLoaderHelper.processAllMetaDataFilesInDirectory(qInstance, path);
+      return (qInstance);
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/MetaDataProducerBasedQQQApplication.java

@@ -0,0 +1,67 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances;
+
+
+/*******************************************************************************
+ ** Version of AbstractQQQApplication that assumes all meta-data is produced
+ ** by MetaDataProducers in (or under) a single package (where you can pass that
+ ** package into the constructor, vs. the abstract base class, where you extend
+ ** it and override the getMetaDataPackageName method.
+ *******************************************************************************/
+public class MetaDataProducerBasedQQQApplication extends AbstractMetaDataProducerBasedQQQApplication
+{
+   private final String metaDataPackageName;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public MetaDataProducerBasedQQQApplication(String metaDataPackageName)
+   {
+      this.metaDataPackageName = metaDataPackageName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public MetaDataProducerBasedQQQApplication(Class<?> aClassInMetaDataPackage)
+   {
+      this(aClassInMetaDataPackage.getPackageName());
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public String getMetaDataPackageName()
+   {
+      return (this.metaDataPackageName);
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/QHelpContentPlugin.java

@@ -0,0 +1,46 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances;
+
+
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
+
+
+/*******************************************************************************
+ * interface that can be added to a QSupplementalInstanceMetaData, to receive
+ * QHelpContent records during instance boot or upon updates in the help content
+ * table.
+ *******************************************************************************/
+public interface QHelpContentPlugin
+{
+   /***************************************************************************
+    * accept a single helpContent record, and apply its data to some data in the
+    * qInstance
+    *
+    * @param qInstance the active qInstance, that the content should be applied to
+    * @param helpContent entity with values from HelpContent table
+    * @param nameValuePairs parsed string -> string map from the help content key.
+    ***************************************************************************/
+   void acceptHelpContent(QInstance qInstance, QHelpContent helpContent, Map<String, String> nameValuePairs);
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/QInstanceEnricher.java

@@ -31,7 +31,9 @@ import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
+import java.util.Iterator;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
@@ -43,10 +45,12 @@ import com.kingsrook.qqq.backend.core.actions.metadata.JoinGraph;
 import com.kingsrook.qqq.backend.core.actions.permissions.BulkTableActionProcessPermissionChecker;
 import com.kingsrook.qqq.backend.core.actions.values.QCustomPossibleValueProvider;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QRuntimeException;
 import com.kingsrook.qqq.backend.core.instances.enrichment.plugins.QInstanceEnricherPluginInterface;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
@@ -55,6 +59,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.DynamicDefaultValueB
 import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldAdornment;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QSupplementalFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppChildMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
@@ -210,6 +215,37 @@ public class QInstanceEnricher
     ***************************************************************************/
    private void enrichInstance()
    {
+      ////////////////////////////////////////////////////////////////////////////////////
+      // enriching some objects may cause additional ones to be added to the qInstance! //
+      // this caused concurrent modification exceptions, when we just iterated.         //
+      // we could make a copy of the map and just process that, but then we wouldn't    //
+      // enrich any new objects that do get added, so, use this technique instead.      //
+      ////////////////////////////////////////////////////////////////////////////////////
+      Set<QSupplementalInstanceMetaData> toEnrich = new LinkedHashSet<>(qInstance.getSupplementalMetaData().values());
+      Set<QSupplementalInstanceMetaData> enriched = new HashSet<>();
+      int count = 0;
+      while(!toEnrich.isEmpty())
+      {
+         Iterator<QSupplementalInstanceMetaData> iterator                     = toEnrich.iterator();
+         QSupplementalInstanceMetaData           supplementalInstanceMetaData = iterator.next();
+         iterator.remove();
+
+         supplementalInstanceMetaData.enrich(qInstance);
+         enriched.add(supplementalInstanceMetaData);
+
+         for(QSupplementalInstanceMetaData possiblyNew : qInstance.getSupplementalMetaData().values())
+         {
+            if(!toEnrich.contains(possiblyNew) && !enriched.contains(possiblyNew))
+            {
+               if(count++ > 100)
+               {
+                  throw (new QRuntimeException("Too many new QSupplementalInstanceMetaData objects were added while enriching others.  This probably indicates a bug in enrichment code.  Throwing to prevent infinite loop."));
+               }
+               toEnrich.add(possiblyNew);
+            }
+         }
+      }
+
       runPlugins(QInstance.class, qInstance, qInstance);
    }
 
@@ -330,7 +366,21 @@ public class QInstanceEnricher
 
       if(table.getFields() != null)
       {
-         table.getFields().values().forEach(this::enrichField);
+         for(Map.Entry<String, QFieldMetaData> entry : table.getFields().entrySet())
+         {
+            String         name  = entry.getKey();
+            QFieldMetaData field = entry.getValue();
+
+            ////////////////////////////////////////////////////////////////////////////
+            // in case the field wasn't given a name, use its key from the fields map //
+            ////////////////////////////////////////////////////////////////////////////
+            if(!StringUtils.hasContent(field.getName()))
+            {
+               field.setName(name);
+            }
+
+            enrichField(field);
+         }
 
          for(QSupplementalTableMetaData supplementalTableMetaData : CollectionUtils.nonNullMap(table.getSupplementalMetaData()).values())
          {
@@ -568,6 +618,14 @@ public class QInstanceEnricher
          }
       }
 
+      ////////////////////////////////////////////////////
+      // enrich any supplemental meta data on the field //
+      ////////////////////////////////////////////////////
+      for(QSupplementalFieldMetaData supplementalFieldMetaData : CollectionUtils.nonNullMap(field.getSupplementalMetaData()).values())
+      {
+         supplementalFieldMetaData.enrich(qInstance, field);
+      }
+
       runPlugins(QFieldMetaData.class, field, qInstance);
    }
 
@@ -970,16 +1028,16 @@ public class QInstanceEnricher
          .withCode(new QCodeReference(BulkInsertReceiveValueMappingStep.class));
 
       int i = 0;
-      process.addStep(i++, prepareFileUploadStep);
-      process.addStep(i++, uploadScreen);
+      process.withStep(i++, prepareFileUploadStep);
+      process.withStep(i++, uploadScreen);
 
-      process.addStep(i++, prepareFileMappingStep);
-      process.addStep(i++, fileMappingScreen);
-      process.addStep(i++, receiveFileMappingStep);
+      process.withStep(i++, prepareFileMappingStep);
+      process.withStep(i++, fileMappingScreen);
+      process.withStep(i++, receiveFileMappingStep);
 
-      process.addStep(i++, prepareValueMappingStep);
-      process.addStep(i++, valueMappingScreen);
-      process.addStep(i++, receiveValueMappingStep);
+      process.withStep(i++, prepareValueMappingStep);
+      process.withStep(i++, valueMappingScreen);
+      process.withStep(i++, receiveValueMappingStep);
 
       process.getFrontendStep(StreamedETLWithFrontendProcess.STEP_NAME_REVIEW).setRecordListFields(editableFields);
 
@@ -1039,7 +1097,7 @@ public class QInstanceEnricher
                Fields whose switches are off will not be updated."""))
          .withComponent(new QFrontendComponentMetaData().withType(QComponentType.BULK_EDIT_FORM));
 
-      process.addStep(0, editScreen);
+      process.withStep(0, editScreen);
       process.getFrontendStep("review").setRecordListFields(editableFields);
       qInstance.addProcess(process);
    }
@@ -1390,10 +1448,10 @@ public class QInstanceEnricher
          if(possibleValueSource.getIdType() == null)
          {
             QTableMetaData table = qInstance.getTable(possibleValueSource.getTableName());
-            if(table != null)
+            if(table != null && table.getFields() != null)
             {
                String         primaryKeyField         = table.getPrimaryKeyField();
-               QFieldMetaData primaryKeyFieldMetaData = table.getFields().get(primaryKeyField);
+               QFieldMetaData primaryKeyFieldMetaData = CollectionUtils.nonNullMap(table.getFields()).get(primaryKeyField);
                if(primaryKeyFieldMetaData != null)
                {
                   possibleValueSource.setIdType(primaryKeyFieldMetaData.getType());
@@ -1425,9 +1483,9 @@ public class QInstanceEnricher
          {
             try
             {
-               QCustomPossibleValueProvider<?> customPossibleValueProvider = QCodeLoader.getCustomPossibleValueProvider(possibleValueSource);
+               QCustomPossibleValueProvider<?> customPossibleValueProvider = QCodeLoader.getAdHoc(QCustomPossibleValueProvider.class, possibleValueSource.getCustomCodeReference());
 
-               Method getPossibleValueMethod = customPossibleValueProvider.getClass().getDeclaredMethod("getPossibleValue", Serializable.class);
+               Method getPossibleValueMethod = customPossibleValueProvider.getClass().getMethod("getPossibleValue", Serializable.class);
                Type   returnType             = getPossibleValueMethod.getGenericReturnType();
                Type   idType                 = ((ParameterizedType) returnType).getActualTypeArguments()[0];
 
@@ -1463,7 +1521,18 @@ public class QInstanceEnricher
       if(enrichMethod.isPresent())
       {
          Class<?> parameterType = enrichMethod.get().getParameterTypes()[0];
-         enricherPlugins.add(parameterType, plugin);
+
+         Set<String> existingPluginIdentifiers = enricherPlugins.getOrDefault(parameterType, Collections.emptyList())
+            .stream().map(p -> p.getPluginIdentifier())
+            .collect(Collectors.toSet());
+         if(existingPluginIdentifiers.contains(plugin.getPluginIdentifier()))
+         {
+            LOG.debug("Enricher plugin is already registered - not re-adding it", logPair("pluginIdentifer", plugin.getPluginIdentifier()));
+         }
+         else
+         {
+            enricherPlugins.add(parameterType, plugin);
+         }
       }
       else
       {
@@ -1483,6 +1552,17 @@ public class QInstanceEnricher
 
 
 
+   /*******************************************************************************
+    ** Getter for enricherPlugins
+    **
+    *******************************************************************************/
+   public static ListingHash<Class<?>, QInstanceEnricherPluginInterface<?>> getEnricherPlugins()
+   {
+      return enricherPlugins;
+   }
+
+
+
    /***************************************************************************
     ** scan the classpath for classes in the specified package name which
     ** implement the QInstanceEnricherPluginInterface - any found get added

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/QInstanceHelpContentManager.java

@@ -36,6 +36,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.helpcontent.HelpContent;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.help.HelpFormat;
@@ -163,6 +164,23 @@ public class QInstanceHelpContentManager
          {
             processHelpContentForInstance(qInstance, key, slotName, roles, helpContent);
          }
+         else
+         {
+            for(QSupplementalInstanceMetaData supplementalInstanceMetaData : qInstance.getSupplementalMetaData().values())
+            {
+               if(supplementalInstanceMetaData instanceof QHelpContentPlugin helpContentPlugin)
+               {
+                  try
+                  {
+                     helpContentPlugin.acceptHelpContent(qInstance, helpContent, nameValuePairs);
+                  }
+                  catch(Exception e)
+                  {
+                     LOG.warn("Error processing a helpContent record in a helpContentPlugin", e, logPair("pluginName", supplementalInstanceMetaData.getName()), logPair("id", record.getValue("id")));
+                  }
+               }
+            }
+         }
       }
       catch(Exception e)
       {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/QInstanceValidator.java

@@ -41,10 +41,12 @@ import java.util.function.Function;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
-import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandler;
+import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandlerInterface;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
 import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
 import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
 import com.kingsrook.qqq.backend.core.actions.metadata.JoinGraph;
+import com.kingsrook.qqq.backend.core.actions.metadata.MetaDataActionCustomizerInterface;
 import com.kingsrook.qqq.backend.core.actions.metadata.MetaDataFilterInterface;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.actions.reporting.customizers.ReportCustomRecordSourceInterface;
@@ -63,6 +65,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaDa
 import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.automation.QAutomationProviderMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReferenceLambda;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeType;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.ParentWidgetMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaDataInterface;
@@ -70,6 +73,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldAdornment;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QSupplementalFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.ValueTooLongBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
@@ -237,14 +241,32 @@ public class QInstanceValidator
 
 
    /***************************************************************************
-    **
+    * this method still supports the deprecated MetaDataFilter (plus its
+    * replacement, MetaDataActionCustomizer
     ***************************************************************************/
+   @SuppressWarnings("deprecation")
    private void validateInstanceAttributes(QInstance qInstance)
    {
       if(qInstance.getMetaDataFilter() != null)
       {
          validateSimpleCodeReference("Instance metaDataFilter ", qInstance.getMetaDataFilter(), MetaDataFilterInterface.class);
       }
+
+      if(qInstance.getMetaDataActionCustomizer() != null)
+      {
+         validateSimpleCodeReference("Instance metaDataActionCustomizer ", qInstance.getMetaDataActionCustomizer(), MetaDataActionCustomizerInterface.class);
+      }
+
+      if(qInstance.getTableCustomizers() != null)
+      {
+         for(Map.Entry<String, List<QCodeReference>> entry : qInstance.getTableCustomizers().entrySet())
+         {
+            for(QCodeReference codeReference : CollectionUtils.nonNullList(entry.getValue()))
+            {
+               validateSimpleCodeReference("Instance tableCustomizer of type " + entry.getKey() + ": ", codeReference, TableCustomizerInterface.class);
+            }
+         }
+      }
    }
 
 
@@ -276,7 +298,18 @@ public class QInstanceValidator
       if(validateMethod.isPresent())
       {
          Class<?> parameterType = validateMethod.get().getParameterTypes()[0];
-         validatorPlugins.add(parameterType, plugin);
+
+         Set<String> existingPluginIdentifiers = validatorPlugins.getOrDefault(parameterType, Collections.emptyList())
+            .stream().map(p -> p.getPluginIdentifier())
+            .collect(Collectors.toSet());
+         if(existingPluginIdentifiers.contains(plugin.getPluginIdentifier()))
+         {
+            LOG.debug("Validator plugin is already registered - not re-adding it", logPair("pluginIdentifer", plugin.getPluginIdentifier()));
+         }
+         else
+         {
+            validatorPlugins.add(parameterType, plugin);
+         }
       }
       else
       {
@@ -296,6 +329,17 @@ public class QInstanceValidator
 
 
 
+   /*******************************************************************************
+    ** Getter for validatorPlugins
+    **
+    *******************************************************************************/
+   public static ListingHash<Class<?>, QInstanceValidatorPluginInterface<?>> getValidatorPlugins()
+   {
+      return validatorPlugins;
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -645,6 +689,8 @@ public class QInstanceValidator
             validateSimpleCodeReference("Instance Authentication meta data customizer ", authentication.getCustomizer(), QAuthenticationModuleCustomizerInterface.class);
          }
 
+         authentication.validate(qInstance, this);
+
          runPlugins(QAuthenticationMetaData.class, authentication, qInstance);
       }
    }
@@ -1139,6 +1185,21 @@ public class QInstanceValidator
             }
          }
       }
+
+      validateFieldSupplementalMetaData(field, qInstance);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public void validateFieldSupplementalMetaData(QFieldMetaData field, QInstance qInstance)
+   {
+      for(QSupplementalFieldMetaData supplementalFieldMetaData : CollectionUtils.nonNullMap(field.getSupplementalMetaData()).values())
+      {
+         supplementalFieldMetaData.validate(qInstance, field, this);
+      }
    }
 
 
@@ -1331,7 +1392,7 @@ public class QInstanceValidator
                numberSet++;
                if(preAssertionsForCodeReference(action.getCodeReference(), actionPrefix))
                {
-                  validateSimpleCodeReference(actionPrefix + "code reference: ", action.getCodeReference(), RecordAutomationHandler.class);
+                  validateSimpleCodeReference(actionPrefix + "code reference: ", action.getCodeReference(), RecordAutomationHandlerInterface.class);
                }
             }
 
@@ -1400,7 +1461,7 @@ public class QInstanceValidator
             //////////////////////////////////////////////////
             // make sure the customizer can be instantiated //
             //////////////////////////////////////////////////
-            Object customizerInstance = getInstanceOfCodeReference(prefix, customizerClass);
+            Object customizerInstance = getInstanceOfCodeReference(prefix, customizerClass, codeReference);
 
             TableCustomizers tableCustomizer = TableCustomizers.forRole(roleName);
             if(tableCustomizer == null)
@@ -1461,8 +1522,13 @@ public class QInstanceValidator
    /*******************************************************************************
     **
     *******************************************************************************/
-   private Object getInstanceOfCodeReference(String prefix, Class<?> clazz)
+   private Object getInstanceOfCodeReference(String prefix, Class<?> clazz, QCodeReference codeReference)
    {
+      if(codeReference instanceof QCodeReferenceLambda<?> lambdaCodeReference)
+      {
+         return (lambdaCodeReference.getLambda());
+      }
+
       Object instance = null;
       try
       {
@@ -1641,21 +1707,26 @@ public class QInstanceValidator
             Set<String> usedStepNames = new HashSet<>();
             if(assertCondition(CollectionUtils.nullSafeHasContents(process.getStepList()), "At least 1 step must be defined in process " + processName + "."))
             {
-               int index = 0;
+               int index = -1;
                for(QStepMetaData step : process.getStepList())
                {
+                  index++;
                   if(assertCondition(StringUtils.hasContent(step.getName()), "Missing name for a step at index " + index + " in process " + processName))
                   {
                      assertCondition(!usedStepNames.contains(step.getName()), "Duplicate step name [" + step.getName() + "] in process " + processName);
                      usedStepNames.add(step.getName());
                   }
-                  index++;
 
                   ////////////////////////////////////////////
                   // validate instantiation of step classes //
                   ////////////////////////////////////////////
                   if(step instanceof QBackendStepMetaData backendStepMetaData)
                   {
+                     if(assertCondition(backendStepMetaData.getCode() != null, "Missing code for a backend step at index " + index + " in process " + processName))
+                     {
+                        validateSimpleCodeReference("Process " + processName + ", backend step at index " + index + ", code reference: ", backendStepMetaData.getCode(), BackendStep.class);
+                     }
+
                      if(backendStepMetaData.getInputMetaData() != null && CollectionUtils.nullSafeHasContents(backendStepMetaData.getInputMetaData().getFieldList()))
                      {
                         for(QFieldMetaData fieldMetaData : backendStepMetaData.getInputMetaData().getFieldList())
@@ -1682,6 +1753,8 @@ public class QInstanceValidator
 
                               validateSimpleCodeReference("Process " + processName + " code reference:", codeReference, expectedClass);
                            }
+
+                           validateFieldSupplementalMetaData(fieldMetaData, qInstance);
                         }
                      }
                   }
@@ -2219,8 +2292,7 @@ public class QInstanceValidator
    /*******************************************************************************
     **
     *******************************************************************************/
-   @SafeVarargs
-   private void validateSimpleCodeReference(String prefix, QCodeReference codeReference, Class<?>... anyOfExpectedClasses)
+   public void validateSimpleCodeReference(String prefix, QCodeReference codeReference, Class<?>... anyOfExpectedClasses)
    {
       if(!preAssertionsForCodeReference(codeReference, prefix))
       {
@@ -2241,7 +2313,7 @@ public class QInstanceValidator
             //////////////////////////////////////////////////
             // make sure the customizer can be instantiated //
             //////////////////////////////////////////////////
-            Object classInstance = getInstanceOfCodeReference(prefix, clazz);
+            Object classInstance = getInstanceOfCodeReference(prefix, clazz, codeReference);
 
             ////////////////////////////////////////////////////////////////////////
             // make sure the customizer instance can be cast to the expected type //
@@ -2264,6 +2336,11 @@ public class QInstanceValidator
       Class<?> clazz = null;
       try
       {
+         if(codeReference instanceof QCodeReferenceLambda<?> lambdaCodeReference)
+         {
+            return (lambdaCodeReference.getLambda().getClass());
+         }
+
          clazz = Class.forName(codeReference.getName());
       }
       catch(ClassNotFoundException e)

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/SecretsManagerUtils.java

@@ -72,6 +72,18 @@ public class SecretsManagerUtils
     ** and write them to a .env file (backing up any pre-existing .env files first).
     *******************************************************************************/
    public static void writeEnvFromSecretsWithNamePrefix(String prefix) throws IOException
+   {
+      writeEnvFromSecretsWithNamePrefix(prefix, true);
+   }
+
+
+
+   /*******************************************************************************
+    ** IF secret manager ENV vars are set,
+    ** THEN lookup all secrets starting with the given prefix,
+    ** and write them to a .env file (backing up any pre-existing .env files first).
+    *******************************************************************************/
+   public static void writeEnvFromSecretsWithNamePrefix(String prefix, boolean quoteValues) throws IOException
    {
       Optional<AWSSecretsManager> optionalSecretsManagerClient = getSecretsManagerClient();
       if(optionalSecretsManagerClient.isPresent())
@@ -91,7 +103,9 @@ public class SecretsManagerUtils
                Optional<String> secretValue       = getSecret(prefix, nameWithoutPrefix);
                if(secretValue.isPresent())
                {
-                  String envLine = nameWithoutPrefix + "=" + secretValue.get();
+                  String envLine = quoteValues
+                     ? nameWithoutPrefix + "=\"" + secretValue.get() + "\""
+                     : nameWithoutPrefix + "=" + secretValue.get();
                   fullEnv.append(envLine).append('\n');
                }
             }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/assessment/Assessable.java

@@ -0,0 +1,37 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.assessment;
+
+
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** marker for an object which can be processed by the QInstanceAssessor.
+ *******************************************************************************/
+public interface Assessable
+{
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   void assess(QInstanceAssessor qInstanceAssessor, QInstance qInstance);
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/assessment/QInstanceAssessor.java

@@ -0,0 +1,219 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.assessment;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** POC of a class that is meant to review meta-data for accuracy vs. real backends.
+ *******************************************************************************/
+public class QInstanceAssessor
+{
+   private static final QLogger LOG = QLogger.getLogger(QInstanceAssessor.class);
+
+   private final QInstance qInstance;
+
+   private List<String> errors      = new ArrayList<>();
+   private List<String> warnings    = new ArrayList<>();
+   private List<String> suggestions = new ArrayList<>();
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public QInstanceAssessor(QInstance qInstance)
+   {
+      this.qInstance = qInstance;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void assess()
+   {
+      for(QBackendMetaData backend : qInstance.getBackends().values())
+      {
+         if(backend instanceof Assessable assessable)
+         {
+            assessable.assess(this, qInstance);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @SuppressWarnings("checkstyle:AvoidEscapedUnicodeCharacters")
+   public String getSummary()
+   {
+      StringBuilder rs = new StringBuilder();
+
+      ///////////////////////////
+      // print header & errors //
+      ///////////////////////////
+      if(CollectionUtils.nullSafeIsEmpty(errors))
+      {
+         rs.append("Assessment passed with no errors! \uD83D\uDE0E\n");
+      }
+      else
+      {
+         rs.append("Assessment found the following ").append(StringUtils.plural(errors, "error", "errors")).append(": \uD83D\uDE32\n");
+
+         for(String error : errors)
+         {
+            rs.append(" - ").append(error).append("\n");
+         }
+      }
+
+      /////////////////////////////////////
+      // print warnings if there are any //
+      /////////////////////////////////////
+      if(CollectionUtils.nullSafeHasContents(warnings))
+      {
+         rs.append("\nAssessment found the following ").append(StringUtils.plural(warnings, "warning", "warnings")).append(": \uD83E\uDD28\n");
+
+         for(String warning : warnings)
+         {
+            rs.append(" - ").append(warning).append("\n");
+         }
+      }
+
+      //////////////////////////////////////////
+      // print suggestions, if there were any //
+      //////////////////////////////////////////
+      if(CollectionUtils.nullSafeHasContents(suggestions))
+      {
+         rs.append("\nThe following ").append(StringUtils.plural(suggestions, "fix is", "fixes are")).append(" suggested: \uD83E\uDD13\n");
+
+         for(String suggestion : suggestions)
+         {
+            rs.append("\n").append(suggestion).append("\n\n");
+         }
+      }
+
+      return (rs.toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for qInstance
+    **
+    *******************************************************************************/
+   public QInstance getInstance()
+   {
+      return qInstance;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for errors
+    **
+    *******************************************************************************/
+   public List<String> getErrors()
+   {
+      return errors;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for warnings
+    **
+    *******************************************************************************/
+   public List<String> getWarnings()
+   {
+      return warnings;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void addError(String errorMessage)
+   {
+      errors.add(errorMessage);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void addWarning(String warningMessage)
+   {
+      warnings.add(warningMessage);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void addError(String errorMessage, Exception e)
+   {
+      addError(errorMessage + " : " + e.getMessage());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void addSuggestion(String message)
+   {
+      suggestions.add(message);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public int getExitCode()
+   {
+      if(CollectionUtils.nullSafeHasContents(errors))
+      {
+         return (1);
+      }
+      else
+      {
+         return (0);
+      }
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/enrichment/plugins/QInstanceEnricherPluginInterface.java

@@ -37,4 +37,13 @@ public interface QInstanceEnricherPluginInterface<T>
     *******************************************************************************/
    void enrich(T object, QInstance qInstance);
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   default String getPluginIdentifier()
+   {
+      return getClass().getName();
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/AbstractMetaDataLoader.java

@@ -0,0 +1,510 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.Serializable;
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.math.BigDecimal;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.kingsrook.qqq.backend.core.instances.QMetaDataVariableInterpreter;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+import com.kingsrook.qqq.backend.core.utils.YamlUtils;
+import org.apache.commons.io.IOUtils;
+import static com.kingsrook.qqq.backend.core.utils.ValueUtils.getValueAsInteger;
+import static com.kingsrook.qqq.backend.core.utils.ValueUtils.getValueAsString;
+
+
+/*******************************************************************************
+ ** Abstract base class in hierarchy of classes that know how to construct &
+ ** populate QMetaDataObject instances, based on input streams (e.g., from files).
+ *******************************************************************************/
+public abstract class AbstractMetaDataLoader<T extends QMetaDataObject>
+{
+   private static final QLogger LOG = QLogger.getLogger(AbstractMetaDataLoader.class);
+
+   private String fileName;
+
+   private List<LoadingProblem> problems = new ArrayList<>();
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public T fileToMetaDataObject(QInstance qInstance, InputStream inputStream, String fileName) throws QMetaDataLoaderException
+   {
+      this.fileName = fileName;
+      Map<String, Object> map = fileToMap(inputStream, fileName);
+      LoadingContext loadingContext = new LoadingContext(fileName, "/");
+      return (mapToMetaDataObject(qInstance, map, loadingContext));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public abstract T mapToMetaDataObject(QInstance qInstance, Map<String, Object> map, LoadingContext context) throws QMetaDataLoaderException;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   protected Map<String, Object> fileToMap(InputStream inputStream, String fileName) throws QMetaDataLoaderException
+   {
+      try
+      {
+         String string = IOUtils.toString(inputStream, StandardCharsets.UTF_8);
+         string = StringUtils.ltrim(string);
+         if(fileName.toLowerCase().endsWith(".json"))
+         {
+            return JsonUtils.toObject(string, new TypeReference<>() {});
+         }
+         else if(fileName.toLowerCase().endsWith(".yaml") || fileName.toLowerCase().endsWith(".yml"))
+         {
+            return YamlUtils.toMap(string);
+         }
+
+         throw (new QMetaDataLoaderException("Unsupported file format (based on file name: " + fileName + ")"));
+      }
+      catch(IOException e)
+      {
+         throw new QMetaDataLoaderException("Error building map from file: " + fileName, e);
+      }
+   }
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   protected void reflectivelyMap(QInstance qInstance, QMetaDataObject targetObject, Map<String, Object> map, LoadingContext context)
+   {
+      Class<? extends QMetaDataObject> targetClass    = targetObject.getClass();
+      Set<String>                      usedFieldNames = new HashSet<>();
+
+      for(Method method : targetClass.getMethods())
+      {
+         try
+         {
+            if(method.getName().startsWith("set") && method.getParameterTypes().length == 1)
+            {
+               String propertyName = StringUtils.lcFirst(method.getName().substring(3));
+
+               if(map.containsKey(propertyName))
+               {
+                  usedFieldNames.add(propertyName);
+                  Class<?> parameterType = method.getParameterTypes()[0];
+                  Object   rawValue      = map.get(propertyName);
+
+                  try
+                  {
+                     Object mappedValue = reflectivelyMapValue(qInstance, method, parameterType, rawValue, context.descendToProperty(propertyName));
+                     method.invoke(targetObject, mappedValue);
+                  }
+                  catch(NoValueException nve)
+                  {
+                     ///////////////////////
+                     // don't call setter //
+                     ///////////////////////
+                     LOG.debug("at " + context + ": No value was mapped for property [" + propertyName + "] on " + targetClass.getSimpleName() + "." + method.getName() + ", raw value: [" + rawValue + "]");
+                  }
+               }
+            }
+         }
+         catch(Exception e)
+         {
+            addProblem(new LoadingProblem(context, "Error reflectively mapping on " + targetClass.getName() + "." + method.getName(), e));
+         }
+      }
+
+      //////////////////////////
+      // mmm, slightly sus... //
+      //////////////////////////
+      map.remove("class");
+      map.remove("version");
+
+      Set<String> unrecognizedKeys = new HashSet<>(map.keySet());
+      unrecognizedKeys.removeAll(usedFieldNames);
+
+      if(!unrecognizedKeys.isEmpty())
+      {
+         addProblem(new LoadingProblem(context, unrecognizedKeys.size() + " Unrecognized " + StringUtils.plural(unrecognizedKeys, "property", "properties") + ": " + unrecognizedKeys));
+      }
+   }
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   public Object reflectivelyMapValue(QInstance qInstance, Method method, Class<?> parameterType, Object rawValue, LoadingContext context) throws Exception
+   {
+      if(rawValue instanceof String s && s.matches("^\\$\\{.+\\..+}"))
+      {
+         rawValue = new QMetaDataVariableInterpreter().interpret(s);
+         LOG.debug("Interpreted raw value [" + s + "] as [" + StringUtils.maskAndTruncate(ValueUtils.getValueAsString(rawValue) + "]"));
+      }
+
+      if(parameterType.equals(String.class))
+      {
+         return (getValueAsString(rawValue));
+      }
+      else if(parameterType.equals(Integer.class))
+      {
+         try
+         {
+            return (getValueAsInteger(rawValue));
+         }
+         catch(Exception e)
+         {
+            addProblem(new LoadingProblem(context, "[" + rawValue + "] is not an Integer value."));
+         }
+      }
+      else if(parameterType.equals(Boolean.class))
+      {
+         if("true".equals(rawValue) || Boolean.TRUE.equals(rawValue))
+         {
+            return (true);
+         }
+         else if("false".equals(rawValue) || Boolean.FALSE.equals(rawValue))
+         {
+            return (false);
+         }
+         else if(rawValue == null)
+         {
+            return (null);
+         }
+         else
+         {
+            addProblem(new LoadingProblem(context, "[" + rawValue + "] is not a boolean value (must be 'true' or 'false')."));
+            return (null);
+         }
+      }
+      else if(parameterType.equals(boolean.class))
+      {
+         if("true".equals(rawValue) || Boolean.TRUE.equals(rawValue))
+         {
+            return (true);
+         }
+         else if("false".equals(rawValue) || Boolean.FALSE.equals(rawValue))
+         {
+            return (false);
+         }
+         else
+         {
+            addProblem(new LoadingProblem(context, rawValue + " is not a boolean value (must be 'true' or 'false')."));
+            throw (new NoValueException());
+         }
+      }
+      else if(parameterType.equals(List.class))
+      {
+         Type     actualTypeArgument = ((ParameterizedType) method.getGenericParameterTypes()[0]).getActualTypeArguments()[0];
+         Class<?> actualTypeClass    = Class.forName(actualTypeArgument.getTypeName());
+
+         if(rawValue instanceof @SuppressWarnings("rawtypes")List valueList)
+         {
+            List<Object> mappedValueList = new ArrayList<>();
+            for(Object o : valueList)
+            {
+               try
+               {
+                  Object mappedValue = reflectivelyMapValue(qInstance, null, actualTypeClass, o, context);
+                  mappedValueList.add(mappedValue);
+               }
+               catch(NoValueException nve)
+               {
+                  // leave off list
+               }
+            }
+            return (mappedValueList);
+         }
+      }
+      else if(parameterType.equals(Set.class))
+      {
+         Type     actualTypeArgument = ((ParameterizedType) method.getGenericParameterTypes()[0]).getActualTypeArguments()[0];
+         Class<?> actualTypeClass    = Class.forName(actualTypeArgument.getTypeName());
+
+         if(rawValue instanceof @SuppressWarnings("rawtypes")List valueList)
+         {
+            Set<Object> mappedValueSet = new LinkedHashSet<>();
+            for(Object o : valueList)
+            {
+               try
+               {
+                  Object mappedValue = reflectivelyMapValue(qInstance, null, actualTypeClass, o, context);
+                  mappedValueSet.add(mappedValue);
+               }
+               catch(NoValueException nve)
+               {
+                  // leave off list
+               }
+            }
+            return (mappedValueSet);
+         }
+      }
+      else if(parameterType.equals(Map.class))
+      {
+         Type keyType = ((ParameterizedType) method.getGenericParameterTypes()[0]).getActualTypeArguments()[0];
+         if(!keyType.equals(String.class))
+         {
+            addProblem(new LoadingProblem(context, "Unsupported key type for " + method + " got [" + keyType + "], expected [String]"));
+            throw new NoValueException();
+         }
+         // todo make sure string
+
+         Type     actualTypeArgument = ((ParameterizedType) method.getGenericParameterTypes()[0]).getActualTypeArguments()[1];
+         Class<?> actualTypeClass    = Class.forName(actualTypeArgument.getTypeName());
+
+         if(rawValue instanceof @SuppressWarnings("rawtypes")Map valueMap)
+         {
+            Map<String, Object> mappedValueMap = new LinkedHashMap<>();
+            for(Object o : valueMap.entrySet())
+            {
+               try
+               {
+                  @SuppressWarnings("unchecked")
+                  Map.Entry<String, Object> entry = (Map.Entry<String, Object>) o;
+                  Object mappedValue = reflectivelyMapValue(qInstance, null, actualTypeClass, entry.getValue(), context);
+                  mappedValueMap.put(entry.getKey(), mappedValue);
+               }
+               catch(NoValueException nve)
+               {
+                  // leave out of map
+               }
+            }
+            return (mappedValueMap);
+         }
+      }
+      else if(parameterType.isEnum())
+      {
+         String value = getValueAsString(rawValue);
+         for(Object enumConstant : parameterType.getEnumConstants())
+         {
+            if(((Enum<?>) enumConstant).name().equals(value))
+            {
+               return (enumConstant);
+            }
+         }
+
+         addProblem(new LoadingProblem(context, "Unrecognized value [" + rawValue + "].  Expected one of: " + Arrays.toString(parameterType.getEnumConstants())));
+      }
+      else if(MetaDataLoaderRegistry.hasLoaderForClass(parameterType))
+      {
+         if(rawValue instanceof @SuppressWarnings("rawtypes")Map valueMap)
+         {
+            Class<? extends AbstractMetaDataLoader<?>> loaderClass = MetaDataLoaderRegistry.getLoaderForClass(parameterType);
+            AbstractMetaDataLoader<?>                  loader      = loaderClass.getConstructor().newInstance();
+            //noinspection unchecked
+            return (loader.mapToMetaDataObject(qInstance, valueMap, context));
+         }
+      }
+      else if(QMetaDataObject.class.isAssignableFrom(parameterType))
+      {
+         if(rawValue instanceof @SuppressWarnings("rawtypes")Map valueMap)
+         {
+            QMetaDataObject childObject = (QMetaDataObject) parameterType.getConstructor().newInstance();
+            //noinspection unchecked
+            reflectivelyMap(qInstance, childObject, valueMap, context);
+            return (childObject);
+         }
+      }
+      else if(parameterType.equals(Serializable.class))
+      {
+         if(rawValue instanceof String
+            || rawValue instanceof Integer
+            || rawValue instanceof BigDecimal
+            || rawValue instanceof Boolean
+         )
+         {
+            return rawValue;
+         }
+      }
+      else
+      {
+         // todo clean up this message/level
+         addProblem(new LoadingProblem(context, "No case for " + parameterType + " (arg to: " + method + ")"));
+      }
+
+      throw new NoValueException();
+   }
+
+   ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   // unclear if the below is needed.  if so, useful to not re-write, but is hurting test coverage, so zombie until used //
+   ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   ///***************************************************************************
+   // *
+   // ***************************************************************************/
+   //protected ListOfMapOrMapOfMap getListOfMapOrMapOfMap(Map<String, Object> map, String key)
+   //{
+   //   if(map.containsKey(key))
+   //   {
+   //      if(map.get(key) instanceof List)
+   //      {
+   //         return (new ListOfMapOrMapOfMap((List<Map<String, Object>>) map.get(key)));
+   //      }
+   //      else if(map.get(key) instanceof Map)
+   //      {
+   //         return (new ListOfMapOrMapOfMap((Map<String, Map<String, Object>>) map.get(key)));
+   //      }
+   //      else
+   //      {
+   //         LOG.warn("Expected list or map under key [" + key + "] while processing [" + getClass().getSimpleName() + "] from [" + fileName + "], but found: " + (map.get(key) == null ? "null" : map.get(key).getClass().getSimpleName()));
+   //      }
+   //   }
+
+   //   return (null);
+   //}
+
+   ///***************************************************************************
+   // *
+   // ***************************************************************************/
+   //protected List<Map<String, Object>> getListOfMap(Map<String, Object> map, String key)
+   //{
+   //   if(map.containsKey(key))
+   //   {
+   //      if(map.get(key) instanceof List)
+   //      {
+   //         return (List<Map<String, Object>>) map.get(key);
+   //      }
+   //      else
+   //      {
+   //         LOG.warn("Expected list under key [" + key + "] while processing [" + getClass().getSimpleName() + "] from [" + fileName + "], but found: " + (map.get(key) == null ? "null" : map.get(key).getClass().getSimpleName()));
+   //      }
+   //   }
+
+   //   return (null);
+   //}
+
+   ///***************************************************************************
+   // *
+   // ***************************************************************************/
+   //protected Map<String, Map<String, Object>> getMapOfMap(Map<String, Object> map, String key)
+   //{
+   //   if(map.containsKey(key))
+   //   {
+   //      if(map.get(key) instanceof Map)
+   //      {
+   //         return (Map<String, Map<String, Object>>) map.get(key);
+   //      }
+   //      else
+   //      {
+   //         LOG.warn("Expected map under key [" + key + "] while processing [" + getClass().getSimpleName() + "] from [" + fileName + "], but found: " + (map.get(key) == null ? "null" : map.get(key).getClass().getSimpleName()));
+   //      }
+   //   }
+
+   //   return (null);
+   //}
+
+   ///***************************************************************************
+   // **
+   // ***************************************************************************/
+   //protected record ListOfMapOrMapOfMap(List<Map<String, Object>> listOf, Map<String, Map<String, Object>> mapOf)
+   //{
+   //   /*******************************************************************************
+   //    ** Constructor
+   //    **
+   //    *******************************************************************************/
+   //   public ListOfMapOrMapOfMap(List<Map<String, Object>> listOf)
+   //   {
+   //      this(listOf, null);
+   //   }
+
+   //   /*******************************************************************************
+   //    ** Constructor
+   //    **
+   //    *******************************************************************************/
+   //   public ListOfMapOrMapOfMap(Map<String, Map<String, Object>> mapOf)
+   //   {
+   //      this(null, mapOf);
+   //   }
+   //}
+
+
+
+   /*******************************************************************************
+    ** Getter for fileName
+    **
+    *******************************************************************************/
+   public String getFileName()
+   {
+      return fileName;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class NoValueException extends Exception
+   {
+      /*******************************************************************************
+       ** Constructor
+       **
+       *******************************************************************************/
+      public NoValueException()
+      {
+         super("No value");
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public void addProblem(LoadingProblem problem)
+   {
+      problems.add(problem);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for problems
+    **
+    *******************************************************************************/
+   public List<LoadingProblem> getProblems()
+   {
+      return (problems);
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/ClassDetectingMetaDataLoader.java

@@ -0,0 +1,120 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+import java.io.InputStream;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.instances.loaders.implementations.GenericMetaDataLoader;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
+import com.kingsrook.qqq.backend.core.utils.ClassPathUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+import com.kingsrook.qqq.backend.core.utils.memoization.AnyKey;
+import com.kingsrook.qqq.backend.core.utils.memoization.Memoization;
+
+
+/*******************************************************************************
+ ** Generic implementation of AbstractMetaDataLoader, who "detects" the class
+ ** of meta data object to be created, then defers to an appropriate subclass
+ ** to do the work.
+ *******************************************************************************/
+public class ClassDetectingMetaDataLoader extends AbstractMetaDataLoader<QMetaDataObject>
+{
+   private static final Memoization<AnyKey, List<Class<?>>> memoizedMetaDataObjectClasses = new Memoization<>();
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   public AbstractMetaDataLoader<?> getLoaderForFile(InputStream inputStream, String fileName) throws QMetaDataLoaderException
+   {
+      Map<String, Object> map = fileToMap(inputStream, fileName);
+      return (getLoaderForMap(map));
+   }
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   public AbstractMetaDataLoader<?> getLoaderForMap(Map<String, Object> map) throws QMetaDataLoaderException
+   {
+      if(map.containsKey("class"))
+      {
+         String classProperty = ValueUtils.getValueAsString(map.get("class"));
+         try
+         {
+            if(MetaDataLoaderRegistry.hasLoaderForSimpleName(classProperty))
+            {
+               Class<? extends AbstractMetaDataLoader<?>> loaderClass = MetaDataLoaderRegistry.getLoaderForSimpleName(classProperty);
+               return (loaderClass.getConstructor().newInstance());
+            }
+            else
+            {
+               Optional<List<Class<?>>> metaDataClasses = memoizedMetaDataObjectClasses.getResult(AnyKey.getInstance(), k -> ClassPathUtils.getClassesContainingNameAndOfType("MetaData", QMetaDataObject.class));
+               if(metaDataClasses.isEmpty())
+               {
+                  throw (new QMetaDataLoaderException("Could not get list of metaDataObjects from class loader"));
+               }
+
+               for(Class<?> c : metaDataClasses.get())
+               {
+                  if(c.getSimpleName().equals(classProperty) && QMetaDataObject.class.isAssignableFrom(c))
+                  {
+                     @SuppressWarnings("unchecked")
+                     Class<? extends QMetaDataObject> metaDataClass = (Class<? extends QMetaDataObject>) c;
+                     return new GenericMetaDataLoader<>(metaDataClass);
+                  }
+               }
+            }
+            throw new QMetaDataLoaderException("Unexpected class [" + classProperty + "] (not a QMetaDataObject; doesn't have a registered MetaDataLoader) specified in " + getFileName());
+         }
+         catch(QMetaDataLoaderException qmdle)
+         {
+            throw (qmdle);
+         }
+         catch(Exception e)
+         {
+            throw new QMetaDataLoaderException("Error handling class [" + classProperty + "] specified in " + getFileName(), e);
+         }
+      }
+      else
+      {
+         throw new QMetaDataLoaderException("Cannot detect meta-data type, because [class] attribute was not specified in file: " + getFileName());
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QMetaDataObject mapToMetaDataObject(QInstance qInstance, Map<String, Object> map, LoadingContext context) throws QMetaDataLoaderException
+   {
+      AbstractMetaDataLoader<?> loaderForMap = getLoaderForMap(map);
+      return loaderForMap.mapToMetaDataObject(qInstance, map, context);
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/LoadingContext.java

@@ -0,0 +1,38 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+/*******************************************************************************
+ ** Record to track where loader objects are - e.g., what file they're on,
+ ** and at what property path within the file (e.g., helps report problems).
+ *******************************************************************************/
+public record LoadingContext(String fileName, String propertyPath)
+{
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public LoadingContext descendToProperty(String propertyName)
+   {
+      return new LoadingContext(fileName, propertyPath + propertyName + "/");
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/LoadingProblem.java

@@ -0,0 +1,49 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+/*******************************************************************************
+ ** record that tracks a problem that was encountered when loading files.
+ *******************************************************************************/
+public record LoadingProblem(LoadingContext context, String message, Exception exception) // todo Level if useful
+{
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public LoadingProblem(LoadingContext context, String message)
+   {
+      this(context, message, null);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public String toString()
+   {
+      return "at[" + context.fileName() + "][" + context.propertyPath() + "]: " + message;
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/MetaDataLoaderHelper.java

@@ -0,0 +1,118 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
+import com.kingsrook.qqq.backend.core.model.metadata.TopLevelMetaDataInterface;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.Pair;
+
+
+/*******************************************************************************
+ ** class that loads a directory full of meta data files into meta data objects,
+ ** and then sets all of them in a QInstance.
+ *******************************************************************************/
+public class MetaDataLoaderHelper
+{
+   private static final QLogger LOG = QLogger.getLogger(MetaDataLoaderHelper.class);
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   public static void processAllMetaDataFilesInDirectory(QInstance qInstance, String path) throws QException
+   {
+      List<Pair<File, AbstractMetaDataLoader<?>>> loaders = new ArrayList<>();
+
+      File directory = new File(path);
+      processAllMetaDataFilesInDirectory(loaders, directory);
+
+      // todo - some version of sorting the loaders by type or possibly a sort field within the files (or file names)
+
+      for(Pair<File, AbstractMetaDataLoader<?>> pair : loaders)
+      {
+         File                      file   = pair.getA();
+         AbstractMetaDataLoader<?> loader = pair.getB();
+         try(FileInputStream fileInputStream = new FileInputStream(file))
+         {
+            QMetaDataObject qMetaDataObject = loader.fileToMetaDataObject(qInstance, fileInputStream, file.getName());
+
+            if(CollectionUtils.nullSafeHasContents(loader.getProblems()))
+            {
+               loader.getProblems().forEach(System.out::println);
+            }
+
+            if(qMetaDataObject instanceof TopLevelMetaDataInterface topLevelMetaData)
+            {
+               topLevelMetaData.addSelfToInstance(qInstance);
+            }
+            else
+            {
+               LOG.warn("Received a non-topLevelMetaDataObject from file: " + file.getAbsolutePath());
+            }
+         }
+         catch(Exception e)
+         {
+            LOG.error("Error processing file: " + file.getAbsolutePath(), e);
+         }
+      }
+   }
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   private static void processAllMetaDataFilesInDirectory(List<Pair<File, AbstractMetaDataLoader<?>>> loaders, File directory) throws QException
+   {
+      for(File file : Objects.requireNonNullElse(directory.listFiles(), new File[0]))
+      {
+         if(file.isDirectory())
+         {
+            processAllMetaDataFilesInDirectory(loaders, file);
+         }
+         else
+         {
+            try(FileInputStream fileInputStream = new FileInputStream(file))
+            {
+               AbstractMetaDataLoader<?> loader = new ClassDetectingMetaDataLoader().getLoaderForFile(fileInputStream, file.getName());
+               loaders.add(Pair.of(file, loader));
+            }
+            catch(Exception e)
+            {
+               LOG.error("Error processing file: " + file.getAbsolutePath(), e);
+            }
+         }
+      }
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/MetaDataLoaderRegistry.java

@@ -0,0 +1,120 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.instances.loaders.implementations.QTableMetaDataLoader;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.utils.ClassPathUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class MetaDataLoaderRegistry
+{
+   private static final QLogger LOG = QLogger.getLogger(AbstractMetaDataLoader.class);
+
+   private static final Map<Class<?>, Class<? extends AbstractMetaDataLoader<?>>> registeredLoaders                   = new HashMap<>();
+   private static final Map<String, Class<? extends AbstractMetaDataLoader<?>>>   registeredLoadersByTargetSimpleName = new HashMap<>();
+
+   static
+   {
+      try
+      {
+         List<Class<?>> classesInPackage = ClassPathUtils.getClassesInPackage(QTableMetaDataLoader.class.getPackageName());
+         for(Class<?> possibleLoaderClass : classesInPackage)
+         {
+            try
+            {
+               Type superClass = possibleLoaderClass.getGenericSuperclass();
+               if(superClass.getTypeName().startsWith(AbstractMetaDataLoader.class.getName() + "<"))
+               {
+                  Type actualTypeArgument = ((ParameterizedType) superClass).getActualTypeArguments()[0];
+                  if(actualTypeArgument instanceof Class)
+                  {
+                     //noinspection unchecked
+                     Class<? extends AbstractMetaDataLoader<?>> loaderClass = (Class<? extends AbstractMetaDataLoader<?>>) possibleLoaderClass;
+
+                     Class<?> metaDataObjectType = Class.forName(actualTypeArgument.getTypeName());
+                     registeredLoaders.put(metaDataObjectType, loaderClass);
+                     registeredLoadersByTargetSimpleName.put(metaDataObjectType.getSimpleName(), loaderClass);
+                  }
+               }
+            }
+            catch(Exception e)
+            {
+               LOG.info("Error on class: " + possibleLoaderClass, e);
+            }
+         }
+
+         System.out.println("Registered loaders: " + registeredLoadersByTargetSimpleName);
+      }
+      catch(Exception e)
+      {
+         LOG.error("Error in static init block for MetaDataLoaderRegistry", e);
+      }
+   }
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static boolean hasLoaderForClass(Class<?> metaDataClass)
+   {
+      return registeredLoaders.containsKey(metaDataClass);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static Class<? extends AbstractMetaDataLoader<?>> getLoaderForClass(Class<?> metaDataClass)
+   {
+      return registeredLoaders.get(metaDataClass);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static boolean hasLoaderForSimpleName(String targetSimpleName)
+   {
+      return registeredLoadersByTargetSimpleName.containsKey(targetSimpleName);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static Class<? extends AbstractMetaDataLoader<?>> getLoaderForSimpleName(String targetSimpleName)
+   {
+      return registeredLoadersByTargetSimpleName.get(targetSimpleName);
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/QMetaDataLoaderException.java

@@ -0,0 +1,50 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class QMetaDataLoaderException extends Exception
+{
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public QMetaDataLoaderException(String message)
+   {
+      super(message);
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public QMetaDataLoaderException(String message, Throwable cause)
+   {
+      super(message, cause);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/implementations/GenericMetaDataLoader.java

@@ -0,0 +1,71 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders.implementations;
+
+
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.instances.loaders.AbstractMetaDataLoader;
+import com.kingsrook.qqq.backend.core.instances.loaders.LoadingContext;
+import com.kingsrook.qqq.backend.core.instances.loaders.QMetaDataLoaderException;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class GenericMetaDataLoader<T extends QMetaDataObject> extends AbstractMetaDataLoader<T>
+{
+   private final Class<T> metaDataClass;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public GenericMetaDataLoader(Class<T> metaDataClass)
+   {
+      this.metaDataClass = metaDataClass;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public T mapToMetaDataObject(QInstance qInstance, Map<String, Object> map, LoadingContext context) throws QMetaDataLoaderException
+   {
+      try
+      {
+         T object = metaDataClass.getConstructor().newInstance();
+         reflectivelyMap(qInstance, object, map, context);
+         return (object);
+      }
+      catch(Exception e)
+      {
+         throw (new QMetaDataLoaderException("Error loading metaData object of type " + metaDataClass.getSimpleName(), e));
+      }
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/implementations/QStepDataLoader.java

@@ -0,0 +1,85 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders.implementations;
+
+
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.instances.loaders.AbstractMetaDataLoader;
+import com.kingsrook.qqq.backend.core.instances.loaders.LoadingContext;
+import com.kingsrook.qqq.backend.core.instances.loaders.QMetaDataLoaderException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class QStepDataLoader extends AbstractMetaDataLoader<QStepMetaData>
+{
+   private static final QLogger LOG = QLogger.getLogger(QStepDataLoader.class);
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QStepMetaData mapToMetaDataObject(QInstance qInstance, Map<String, Object> map, LoadingContext context) throws QMetaDataLoaderException
+   {
+      String stepType = ValueUtils.getValueAsString(map.get("stepType"));
+
+      if(!StringUtils.hasContent(stepType))
+      {
+         throw (new QMetaDataLoaderException("stepType was not specified for process step"));
+      }
+
+      QStepMetaData step;
+      if("backend".equalsIgnoreCase(stepType))
+      {
+         step = new QBackendStepMetaData();
+         reflectivelyMap(qInstance, step, map, context);
+      }
+      else if("frontend".equalsIgnoreCase(stepType))
+      {
+         step = new QFrontendStepMetaData();
+         reflectivelyMap(qInstance, step, map, context);
+      }
+      // todo - we have custom factory methods for this, so, maybe needs all custom loader?
+      // else if("stateMachine".equalsIgnoreCase(stepType))
+      // {
+      //    step = new QStateMachineStep();
+      //    reflectivelyMap(qInstance, step, map, context);
+      // }
+      else
+      {
+         throw (new QMetaDataLoaderException("Unsupported step stepType: " + stepType));
+      }
+
+      return (step);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/loaders/implementations/QTableMetaDataLoader.java

@@ -0,0 +1,58 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2024.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.instances.loaders.implementations;
+
+
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.instances.loaders.AbstractMetaDataLoader;
+import com.kingsrook.qqq.backend.core.instances.loaders.LoadingContext;
+import com.kingsrook.qqq.backend.core.instances.loaders.QMetaDataLoaderException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class QTableMetaDataLoader extends AbstractMetaDataLoader<QTableMetaData>
+{
+   private static final QLogger LOG = QLogger.getLogger(QTableMetaDataLoader.class);
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QTableMetaData mapToMetaDataObject(QInstance qInstance, Map<String, Object> map, LoadingContext context) throws QMetaDataLoaderException
+   {
+      QTableMetaData table = new QTableMetaData();
+
+      reflectivelyMap(qInstance, table, map, context);
+
+      // todo - handle QTableBackendDetails, based on backend's type
+
+      return (table);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/validation/plugins/QInstanceValidatorPluginInterface.java

@@ -38,4 +38,13 @@ public interface QInstanceValidatorPluginInterface<T>
     *******************************************************************************/
    void validate(T object, QInstance qInstance, QInstanceValidator qInstanceValidator);
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   default String getPluginIdentifier()
+   {
+      return getClass().getName();
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/audits/AuditInput.java

@@ -25,6 +25,7 @@ package com.kingsrook.qqq.backend.core.model.actions.audits;
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 
 
@@ -36,6 +37,8 @@ public class AuditInput extends AbstractActionInput implements Serializable
 {
    private List<AuditSingleInput> auditSingleInputList = new ArrayList<>();
 
+   private QBackendTransaction transaction;
+
 
 
    /*******************************************************************************
@@ -92,4 +95,42 @@ public class AuditInput extends AbstractActionInput implements Serializable
       return (this);
    }
 
+
+   /*******************************************************************************
+    * Getter for transaction
+    * @see #withTransaction(QBackendTransaction)
+    *******************************************************************************/
+   public QBackendTransaction getTransaction()
+   {
+      return (this.transaction);
+   }
+
+
+
+   /*******************************************************************************
+    * Setter for transaction
+    * @see #withTransaction(QBackendTransaction)
+    *******************************************************************************/
+   public void setTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+   }
+
+
+
+   /*******************************************************************************
+    * Fluent setter for transaction
+    *
+    * @param transaction
+    * transaction upon which the audits will be inserted.
+    *
+    * @return this
+    *******************************************************************************/
+   public AuditInput withTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/audits/DMLAuditInput.java

@@ -24,6 +24,7 @@ package com.kingsrook.qqq.backend.core.model.actions.audits;
 
 import java.io.Serializable;
 import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
@@ -38,6 +39,8 @@ public class DMLAuditInput extends AbstractActionInput implements Serializable
    private List<QRecord>            oldRecordList;
    private AbstractTableActionInput tableActionInput;
 
+   private QBackendTransaction transaction;
+
    private String auditContext = null;
 
 
@@ -164,4 +167,43 @@ public class DMLAuditInput extends AbstractActionInput implements Serializable
       return (this);
    }
 
+
+   /*******************************************************************************
+    * Getter for transaction
+    * @see #withTransaction(QBackendTransaction)
+    *******************************************************************************/
+   public QBackendTransaction getTransaction()
+   {
+      return (this.transaction);
+   }
+
+
+
+   /*******************************************************************************
+    * Setter for transaction
+    * @see #withTransaction(QBackendTransaction)
+    *******************************************************************************/
+   public void setTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+   }
+
+
+
+   /*******************************************************************************
+    * Fluent setter for transaction
+    *
+    * @param transaction
+    * transaction that will be used for inserting the audits, where (presumably)
+    * the DML against the record occurred as well
+    *
+    * @return this
+    *******************************************************************************/
+   public DMLAuditInput withTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/metadata/MetaDataOutput.java

@@ -25,6 +25,7 @@ package com.kingsrook.qqq.backend.core.model.actions.metadata;
 import java.util.List;
 import java.util.Map;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.QSupplementalInstanceMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.branding.QBrandingMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.frontend.AppTreeNode;
 import com.kingsrook.qqq.backend.core.model.metadata.frontend.QFrontendAppMetaData;
@@ -41,12 +42,13 @@ import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
  *******************************************************************************/
 public class MetaDataOutput extends AbstractActionOutput
 {
-   private Map<String, QFrontendTableMetaData>   tables;
-   private Map<String, QFrontendProcessMetaData> processes;
-   private Map<String, QFrontendReportMetaData>  reports;
-   private Map<String, QFrontendAppMetaData>     apps;
-   private Map<String, QFrontendWidgetMetaData>  widgets;
-   private Map<String, String>                   environmentValues;
+   private Map<String, QFrontendTableMetaData>        tables;
+   private Map<String, QFrontendProcessMetaData>      processes;
+   private Map<String, QFrontendReportMetaData>       reports;
+   private Map<String, QFrontendAppMetaData>          apps;
+   private Map<String, QFrontendWidgetMetaData>       widgets;
+   private Map<String, String>                        environmentValues;
+   private Map<String, QSupplementalInstanceMetaData> supplementalInstanceMetaData;
 
    private List<AppTreeNode>               appTree;
    private QBrandingMetaData               branding;
@@ -230,6 +232,28 @@ public class MetaDataOutput extends AbstractActionOutput
 
 
 
+   /*******************************************************************************
+    ** Getter for supplementalInstanceMetaData
+    **
+    *******************************************************************************/
+   public Map<String, QSupplementalInstanceMetaData> getSupplementalInstanceMetaData()
+   {
+      return supplementalInstanceMetaData;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for supplementalInstanceMetaData
+    **
+    *******************************************************************************/
+   public void setSupplementalInstanceMetaData(Map<String, QSupplementalInstanceMetaData> supplementalInstanceMetaData)
+   {
+      this.supplementalInstanceMetaData = supplementalInstanceMetaData;
+   }
+
+
+
    /*******************************************************************************
     ** Setter for helpContents
     **

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/processes/ProcessSummaryLineInterface.java

@@ -23,7 +23,11 @@ package com.kingsrook.qqq.backend.core.model.actions.processes;
 
 
 import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
 import com.kingsrook.qqq.backend.core.logging.LogPair;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -31,6 +35,45 @@ import com.kingsrook.qqq.backend.core.logging.LogPair;
  *******************************************************************************/
 public interface ProcessSummaryLineInterface extends Serializable
 {
+   QLogger LOG = QLogger.getLogger(ProcessSummaryLineInterface.class);
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static void log(String message, Serializable summaryLines, List<LogPair> additionalLogPairs)
+   {
+      try
+      {
+         if(summaryLines instanceof List)
+         {
+            List<ProcessSummaryLineInterface> list = (List<ProcessSummaryLineInterface>) summaryLines;
+
+            List<LogPair> logPairs = new ArrayList<>();
+            for(ProcessSummaryLineInterface processSummaryLineInterface : list)
+            {
+               LogPair logPair = processSummaryLineInterface.toLogPair();
+               logPair.setKey(logPair.getKey() + logPairs.size());
+               logPairs.add(logPair);
+            }
+
+            if(additionalLogPairs != null)
+            {
+               logPairs.addAll(0, additionalLogPairs);
+            }
+            logPairs.add(0, logPair("message", message));
+
+            LOG.info(logPairs);
+         }
+         else
+         {
+            LOG.info("Unrecognized type for summaryLines (expected List)", logPair("processSummary", summaryLines));
+         }
+      }
+      catch(Exception e)
+      {
+         LOG.info("Error logging a process summary", e, logPair("processSummary", summaryLines));
+      }
+   }
 
    /*******************************************************************************
     ** Getter for status

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/processes/QProcessPayload.java

@@ -0,0 +1,162 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.model.actions.processes;
+
+
+import java.io.Serializable;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QRuntimeException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.data.QRecordEntityField;
+import com.kingsrook.qqq.backend.core.utils.ListingHash;
+import com.kingsrook.qqq.backend.core.utils.ReflectiveBeanLikeClassUtils;
+
+
+/*******************************************************************************
+ ** base-class for bean-like classes to represent the fields of a process.
+ ** similar in spirit to QRecordEntity, but for processes.
+ *******************************************************************************/
+public class QProcessPayload
+{
+   private static final QLogger LOG = QLogger.getLogger(QProcessPayload.class);
+
+   private static final ListingHash<Class<? extends QProcessPayload>, QRecordEntityField> fieldMapping = new ListingHash<>();
+
+
+
+   /*******************************************************************************
+    ** Build an entity of this QRecord type from a QRecord
+    **
+    *******************************************************************************/
+   public static <T extends QProcessPayload> T fromProcessState(Class<T> c, ProcessState processState) throws QException
+   {
+      try
+      {
+         T entity = c.getConstructor().newInstance();
+         entity.populateFromProcessState(processState);
+         return (entity);
+      }
+      catch(Exception e)
+      {
+         throw (new QException("Error building process payload from state.", e));
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   protected void populateFromProcessState(ProcessState processState)
+   {
+      try
+      {
+         List<QRecordEntityField> fieldList = getFieldList(this.getClass());
+
+         for(QRecordEntityField qRecordEntityField : fieldList)
+         {
+            Serializable value      = processState.getValues().get(qRecordEntityField.getFieldName());
+            Object       typedValue = qRecordEntityField.convertValueType(value);
+            qRecordEntityField.getSetter().invoke(this, typedValue);
+         }
+      }
+      catch(Exception e)
+      {
+         throw (new QRuntimeException("Error building process payload from process state.", e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Copy the values from this payload into the given process state.
+    ** ALL fields in the entity will be set in the process state.
+    **
+    *******************************************************************************/
+   public void toProcessState(ProcessState processState) throws QRuntimeException
+   {
+      try
+      {
+         for(QRecordEntityField qRecordEntityField : getFieldList(this.getClass()))
+         {
+            processState.getValues().put(qRecordEntityField.getFieldName(), (Serializable) qRecordEntityField.getGetter().invoke(this));
+         }
+      }
+      catch(Exception e)
+      {
+         throw (new QRuntimeException("Error populating process state from process payload.", e));
+      }
+   }
+
+
+
+   /***************************************************************************
+    *
+    ***************************************************************************/
+   public static Set<Class<?>> allowedFieldTypes()
+   {
+      HashSet<Class<?>> classes = new HashSet<>(ReflectiveBeanLikeClassUtils.defaultAllowedTypes());
+      classes.add(Map.class);
+      classes.add(List.class);
+      return (classes);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static List<QRecordEntityField> getFieldList(Class<? extends QProcessPayload> c)
+   {
+      if(!fieldMapping.containsKey(c))
+      {
+         List<QRecordEntityField> fieldList = new ArrayList<>();
+         for(Method possibleGetter : c.getMethods())
+         {
+            if(ReflectiveBeanLikeClassUtils.isGetter(possibleGetter, false, allowedFieldTypes()))
+            {
+               Optional<Method> setter = ReflectiveBeanLikeClassUtils.getSetterForGetter(c, possibleGetter);
+
+               if(setter.isPresent())
+               {
+                  String fieldName = ReflectiveBeanLikeClassUtils.getFieldNameFromGetter(possibleGetter);
+                  fieldList.add(new QRecordEntityField(fieldName, possibleGetter, setter.get(), possibleGetter.getReturnType(), null));
+               }
+               else
+               {
+                  LOG.debug("Getter method [" + possibleGetter.getName() + "] does not have a corresponding setter.");
+               }
+            }
+         }
+         fieldMapping.put(c, fieldList);
+      }
+      return (fieldMapping.get(c));
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/processes/RunBackendStepInput.java

@@ -628,4 +628,15 @@ public class RunBackendStepInput extends AbstractActionInput
    {
       return (QContext.getQInstance().getProcess(getProcessName()));
    }
+
+
+
+   /***************************************************************************
+    ** return a QProcessPayload subclass instance, with values populated from
+    ** the current process state.
+    ***************************************************************************/
+   public <T extends QProcessPayload> T getProcessPayload(Class<T> payloadClass) throws QException
+   {
+      return QProcessPayload.fromProcessState(payloadClass, getProcessState());
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/processes/RunBackendStepOutput.java

@@ -445,4 +445,14 @@ public class RunBackendStepOutput extends AbstractActionOutput implements Serial
       this.processState.setProcessMetaDataAdjustment(processMetaDataAdjustment);
    }
 
+
+
+   /***************************************************************************
+    ** Update the process state with values from the input processPayload
+    ** subclass instance.
+    ***************************************************************************/
+   public void setProcessPayload(QProcessPayload processPayload)
+   {
+      processPayload.toProcessState(getProcessState());
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/reporting/ReportInput.java

@@ -28,6 +28,7 @@ import java.util.Map;
 import java.util.function.Supplier;
 import com.kingsrook.qqq.backend.core.actions.reporting.ExportStreamerInterface;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportMetaData;
 
 
@@ -44,6 +45,7 @@ public class ReportInput extends AbstractTableActionInput
    private ReportDestination reportDestination;
 
    private Supplier<? extends ExportStreamerInterface> overrideExportStreamerSupplier;
+   private QCodeReference                              exportStyleCustomizer;
 
 
 
@@ -208,4 +210,35 @@ public class ReportInput extends AbstractTableActionInput
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for exportStyleCustomizer
+    *******************************************************************************/
+   public QCodeReference getExportStyleCustomizer()
+   {
+      return (this.exportStyleCustomizer);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for exportStyleCustomizer
+    *******************************************************************************/
+   public void setExportStyleCustomizer(QCodeReference exportStyleCustomizer)
+   {
+      this.exportStyleCustomizer = exportStyleCustomizer;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for exportStyleCustomizer
+    *******************************************************************************/
+   public ReportInput withExportStyleCustomizer(QCodeReference exportStyleCustomizer)
+   {
+      this.exportStyleCustomizer = exportStyleCustomizer;
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/ActionFlag.java

@@ -0,0 +1,35 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.model.actions.tables;
+
+
+import java.io.Serializable;
+
+
+/*******************************************************************************
+ ** interface to mark enums (presumably classes too, but the original intent is
+ ** enums) that can be added to insert/update/delete action inputs to flag behaviors
+ *******************************************************************************/
+public interface ActionFlag extends Serializable
+{
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/QueryOrCountInputInterface.java

@@ -0,0 +1,117 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.model.actions.tables;
+
+
+import java.util.EnumSet;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
+
+
+/*******************************************************************************
+ ** Common getters & setters, shared by both QueryInput and CountInput.
+ **
+ ** Original impetus for this class is the setCommonParamsFrom() method - for cases
+ ** where we need to change a Query to a Get, or vice-versa, and we want to copy over
+ ** all of those input params.
+ *******************************************************************************/
+public interface QueryOrCountInputInterface
+{
+   /*******************************************************************************
+    ** Set in THIS, the "common params" (e.g., common to both Query & Count inputs)
+    ** from the parameter SOURCE object.
+    *******************************************************************************/
+   default void setCommonParamsFrom(QueryOrCountInputInterface source)
+   {
+      this.setTransaction(source.getTransaction());
+      this.setFilter(source.getFilter());
+      this.setTableName(source.getTableName());
+      this.setQueryJoins(source.getQueryJoins());
+      this.setTimeoutSeconds(source.getTimeoutSeconds());
+      this.setQueryHints(source.getQueryHints());
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   String getTableName();
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   void setTableName(String tableName);
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   QQueryFilter getFilter();
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   void setFilter(QQueryFilter filter);
+
+   /*******************************************************************************
+    ** Getter for transaction
+    *******************************************************************************/
+   QBackendTransaction getTransaction();
+
+   /*******************************************************************************
+    ** Setter for transaction
+    *******************************************************************************/
+   void setTransaction(QBackendTransaction transaction);
+
+   /*******************************************************************************
+    ** Getter for queryJoins
+    *******************************************************************************/
+   List<QueryJoin> getQueryJoins();
+
+   /*******************************************************************************
+    ** Setter for queryJoins
+    **
+    *******************************************************************************/
+   void setQueryJoins(List<QueryJoin> queryJoins);
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   Integer getTimeoutSeconds();
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   void setTimeoutSeconds(Integer timeoutSeconds);
+
+
+   /*******************************************************************************
+    ** Getter for queryHints
+    *******************************************************************************/
+   EnumSet<QueryHint> getQueryHints();
+
+
+   /*******************************************************************************
+    ** Setter for queryHints
+    *******************************************************************************/
+   void setQueryHints(EnumSet<QueryHint> queryHints);
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/aggregate/AggregateInput.java

@@ -25,6 +25,7 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.aggregate;
 import java.util.ArrayList;
 import java.util.EnumSet;
 import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QueryHint;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
@@ -37,6 +38,8 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
  *******************************************************************************/
 public class AggregateInput extends AbstractTableActionInput
 {
+   private QBackendTransaction transaction;
+
    private QQueryFilter    filter;
    private List<Aggregate> aggregates;
    private List<GroupBy>   groupBys = new ArrayList<>();
@@ -404,4 +407,35 @@ public class AggregateInput extends AbstractTableActionInput
 
       return (queryHints.contains(queryHint));
    }
+
+   /*******************************************************************************
+    ** Getter for transaction
+    *******************************************************************************/
+   public QBackendTransaction getTransaction()
+   {
+      return (this.transaction);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for transaction
+    *******************************************************************************/
+   public void setTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for transaction
+    *******************************************************************************/
+   public AggregateInput withTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/count/CountInput.java

@@ -25,8 +25,10 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.count;
 import java.util.ArrayList;
 import java.util.EnumSet;
 import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QueryHint;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrCountInputInterface;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
 
@@ -35,9 +37,10 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
  ** Input data for the Count action
  **
  *******************************************************************************/
-public class CountInput extends AbstractTableActionInput
+public class CountInput extends AbstractTableActionInput implements QueryOrCountInputInterface
 {
-   private QQueryFilter filter;
+   private QBackendTransaction transaction;
+   private QQueryFilter        filter;
 
    private Integer timeoutSeconds;
 
@@ -285,4 +288,35 @@ public class CountInput extends AbstractTableActionInput
 
       return (queryHints.contains(queryHint));
    }
+
+   /*******************************************************************************
+    ** Getter for transaction
+    *******************************************************************************/
+   public QBackendTransaction getTransaction()
+   {
+      return (this.transaction);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for transaction
+    *******************************************************************************/
+   public void setTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for transaction
+    *******************************************************************************/
+   public CountInput withTransaction(QBackendTransaction transaction)
+   {
+      this.transaction = transaction;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/delete/DeleteInput.java

@@ -24,9 +24,12 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.delete;
 
 import java.io.Serializable;
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.ActionFlag;
 import com.kingsrook.qqq.backend.core.model.actions.tables.InputSource;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
@@ -47,6 +50,8 @@ public class DeleteInput extends AbstractTableActionInput
    private boolean omitDmlAudit = false;
    private String  auditContext = null;
 
+   private Set<ActionFlag> flags;
+
 
 
    /*******************************************************************************
@@ -295,4 +300,65 @@ public class DeleteInput extends AbstractTableActionInput
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for flags
+    *******************************************************************************/
+   public Set<ActionFlag> getFlags()
+   {
+      return (this.flags);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for flags
+    *******************************************************************************/
+   public void setFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for flags
+    *******************************************************************************/
+   public DeleteInput withFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public DeleteInput withFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         this.flags = new HashSet<>();
+      }
+      this.flags.add(flag);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public boolean hasFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         return (false);
+      }
+
+      return (this.flags.contains(flag));
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/insert/InsertInput.java

@@ -23,9 +23,12 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.insert;
 
 
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.ActionFlag;
 import com.kingsrook.qqq.backend.core.model.actions.tables.InputSource;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
@@ -48,6 +51,8 @@ public class InsertInput extends AbstractTableActionInput
    private boolean omitDmlAudit = false;
    private String  auditContext = null;
 
+   private Set<ActionFlag> flags;
+
 
 
    /*******************************************************************************
@@ -316,4 +321,65 @@ public class InsertInput extends AbstractTableActionInput
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for flags
+    *******************************************************************************/
+   public Set<ActionFlag> getFlags()
+   {
+      return (this.flags);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for flags
+    *******************************************************************************/
+   public void setFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for flags
+    *******************************************************************************/
+   public InsertInput withFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public InsertInput withFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         this.flags = new HashSet<>();
+      }
+      this.flags.add(flag);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public boolean hasFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         return (false);
+      }
+
+      return (this.flags.contains(flag));
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/QFilterCriteria.java

@@ -33,6 +33,7 @@ import java.util.Set;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.serialization.QFilterCriteriaDeserializer;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 
@@ -42,7 +43,7 @@ import com.kingsrook.qqq.backend.core.utils.StringUtils;
  *
  *******************************************************************************/
 @JsonDeserialize(using = QFilterCriteriaDeserializer.class)
-public class QFilterCriteria implements Serializable, Cloneable
+public class QFilterCriteria implements Serializable, Cloneable, QMetaDataObject
 {
    private static final QLogger LOG = QLogger.getLogger(QFilterCriteria.class);
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/QFilterOrderBy.java

@@ -23,13 +23,14 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.query;
 
 
 import java.io.Serializable;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
 
 
 /*******************************************************************************
  ** Bean representing an element of a query order-by clause.
  **
  *******************************************************************************/
-public class QFilterOrderBy implements Serializable, Cloneable
+public class QFilterOrderBy implements Serializable, Cloneable, QMetaDataObject
 {
    private String  fieldName;
    private boolean isAscending = true;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/QQueryFilter.java

@@ -36,6 +36,7 @@ import com.kingsrook.qqq.backend.core.instances.QMetaDataVariableInterpreter;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.AbstractFilterExpression;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.FilterVariableExpression;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
@@ -45,7 +46,7 @@ import com.kingsrook.qqq.backend.core.utils.ValueUtils;
  * Full "filter" for a query - a list of criteria and order-bys
  *
  *******************************************************************************/
-public class QQueryFilter implements Serializable, Cloneable
+public class QQueryFilter implements Serializable, Cloneable, QMetaDataObject
 {
    private static final QLogger LOG = QLogger.getLogger(QQueryFilter.class);
 
@@ -658,6 +659,21 @@ public class QQueryFilter implements Serializable, Cloneable
          }
       }
 
+      //////////////////////////////////////
+      // recursively process sub filters! //
+      //////////////////////////////////////
+      for(QQueryFilter subFilter : CollectionUtils.nonNullList(getSubFilters()))
+      {
+         try
+         {
+            subFilter.interpretValues(inputValues, useCase);
+         }
+         catch(Exception e)
+         {
+            caughtExceptions.add(e);
+         }
+      }
+
       if(!caughtExceptions.isEmpty())
       {
          String  message       = "Error interpreting filter values: " + StringUtils.joinWithCommasAndAnd(caughtExceptions.stream().map(e -> e.getMessage()).toList());
@@ -823,6 +839,7 @@ public class QQueryFilter implements Serializable, Cloneable
    }
 
 
+
    /*******************************************************************************
     ** Getter for subFilterSetOperator
     *******************************************************************************/
@@ -853,6 +870,7 @@ public class QQueryFilter implements Serializable, Cloneable
    }
 
 
+
    /***************************************************************************
     **
     ***************************************************************************/

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/QueryInput.java

@@ -32,6 +32,7 @@ import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.actions.reporting.RecordPipe;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QueryHint;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrCountInputInterface;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
 
 
@@ -42,7 +43,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterf
  ** CountInput, and AggregateInput}, with common attributes for all of these
  ** "read" operations (like, queryHints,
  *******************************************************************************/
-public class QueryInput extends AbstractTableActionInput implements QueryOrGetInputInterface, Cloneable
+public class QueryInput extends AbstractTableActionInput implements QueryOrGetInputInterface, QueryOrCountInputInterface, Cloneable
 {
    private QBackendTransaction transaction;
    private QQueryFilter        filter;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/replace/ReplaceInput.java

@@ -22,9 +22,12 @@
 package com.kingsrook.qqq.backend.core.model.actions.tables.replace;
 
 
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.ActionFlag;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
@@ -39,12 +42,14 @@ public class ReplaceInput extends AbstractTableActionInput
    private UniqueKey           key;
    private List<QRecord>       records;
    private QQueryFilter        filter;
-   private boolean performDeletes                 = true;
-   private boolean allowNullKeyValuesToEqual      = false;
-   private boolean setPrimaryKeyInInsertedRecords = false;
+   private boolean             performDeletes                 = true;
+   private boolean             allowNullKeyValuesToEqual      = false;
+   private boolean             setPrimaryKeyInInsertedRecords = false;
 
    private boolean omitDmlAudit = false;
 
+   private Set<ActionFlag> flags;
+
 
 
    /*******************************************************************************
@@ -303,4 +308,65 @@ public class ReplaceInput extends AbstractTableActionInput
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for flags
+    *******************************************************************************/
+   public Set<ActionFlag> getFlags()
+   {
+      return (this.flags);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for flags
+    *******************************************************************************/
+   public void setFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for flags
+    *******************************************************************************/
+   public ReplaceInput withFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public ReplaceInput withFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         this.flags = new HashSet<>();
+      }
+      this.flags.add(flag);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public boolean hasFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         return (false);
+      }
+
+      return (this.flags.contains(flag));
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/update/UpdateInput.java

@@ -23,9 +23,12 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.update;
 
 
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.ActionFlag;
 import com.kingsrook.qqq.backend.core.model.actions.tables.InputSource;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QInputSource;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
@@ -56,6 +59,8 @@ public class UpdateInput extends AbstractTableActionInput
    private boolean omitModifyDateUpdate      = false;
    private String  auditContext              = null;
 
+   private Set<ActionFlag> flags;
+
 
 
    /*******************************************************************************
@@ -385,4 +390,65 @@ public class UpdateInput extends AbstractTableActionInput
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for flags
+    *******************************************************************************/
+   public Set<ActionFlag> getFlags()
+   {
+      return (this.flags);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for flags
+    *******************************************************************************/
+   public void setFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for flags
+    *******************************************************************************/
+   public UpdateInput withFlags(Set<ActionFlag> flags)
+   {
+      this.flags = flags;
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public UpdateInput withFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         this.flags = new HashSet<>();
+      }
+      this.flags.add(flag);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public boolean hasFlag(ActionFlag flag)
+   {
+      if(this.flags == null)
+      {
+         return (false);
+      }
+
+      return (this.flags.contains(flag));
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/values/SearchPossibleValueSourceInput.java

@@ -25,6 +25,7 @@ package com.kingsrook.qqq.backend.core.model.actions.values;
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 
@@ -40,6 +41,8 @@ public class SearchPossibleValueSourceInput extends AbstractActionInput implemen
    private List<Serializable> idList;
    private List<String>       labelList;
 
+   private Map<String, Serializable> otherValues;
+
    private Integer skip  = 0;
    private Integer limit = 250;
 
@@ -284,6 +287,7 @@ public class SearchPossibleValueSourceInput extends AbstractActionInput implemen
    }
 
 
+
    /*******************************************************************************
     ** Getter for labelList
     *******************************************************************************/
@@ -313,4 +317,35 @@ public class SearchPossibleValueSourceInput extends AbstractActionInput implemen
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for otherValues
+    *******************************************************************************/
+   public Map<String, Serializable> getOtherValues()
+   {
+      return (this.otherValues);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for otherValues
+    *******************************************************************************/
+   public void setOtherValues(Map<String, Serializable> otherValues)
+   {
+      this.otherValues = otherValues;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for otherValues
+    *******************************************************************************/
+   public SearchPossibleValueSourceInput withOtherValues(Map<String, Serializable> otherValues)
+   {
+      this.otherValues = otherValues;
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/automation/TableTrigger.java

@@ -27,7 +27,7 @@ import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.data.QField;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.TablesPossibleValueSourceMetaDataProvider;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TablesSupportingAutomationsPossibleValueSourceMetaDataProvider;
 import com.kingsrook.qqq.backend.core.model.savedviews.SavedView;
 import com.kingsrook.qqq.backend.core.model.scripts.Script;
 
@@ -48,16 +48,16 @@ public class TableTrigger extends QRecordEntity
    @QField(isEditable = false)
    private Instant modifyDate;
 
-   @QField(possibleValueSourceName = TablesPossibleValueSourceMetaDataProvider.NAME)
+   @QField(possibleValueSourceName = TablesSupportingAutomationsPossibleValueSourceMetaDataProvider.NAME, isRequired = true)
    private String tableName;
 
    @QField(possibleValueSourceName = SavedView.TABLE_NAME)
    private Integer filterId;
 
-   @QField(possibleValueSourceName = Script.TABLE_NAME)
+   @QField(possibleValueSourceName = Script.TABLE_NAME, isRequired = true)
    private Integer scriptId;
 
-   @QField()
+   @QField(defaultValue = "500")
    private Integer priority;
 
    @QField()

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/common/TimeZonePossibleValueSourceMetaDataProvider.java

@@ -23,6 +23,7 @@ package com.kingsrook.qqq.backend.core.model.common;
 
 
 import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.List;
 import java.util.TimeZone;
 import java.util.function.Function;
@@ -47,7 +48,7 @@ public class TimeZonePossibleValueSourceMetaDataProvider
     *******************************************************************************/
    public QPossibleValueSource produce()
    {
-      return (produce(null, null));
+      return (produce(null, null, null));
    }
 
 
@@ -56,6 +57,16 @@ public class TimeZonePossibleValueSourceMetaDataProvider
     **
     *******************************************************************************/
    public QPossibleValueSource produce(Predicate<String> filter, Function<String, String> labelMapper)
+   {
+      return (produce(filter, labelMapper, null));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QPossibleValueSource produce(Predicate<String> filter, Function<String, String> labelMapper, Comparator<QPossibleValue<?>> comparator)
    {
       QPossibleValueSource possibleValueSource = new QPossibleValueSource()
          .withName("timeZones")
@@ -72,6 +83,11 @@ public class TimeZonePossibleValueSourceMetaDataProvider
          }
       }
 
+      if(comparator != null)
+      {
+         enumValues.sort(comparator);
+      }
+
       possibleValueSource.withEnumValues(enumValues);
       return (possibleValueSource);
    }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/ChildRecordListData.java

@@ -23,6 +23,7 @@ package com.kingsrook.qqq.backend.core.model.dashboard.widgets;
 
 
 import java.io.Serializable;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
@@ -52,6 +53,7 @@ public class ChildRecordListData extends QWidgetData
    private Map<String, Serializable> defaultValuesForNewChildRecords;
    private Set<String>               disabledFieldsForNewChildRecords;
    private Map<String, String>       defaultValuesForNewChildRecordsFromParentFields;
+   private List<String>              omitFieldNames;
 
 
 
@@ -555,6 +557,37 @@ public class ChildRecordListData extends QWidgetData
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for omitFieldNames
+    *******************************************************************************/
+   public List<String> getOmitFieldNames()
+   {
+      return (this.omitFieldNames);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for omitFieldNames
+    *******************************************************************************/
+   public void setOmitFieldNames(List<String> omitFieldNames)
+   {
+      this.omitFieldNames = omitFieldNames;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for omitFieldNames
+    *******************************************************************************/
+   public ChildRecordListData withOmitFieldNames(List<String> omitFieldNames)
+   {
+      this.omitFieldNames = omitFieldNames;
+      return (this);
+   }
+
 }
 
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/FilterAndColumnsSetupData.java

@@ -35,7 +35,15 @@ public class FilterAndColumnsSetupData extends QWidgetData
    private Boolean      allowVariables = false;
    private Boolean      hideColumns    = false;
    private Boolean      hidePreview    = false;
+   private Boolean      hideSortBy     = false;
+   private Boolean      overrideIsEditable;
    private List<String> filterDefaultFieldNames;
+   private List<String> omitExposedJoins;
+
+   private Boolean isApiVersioned = false;
+   private String  apiName;
+   private String  apiPath;
+   private String  apiVersion;
 
    private String filterFieldName = "queryFilterJson";
    private String columnFieldName = "columnsJson";
@@ -290,4 +298,227 @@ public class FilterAndColumnsSetupData extends QWidgetData
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for overrideIsEditable
+    *******************************************************************************/
+   public Boolean getOverrideIsEditable()
+   {
+      return (this.overrideIsEditable);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for overrideIsEditable
+    *******************************************************************************/
+   public void setOverrideIsEditable(Boolean overrideIsEditable)
+   {
+      this.overrideIsEditable = overrideIsEditable;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for overrideIsEditable
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withOverrideIsEditable(Boolean overrideIsEditable)
+   {
+      this.overrideIsEditable = overrideIsEditable;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for hideSortBy
+    *******************************************************************************/
+   public Boolean getHideSortBy()
+   {
+      return (this.hideSortBy);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for hideSortBy
+    *******************************************************************************/
+   public void setHideSortBy(Boolean hideSortBy)
+   {
+      this.hideSortBy = hideSortBy;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for hideSortBy
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withHideSortBy(Boolean hideSortBy)
+   {
+      this.hideSortBy = hideSortBy;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for isApiVersioned
+    *******************************************************************************/
+   public Boolean getIsApiVersioned()
+   {
+      return (this.isApiVersioned);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for isApiVersioned
+    *******************************************************************************/
+   public void setIsApiVersioned(Boolean isApiVersioned)
+   {
+      this.isApiVersioned = isApiVersioned;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for isApiVersioned
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withIsApiVersioned(Boolean isApiVersioned)
+   {
+      this.isApiVersioned = isApiVersioned;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for apiName
+    *******************************************************************************/
+   public String getApiName()
+   {
+      return (this.apiName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for apiName
+    *******************************************************************************/
+   public void setApiName(String apiName)
+   {
+      this.apiName = apiName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for apiName
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withApiName(String apiName)
+   {
+      this.apiName = apiName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for apiPath
+    *******************************************************************************/
+   public String getApiPath()
+   {
+      return (this.apiPath);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for apiPath
+    *******************************************************************************/
+   public void setApiPath(String apiPath)
+   {
+      this.apiPath = apiPath;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for apiPath
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withApiPath(String apiPath)
+   {
+      this.apiPath = apiPath;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for apiVersion
+    *******************************************************************************/
+   public String getApiVersion()
+   {
+      return (this.apiVersion);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for apiVersion
+    *******************************************************************************/
+   public void setApiVersion(String apiVersion)
+   {
+      this.apiVersion = apiVersion;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for apiVersion
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withApiVersion(String apiVersion)
+   {
+      this.apiVersion = apiVersion;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    * Getter for omitExposedJoins
+    * @see #withOmitExposedJoins(List)
+    *******************************************************************************/
+   public List<String> getOmitExposedJoins()
+   {
+      return (this.omitExposedJoins);
+   }
+
+
+
+   /*******************************************************************************
+    * Setter for omitExposedJoins
+    * @see #withOmitExposedJoins(List)
+    *******************************************************************************/
+   public void setOmitExposedJoins(List<String> omitExposedJoins)
+   {
+      this.omitExposedJoins = omitExposedJoins;
+   }
+
+
+
+   /*******************************************************************************
+    * Fluent setter for omitExposedJoins
+    *
+    * @param omitExposedJoins
+    * list of tableNames of exposed joins that shouldn't be available in the filter.
+    * @return this
+    *******************************************************************************/
+   public FilterAndColumnsSetupData withOmitExposedJoins(List<String> omitExposedJoins)
+   {
+      this.omitExposedJoins = omitExposedJoins;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/WidgetType.java

@@ -66,6 +66,7 @@ public enum WidgetType
    // record view/edit widgets //
    //////////////////////////////
    CHILD_RECORD_LIST("childRecordList"),
+   CUSTOM_COMPONENT("customComponent"),
    DYNAMIC_FORM("dynamicForm"),
    DATA_BAG_VIEWER("dataBagViewer"),
    PIVOT_TABLE_SETUP("pivotTableSetup"),

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/data/QRecord.java

@@ -468,7 +468,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public String getValueString(String fieldName)
    {
-      return (ValueUtils.getValueAsString(values.get(fieldName)));
+      return (ValueUtils.getValueAsString(getValue(fieldName)));
    }
 
 
@@ -479,7 +479,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public Integer getValueInteger(String fieldName)
    {
-      return (ValueUtils.getValueAsInteger(values.get(fieldName)));
+      return (ValueUtils.getValueAsInteger(getValue(fieldName)));
    }
 
 
@@ -490,7 +490,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public Long getValueLong(String fieldName)
    {
-      return (ValueUtils.getValueAsLong(values.get(fieldName)));
+      return (ValueUtils.getValueAsLong(getValue(fieldName)));
    }
 
 
@@ -500,7 +500,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public BigDecimal getValueBigDecimal(String fieldName)
    {
-      return (ValueUtils.getValueAsBigDecimal(values.get(fieldName)));
+      return (ValueUtils.getValueAsBigDecimal(getValue(fieldName)));
    }
 
 
@@ -510,7 +510,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public Boolean getValueBoolean(String fieldName)
    {
-      return (ValueUtils.getValueAsBoolean(values.get(fieldName)));
+      return (ValueUtils.getValueAsBoolean(getValue(fieldName)));
    }
 
 
@@ -520,7 +520,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public LocalTime getValueLocalTime(String fieldName)
    {
-      return (ValueUtils.getValueAsLocalTime(values.get(fieldName)));
+      return (ValueUtils.getValueAsLocalTime(getValue(fieldName)));
    }
 
 
@@ -530,7 +530,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public LocalDate getValueLocalDate(String fieldName)
    {
-      return (ValueUtils.getValueAsLocalDate(values.get(fieldName)));
+      return (ValueUtils.getValueAsLocalDate(getValue(fieldName)));
    }
 
 
@@ -540,7 +540,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public byte[] getValueByteArray(String fieldName)
    {
-      return (ValueUtils.getValueAsByteArray(values.get(fieldName)));
+      return (ValueUtils.getValueAsByteArray(getValue(fieldName)));
    }
 
 
@@ -550,7 +550,7 @@ public class QRecord implements Serializable
     *******************************************************************************/
    public Instant getValueInstant(String fieldName)
    {
-      return (ValueUtils.getValueAsInstant(values.get(fieldName)));
+      return (ValueUtils.getValueAsInstant(getValue(fieldName)));
    }
 
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/data/QRecordEntity.java

@@ -49,6 +49,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.ListingHash;
 import com.kingsrook.qqq.backend.core.utils.ObjectUtils;
+import com.kingsrook.qqq.backend.core.utils.ReflectiveBeanLikeClassUtils;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
@@ -208,6 +209,7 @@ public abstract class QRecordEntity
       try
       {
          QRecord qRecord = new QRecord();
+         qRecord.setTableName(tableName());
 
          for(QRecordEntityField qRecordEntityField : getFieldList(this.getClass()))
          {
@@ -325,13 +327,13 @@ public abstract class QRecordEntity
          List<QRecordEntityField> fieldList = new ArrayList<>();
          for(Method possibleGetter : c.getMethods())
          {
-            if(isGetter(possibleGetter))
+            if(ReflectiveBeanLikeClassUtils.isGetter(possibleGetter, true))
             {
-               Optional<Method> setter = getSetterForGetter(c, possibleGetter);
+               Optional<Method> setter = ReflectiveBeanLikeClassUtils.getSetterForGetter(c, possibleGetter);
 
                if(setter.isPresent())
                {
-                  String           fieldName       = getFieldNameFromGetter(possibleGetter);
+                  String           fieldName       = ReflectiveBeanLikeClassUtils.getFieldNameFromGetter(possibleGetter);
                   Optional<QField> fieldAnnotation = getQFieldAnnotation(c, fieldName);
 
                   if(fieldAnnotation.isPresent())
@@ -378,19 +380,19 @@ public abstract class QRecordEntity
          List<QRecordEntityAssociation> associationList = new ArrayList<>();
          for(Method possibleGetter : c.getMethods())
          {
-            if(isGetter(possibleGetter))
+            if(ReflectiveBeanLikeClassUtils.isGetter(possibleGetter, true))
             {
-               Optional<Method> setter = getSetterForGetter(c, possibleGetter);
+               Optional<Method> setter = ReflectiveBeanLikeClassUtils.getSetterForGetter(c, possibleGetter);
 
                if(setter.isPresent())
                {
-                  String                 fieldName             = getFieldNameFromGetter(possibleGetter);
+                  String                 fieldName             = ReflectiveBeanLikeClassUtils.getFieldNameFromGetter(possibleGetter);
                   Optional<QAssociation> associationAnnotation = getQAssociationAnnotation(c, fieldName);
 
                   if(associationAnnotation.isPresent())
                   {
                      @SuppressWarnings("unchecked")
-                     Class<? extends QRecordEntity> listTypeParam = (Class<? extends QRecordEntity>) getListTypeParam(possibleGetter.getReturnType(), possibleGetter.getAnnotatedReturnType());
+                     Class<? extends QRecordEntity> listTypeParam = (Class<? extends QRecordEntity>) ReflectiveBeanLikeClassUtils.getListTypeParam(possibleGetter.getReturnType(), possibleGetter.getAnnotatedReturnType());
                      associationList.add(new QRecordEntityAssociation(fieldName, possibleGetter, setter.get(), listTypeParam, associationAnnotation.orElse(null)));
                   }
                }
@@ -583,4 +585,31 @@ public abstract class QRecordEntity
       return (null);
    }
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static String getTableName(Class<? extends QRecordEntity> entityClass) throws QException
+   {
+      try
+      {
+         Field  tableNameField = entityClass.getDeclaredField("TABLE_NAME");
+         String tableNameValue = (String) tableNameField.get(null);
+         return (tableNameValue);
+      }
+      catch(Exception e)
+      {
+         throw (new QException("Could not get TABLE_NAME from entity class: " + entityClass.getSimpleName(), e));
+      }
+   }
+
+
+   /***************************************************************************
+    ** named without the 'get' to avoid conflict w/ entity fields named that...
+    ***************************************************************************/
+   public String tableName() throws QException
+   {
+      return (getTableName(this.getClass()));
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/data/QRecordEntityField.java

@@ -28,6 +28,7 @@ import java.math.BigDecimal;
 import java.time.Instant;
 import java.time.LocalDate;
 import java.time.LocalTime;
+import java.util.Map;
 import com.kingsrook.qqq.backend.core.exceptions.QValueException;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 
@@ -170,6 +171,11 @@ public class QRecordEntityField
          {
             return (ValueUtils.getValueAsByteArray(value));
          }
+
+         if(type.equals(Map.class))
+         {
+            return (ValueUtils.getValueAsMap(value));
+         }
       }
       catch(Exception e)
       {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/data/QRecordWithJoinedRecords.java

@@ -23,7 +23,9 @@ package com.kingsrook.qqq.backend.core.model.data;
 
 
 import java.io.Serializable;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.function.BiFunction;
 
@@ -198,4 +200,97 @@ public class QRecordWithJoinedRecords extends QRecord
       return (rs);
    }
 
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public Map<String, List<QRecord>> getAssociatedRecords()
+   {
+      return mainRecord.getAssociatedRecords();
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QRecord withAssociatedRecord(String name, QRecord associatedRecord)
+   {
+      mainRecord.withAssociatedRecord(name, associatedRecord);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QRecord withAssociatedRecords(Map<String, List<QRecord>> associatedRecords)
+   {
+      mainRecord.withAssociatedRecords(associatedRecords);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public void setAssociatedRecords(Map<String, List<QRecord>> associatedRecords)
+   {
+      mainRecord.setAssociatedRecords(associatedRecords);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QRecord withAssociatedRecords(String name, List<QRecord> associatedRecords)
+   {
+      mainRecord.withAssociatedRecords(name, associatedRecords);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    * Given an object of this type (`this`), add a list of join-records to it,
+    * producing a new list, which is `this` × joinRecordList.
+    * One may want to use this in a loop to build a larger cross product - more
+    * to come here in that spirit.
+    * @param joinTable name of the join table (e.g., to prefix the join fields)
+    * @param joinRecordList list of join records.  may not be null.  may be 0+ size.
+    * @return list of new QRecordWithJoinedRecords, based on `this` with each
+    * joinRecord added (e.g., output list is same size as joinRecordList).
+    * Note that does imply an 'inner' style join - where - if the joinRecordList
+    * is empty, you'll get back an empty list!
+    ***************************************************************************/
+   public List<QRecordWithJoinedRecords> buildCrossProduct(String joinTable, List<QRecord> joinRecordList)
+   {
+      List<QRecordWithJoinedRecords> rs = new ArrayList<>();
+
+      for(QRecord joinRecord : joinRecordList)
+      {
+         /////////////////////////////////////////////////////////////
+         // essentially clone the existing QRecordWithJoinedRecords //
+         /////////////////////////////////////////////////////////////
+         QRecordWithJoinedRecords newRecord = new QRecordWithJoinedRecords(mainRecord);
+         components.forEach((k, v) -> newRecord.addJoinedRecordValues(k, v));
+
+         ///////////////////////////////////////////
+         // now add the new join record to it too //
+         ///////////////////////////////////////////
+         newRecord.addJoinedRecordValues(joinTable, joinRecord);
+         rs.add(newRecord);
+      }
+
+      return (rs);
+   }
 }