Feedback from code review

Feature/ce 1887 mobile android app

.circleci/adjust-pom-version.sh

@@ -1,23 +1,51 @@
 #!/bin/bash
 
-if [ -z "$CIRCLE_BRANCH" ] && [ -z "$CIRCLE_TAG" ]; then
+############################################################################
-   echo "Error:  env vars CIRCLE_BRANCH and CIRCLE_TAG were not set."
+## adjust-pom.version.sh
-   exit 1;
+## During CircleCI builds - edit the qqq parent pom.xml, to set the
-fi
+## <revision> value such that:
+## - feature-branch builds, tagged as snapshot-*, deploy with a version
+##   number that includes that tag's name (minus the snapshot- part)
+## - integration-branch builds deploy with a version number that includes
+##   the branch name slugified
+## - we never deploy -SNAPSHOT versions any more - because we don't believe
+##   it is ever valid to not know exactly what versions you are getting
+##   (perhaps because we are too loose with our versioning?)
+############################################################################
 
-if [ "$CIRCLE_BRANCH" == "dev" ] || [ "$CIRCLE_BRANCH" == "staging" ] || [ "$CIRCLE_BRANCH" == "main" ] || [ \! -z $(echo "$CIRCLE_TAG" | grep "^version-") ]; then
+POM=$(dirname $0)/../pom.xml
-   echo "On a primary branch or tag [${CIRCLE_BRANCH}${CIRCLE_TAG}] - will not edit the pom version.";
+echo "On branch: $CIRCLE_BRANCH, tag: $CIRCLE_TAG..."
+
+######################################################################
+## ## only do anything if the committed pom has a -SNAPSHOT version ##
+######################################################################
+REVISION=$(grep '<revision>' $POM | sed 's/.*<revision>//;s/<.*//');
+echo "<revision> in pom.xml is: $REVISION"
+if [ \! $(echo "$REVISION" | grep SNAPSHOT) ]; then
+   echo "Not on a SNAPSHOT revision, so nothing to do here."
    exit 0;
 fi
 
-if [ -n "$CIRCLE_BRANCH" ]; then
+##################################################################################
-   SLUG=$(echo $CIRCLE_BRANCH | sed 's/[^a-zA-Z0-9]/-/g')
+## ## figure out if we need a SLUG:  a snapshot- tag, or an integration/ branch ##
-else
+##################################################################################
-   SLUG=$(echo $CIRCLE_TAG | sed 's/^snapshot-//g')
+SLUG=""
+if [ $(echo "$CIRCLE_TAG" | grep ^snapshot-) ]; then
+   SLUG=$(echo "$CIRCLE_TAG" | sed "s/^snapshot-//")-
+   echo "Using slug [$SLUG] from tag [$CIRCLE_TAG]"
+
+elif [ $(echo "$CIRCLE_BRANCH" |  grep ^integration/) ]; then
+   SLUG=$(echo "$CIRCLE_BRANCH" | sed "s,/,-,g")-
+   echo "Using slug [$SLUG] from branch [$CIRCLE_BRANCH]"
 fi
 
-POM=$(dirname $0)/../pom.xml
+################################################################
+## ## build the replcaement for -SNAPSHOT, and update the pom ##
+################################################################
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+REPLACEMENT=${SLUG}${TIMESTAMP}
 
-echo "Updating $POM <revision> to: $SLUG-SNAPSHOT"
+echo "Updating $POM -SNAPSHOT to: -$REPLACEMENT"
-sed -i "s/<revision>.*/<revision>$SLUG-SNAPSHOT<\/revision>/" $POM
+sed -i "s/-SNAPSHOT<\/revision>/-$REPLACEMENT<\/revision>/" $POM
 git diff $POM
+

.circleci/config.yml

@@ -79,6 +79,19 @@ commands:
             - ~/.m2
           key: v1-dependencies-{{ checksum "pom.xml" }}
 
+  check_middleware_api_versions:
+      steps:
+        - checkout
+        - restore_cache:
+            keys:
+              - v1-dependencies-{{ checksum "pom.xml" }}
+        - 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
+              qqq-middleware-javalin/target/appassembler/bin/ValidateApiVersions -r $(pwd)
+
   mvn_jar_deploy:
     steps:
       - checkout
@@ -130,6 +143,7 @@ jobs:
       ## - localstack/startup
       - install_java17
       - mvn_verify
+      - check_middleware_api_versions
 
   mvn_deploy:
     executor: localstack/default
@@ -137,6 +151,7 @@ jobs:
       ## - localstack/startup
       - install_java17
       - mvn_verify
+      - check_middleware_api_versions
       - mvn_jar_deploy
 
   publish_asciidoc:

pom.xml

@@ -36,6 +36,7 @@
       <module>qqq-backend-module-rdbms</module>
       <module>qqq-backend-module-mongodb</module>
       <module>qqq-language-support-javascript</module>
+      <module>qqq-openapi</module>
       <module>qqq-middleware-picocli</module>
       <module>qqq-middleware-javalin</module>
       <module>qqq-middleware-lambda</module>
@@ -46,7 +47,7 @@
    </modules>
 
    <properties>
-      <revision>0.21.0-SNAPSHOT</revision>
+      <revision>0.23.0-SNAPSHOT</revision>
 
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

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

@@ -225,7 +225,13 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
                {
                   if(auditSingleInput.getSecurityKeyValues() == null || !auditSingleInput.getSecurityKeyValues().containsKey(recordSecurityLock.getSecurityKeyType()))
                   {
-                     throw (new QException("Missing securityKeyValue [" + recordSecurityLock.getSecurityKeyType() + "] in audit request for table " + auditSingleInput.getAuditTableName()));
+                     ///////////////////////////////////////////////////////
+                     // originally, this case threw...                    //
+                     // but i think it's better to record the audit, just //
+                     // missing its security key value, then to fail...   //
+                     ///////////////////////////////////////////////////////
+                     // throw (new QException("Missing securityKeyValue [" + recordSecurityLock.getSecurityKeyType() + "] in audit request for table " + auditSingleInput.getAuditTableName()));
+                     LOG.info("Missing securityKeyValue in audit request", logPair("table", auditSingleInput.getAuditTableName()), logPair("securityKey", recordSecurityLock.getSecurityKeyType()));
                   }
                }
 
@@ -272,7 +278,7 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
             List<QRecord> auditDetailRecords = new ArrayList<>();
             for(AuditSingleInput auditSingleInput : CollectionUtils.nonNullList(input.getAuditSingleInputList()))
             {
-               Integer auditId = insertOutput.getRecords().get(i++).getValueInteger("id");
+               Long auditId = insertOutput.getRecords().get(i++).getValueLong("id");
                if(auditId == null)
                {
                   LOG.warn("Missing an id for inserted audit - so won't be able to store its child details...");

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

@@ -23,11 +23,11 @@ package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 
 
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.AlertData;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
@@ -40,9 +40,9 @@ import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
  ** - alertType - name of entry in AlertType enum (ERROR, WARNING, SUCCESS)
  ** - alertHtml - html to display inside the alert (other than its icon)
  *******************************************************************************/
-public class ProcessAlertWidget extends AbstractWidgetRenderer implements MetaDataProducerInterface<QWidgetMetaData>
+public class AlertWidgetRenderer extends AbstractWidgetRenderer implements MetaDataProducerInterface<QWidgetMetaData>
 {
-   public static final String NAME = "ProcessAlertWidget";
+   public static final String NAME = "AlertWidgetRenderer";
 
 
 

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

@@ -301,6 +301,9 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
             }
          }
 
+         widgetData.setAllowRecordEdit(BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(input.getQueryParams().get("allowRecordEdit"))));
+         widgetData.setAllowRecordDelete(BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(input.getQueryParams().get("allowRecordDelete"))));
+
          return (new RenderWidgetOutput(widgetData));
       }
       catch(Exception e)

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/metadata/AllowAllMetaDataFilter.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 allows all the things
+ *******************************************************************************/
+public class AllowAllMetaDataFilter implements MetaDataFilterInterface
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @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

@@ -28,13 +28,18 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 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;
 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.logging.QLogger;
 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.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+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.frontend.AppTreeNode;
 import com.kingsrook.qqq.backend.core.model.metadata.frontend.QFrontendAppMetaData;
@@ -49,6 +54,7 @@ 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;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.memoization.Memoization;
 
 
 /*******************************************************************************
@@ -57,6 +63,12 @@ import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
  *******************************************************************************/
 public class MetaDataAction
 {
+   private static final QLogger LOG = QLogger.getLogger(MetaDataAction.class);
+
+   private static Memoization<QInstance, MetaDataFilterInterface> metaDataFilterMemoization = new Memoization<>();
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -64,10 +76,10 @@ public class MetaDataAction
    {
       ActionHelper.validateSession(metaDataInput);
 
-      // todo pre-customization - just get to modify the request?
+      MetaDataOutput           metaDataOutput = new MetaDataOutput();
-      MetaDataOutput metaDataOutput = new MetaDataOutput();
+      Map<String, AppTreeNode> treeNodes      = new LinkedHashMap<>();
 
-      Map<String, AppTreeNode> treeNodes = new LinkedHashMap<>();
+      MetaDataFilterInterface filter = getMetaDataFilter();
 
       /////////////////////////////////////
       // map tables to frontend metadata //
@@ -78,6 +90,11 @@ public class MetaDataAction
          String         tableName = entry.getKey();
          QTableMetaData table     = entry.getValue();
 
+         if(!filter.allowTable(metaDataInput, table))
+         {
+            continue;
+         }
+
          PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, table);
          if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
          {
@@ -102,6 +119,11 @@ public class MetaDataAction
          String           processName = entry.getKey();
          QProcessMetaData process     = entry.getValue();
 
+         if(!filter.allowProcess(metaDataInput, process))
+         {
+            continue;
+         }
+
          PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, process);
          if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
          {
@@ -122,6 +144,11 @@ public class MetaDataAction
          String          reportName = entry.getKey();
          QReportMetaData report     = entry.getValue();
 
+         if(!filter.allowReport(metaDataInput, report))
+         {
+            continue;
+         }
+
          PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, report);
          if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
          {
@@ -142,6 +169,11 @@ public class MetaDataAction
          String                   widgetName = entry.getKey();
          QWidgetMetaDataInterface widget     = entry.getValue();
 
+         if(!filter.allowWidget(metaDataInput, widget))
+         {
+            continue;
+         }
+
          PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, widget);
          if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
          {
@@ -174,9 +206,19 @@ public class MetaDataAction
             continue;
          }
 
-         apps.put(appName, new QFrontendAppMetaData(app, metaDataOutput));
+         if(!filter.allowApp(metaDataInput, app))
-         treeNodes.put(appName, new AppTreeNode(app));
+         {
+            continue;
+         }
 
+         //////////////////////////////////////
+         // build the frontend-app meta-data //
+         //////////////////////////////////////
+         QFrontendAppMetaData frontendAppMetaData = new QFrontendAppMetaData(app, metaDataOutput);
+
+         /////////////////////////////////////////
+         // add children (if they're permitted) //
+         /////////////////////////////////////////
          if(CollectionUtils.nullSafeHasContents(app.getChildren()))
          {
             for(QAppChildMetaData child : app.getChildren())
@@ -190,9 +232,42 @@ public class MetaDataAction
                   }
                }
 
-               apps.get(appName).addChild(new AppTreeNode(child));
+               //////////////////////////////////////////////////////////////////////////////////////////////////////
+               // if the child was filtered away, so it isn't in its corresponding map, then don't include it here //
+               //////////////////////////////////////////////////////////////////////////////////////////////////////
+               if(child instanceof QTableMetaData table && !tables.containsKey(table.getName()))
+               {
+                  continue;
+               }
+               if(child instanceof QProcessMetaData process && !processes.containsKey(process.getName()))
+               {
+                  continue;
+               }
+               if(child instanceof QReportMetaData report && !reports.containsKey(report.getName()))
+               {
+                  continue;
+               }
+               if(child instanceof QAppMetaData childApp && !apps.containsKey(childApp.getName()))
+               {
+                  // continue;
+               }
+
+               frontendAppMetaData.addChild(new AppTreeNode(child));
             }
          }
+
+         //////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if the app ended up having no children, then discard it                                          //
+         // todo - i think this was wrong, because it didn't take into account ... something nested maybe... //
+         //////////////////////////////////////////////////////////////////////////////////////////////////////
+         if(CollectionUtils.nullSafeIsEmpty(frontendAppMetaData.getChildren()) && CollectionUtils.nullSafeIsEmpty(frontendAppMetaData.getWidgets()))
+         {
+            // LOG.debug("Discarding empty app", logPair("name", frontendAppMetaData.getName()));
+            // continue;
+         }
+
+         apps.put(appName, frontendAppMetaData);
+         treeNodes.put(appName, new AppTreeNode(app));
       }
       metaDataOutput.setApps(apps);
 
@@ -228,6 +303,33 @@ public class MetaDataAction
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private MetaDataFilterInterface getMetaDataFilter()
+   {
+      return metaDataFilterMemoization.getResult(QContext.getQInstance(), i ->
+      {
+         MetaDataFilterInterface filter                  = null;
+         QCodeReference          metaDataFilterReference = QContext.getQInstance().getMetaDataFilter();
+         if(metaDataFilterReference != null)
+         {
+            filter = QCodeLoader.getAdHoc(MetaDataFilterInterface.class, metaDataFilterReference);
+            LOG.debug("Using new meta-data filter of type: " + filter.getClass().getSimpleName());
+         }
+
+         if(filter == null)
+         {
+            filter = new AllowAllMetaDataFilter();
+            LOG.debug("Using new default (allow-all) meta-data filter");
+         }
+
+         return (filter);
+      }).orElseThrow(() -> new QRuntimeException("Error getting metaDataFilter"));
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/

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

@@ -0,0 +1,64 @@
+/*
+ * 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;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public interface MetaDataFilterInterface
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   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

@@ -40,6 +40,7 @@ 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;
 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.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFunctionInputMetaData;
@@ -257,11 +258,20 @@ public class RunBackendStepAction
       {
          runBackendStepOutput.seedFromRequest(runBackendStepInput);
 
-         Class<?> codeClass  = Class.forName(code.getName());
+         Object codeObject;
-         Object   codeObject = codeClass.getConstructor().newInstance();
+         if(code instanceof QCodeReferenceLambda<?> qCodeReferenceLambda)
+         {
+            codeObject = qCodeReferenceLambda.getLambda();
+         }
+         else
+         {
+            Class<?> codeClass = Class.forName(code.getName());
+            codeObject = codeClass.getConstructor().newInstance();
+         }
+
          if(!(codeObject instanceof BackendStep backendStepCodeObject))
          {
-            throw (new QException("The supplied code [" + codeClass.getName() + "] is not an instance of BackendStep"));
+            throw (new QException("The supplied codeReference [" + code + "] is not a reference to a BackendStep"));
          }
 
          backendStepCodeObject.run(runBackendStepInput, runBackendStepOutput);

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

@@ -28,6 +28,7 @@ import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.UUID;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
@@ -58,6 +59,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaD
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QStateMachineStep;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.processes.implementations.basepull.BasepullConfiguration;
@@ -79,6 +81,7 @@ public class RunProcessAction
 {
    private static final QLogger LOG = QLogger.getLogger(RunProcessAction.class);
 
+   public static final String BASEPULL_KEY_VALUE        = "basepullKeyValue";
    public static final String BASEPULL_THIS_RUNTIME_KEY = "basepullThisRuntimeKey";
    public static final String BASEPULL_LAST_RUNTIME_KEY = "basepullLastRuntimeKey";
    public static final String BASEPULL_TIMESTAMP_FIELD  = "basepullTimestampField";
@@ -133,90 +136,11 @@ public class RunProcessAction
 
       try
       {
-         String lastStepName = runProcessInput.getStartAfterStep();
+         switch(Objects.requireNonNull(process.getStepFlow(), "Process [" + process.getName() + "] has a null stepFlow."))
-
-         STEP_LOOP:
-         while(true)
          {
-            ///////////////////////////////////////////////////////////////////////////////////////////////////////
+            case LINEAR -> runLinearStepLoop(process, processState, stateKey, runProcessInput, runProcessOutput);
-            // always refresh the step list - as any step that runs can modify it (in the process state).        //
+            case STATE_MACHINE -> runStateMachineStep(runProcessInput.getStartAfterStep(), process, processState, stateKey, runProcessInput, runProcessOutput, 0);
-            // this is why we don't do a loop over the step list - as we'd get ConcurrentModificationExceptions. //
+            default -> throw (new QException("Unhandled process step flow: " + process.getStepFlow()));
-            ///////////////////////////////////////////////////////////////////////////////////////////////////////
-            List<QStepMetaData> stepList = getAvailableStepList(processState, process, lastStepName);
-            if(stepList.isEmpty())
-            {
-               break;
-            }
-
-            QStepMetaData step = stepList.get(0);
-            lastStepName = step.getName();
-
-            if(step instanceof QFrontendStepMetaData frontendStep)
-            {
-               ////////////////////////////////////////////////////////////////
-               // Handle what to do with frontend steps, per request setting //
-               ////////////////////////////////////////////////////////////////
-               switch(runProcessInput.getFrontendStepBehavior())
-               {
-                  case BREAK ->
-                  {
-                     LOG.trace("Breaking process [" + process.getName() + "] at frontend step (as requested by caller): " + step.getName());
-                     processFrontendStepFieldDefaultValues(processState, frontendStep);
-                     processFrontendComponents(processState, frontendStep);
-                     processState.setNextStepName(step.getName());
-                     break STEP_LOOP;
-                  }
-                  case SKIP ->
-                  {
-                     LOG.trace("Skipping frontend step [" + step.getName() + "] in process [" + process.getName() + "] (as requested by caller)");
-
-                     //////////////////////////////////////////////////////////////////////
-                     // much less error prone in case this code changes in the future... //
-                     //////////////////////////////////////////////////////////////////////
-                     // noinspection UnnecessaryContinue
-                     continue;
-                  }
-                  case FAIL ->
-                  {
-                     LOG.trace("Throwing error for frontend step [" + step.getName() + "] in process [" + process.getName() + "] (as requested by caller)");
-                     throw (new QException("Failing process at step " + step.getName() + " (as requested, to fail on frontend steps)"));
-                  }
-                  default -> throw new IllegalStateException("Unexpected value: " + runProcessInput.getFrontendStepBehavior());
-               }
-            }
-            else if(step instanceof QBackendStepMetaData backendStepMetaData)
-            {
-               ///////////////////////
-               // Run backend steps //
-               ///////////////////////
-               LOG.debug("Running backend step [" + step.getName() + "] in process [" + process.getName() + "]");
-               RunBackendStepOutput runBackendStepOutput = runBackendStep(runProcessInput, process, runProcessOutput, stateKey, backendStepMetaData, process, processState);
-
-               /////////////////////////////////////////////////////////////////////////////////////////
-               // if the step returned an override lastStepName, use that to determine how we proceed //
-               /////////////////////////////////////////////////////////////////////////////////////////
-               if(runBackendStepOutput.getOverrideLastStepName() != null)
-               {
-                  LOG.debug("Process step [" + lastStepName + "] returned an overrideLastStepName [" + runBackendStepOutput.getOverrideLastStepName() + "]!");
-                  lastStepName = runBackendStepOutput.getOverrideLastStepName();
-               }
-
-               /////////////////////////////////////////////////////////////////////////////////////////////
-               // similarly, if the step produced an updatedFrontendStepList, propagate that data outward //
-               /////////////////////////////////////////////////////////////////////////////////////////////
-               if(runBackendStepOutput.getUpdatedFrontendStepList() != null)
-               {
-                  LOG.debug("Process step [" + lastStepName + "] generated an updatedFrontendStepList [" + runBackendStepOutput.getUpdatedFrontendStepList().stream().map(s -> s.getName()).toList() + "]!");
-                  runProcessOutput.setUpdatedFrontendStepList(runBackendStepOutput.getUpdatedFrontendStepList());
-               }
-            }
-            else
-            {
-               //////////////////////////////////////////////////
-               // in case we have a different step type, throw //
-               //////////////////////////////////////////////////
-               throw (new QException("Unsure how to run a step of type: " + step.getClass().getName()));
-            }
          }
 
          ///////////////////////////////////////////////////////////////////////////
@@ -258,6 +182,270 @@ public class RunProcessAction
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void runLinearStepLoop(QProcessMetaData process, ProcessState processState, UUIDAndTypeStateKey stateKey, RunProcessInput runProcessInput, RunProcessOutput runProcessOutput) throws Exception
+   {
+      String lastStepName = runProcessInput.getStartAfterStep();
+
+      while(true)
+      {
+         ///////////////////////////////////////////////////////////////////////////////////////////////////////
+         // always refresh the step list - as any step that runs can modify it (in the process state).        //
+         // this is why we don't do a loop over the step list - as we'd get ConcurrentModificationExceptions. //
+         ///////////////////////////////////////////////////////////////////////////////////////////////////////
+         List<QStepMetaData> stepList = getAvailableStepList(processState, process, lastStepName);
+         if(stepList.isEmpty())
+         {
+            break;
+         }
+
+         QStepMetaData step = stepList.get(0);
+         lastStepName = step.getName();
+
+         if(step instanceof QFrontendStepMetaData frontendStep)
+         {
+            LoopTodo loopTodo = prepareForFrontendStep(runProcessInput, process, frontendStep, processState);
+            if(loopTodo == LoopTodo.BREAK)
+            {
+               break;
+            }
+         }
+         else if(step instanceof QBackendStepMetaData backendStepMetaData)
+         {
+            RunBackendStepOutput runBackendStepOutput = runBackendStep(process, processState, stateKey, runProcessInput, runProcessOutput, backendStepMetaData, step);
+
+            /////////////////////////////////////////////////////////////////////////////////////////
+            // if the step returned an override lastStepName, use that to determine how we proceed //
+            /////////////////////////////////////////////////////////////////////////////////////////
+            if(runBackendStepOutput.getOverrideLastStepName() != null)
+            {
+               LOG.debug("Process step [" + lastStepName + "] returned an overrideLastStepName [" + runBackendStepOutput.getOverrideLastStepName() + "]!");
+               lastStepName = runBackendStepOutput.getOverrideLastStepName();
+            }
+         }
+         else
+         {
+            //////////////////////////////////////////////////
+            // in case we have a different step type, throw //
+            //////////////////////////////////////////////////
+            throw (new QException("Unsure how to run a step of type: " + step.getClass().getName()));
+         }
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private enum LoopTodo
+   {
+      BREAK,
+      CONTINUE
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private LoopTodo prepareForFrontendStep(RunProcessInput runProcessInput, QProcessMetaData process, QFrontendStepMetaData step, ProcessState processState) throws QException
+   {
+      ////////////////////////////////////////////////////////////////
+      // Handle what to do with frontend steps, per request setting //
+      ////////////////////////////////////////////////////////////////
+      switch(runProcessInput.getFrontendStepBehavior())
+      {
+         case BREAK ->
+         {
+            LOG.trace("Breaking process [" + process.getName() + "] at frontend step (as requested by caller): " + step.getName());
+            processFrontendStepFieldDefaultValues(processState, step);
+            processFrontendComponents(processState, step);
+            processState.setNextStepName(step.getName());
+            return LoopTodo.BREAK;
+         }
+         case SKIP ->
+         {
+            LOG.trace("Skipping frontend step [" + step.getName() + "] in process [" + process.getName() + "] (as requested by caller)");
+            return LoopTodo.CONTINUE;
+         }
+         case FAIL ->
+         {
+            LOG.trace("Throwing error for frontend step [" + step.getName() + "] in process [" + process.getName() + "] (as requested by caller)");
+            throw (new QException("Failing process at step " + step.getName() + " (as requested, to fail on frontend steps)"));
+         }
+         default -> throw new IllegalStateException("Unexpected value: " + runProcessInput.getFrontendStepBehavior());
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void runStateMachineStep(String lastStepName, QProcessMetaData process, ProcessState processState, UUIDAndTypeStateKey stateKey, RunProcessInput runProcessInput, RunProcessOutput runProcessOutput, int stackDepth) throws Exception
+   {
+      //////////////////////////////
+      // check for stack-overflow //
+      //////////////////////////////
+      Integer maxStateMachineProcessStepFlowStackDepth = Objects.requireNonNullElse(runProcessInput.getValueInteger("maxStateMachineProcessStepFlowStackDepth"), 20);
+      if(stackDepth > maxStateMachineProcessStepFlowStackDepth)
+      {
+         throw (new QException("StateMachine process recurred too many times (exceeded maxStateMachineProcessStepFlowStackDepth of " + maxStateMachineProcessStepFlowStackDepth + ")"));
+      }
+
+      //////////////////////////////////
+      // figure out what step to run: //
+      //////////////////////////////////
+      QStepMetaData step = null;
+      if(!StringUtils.hasContent(lastStepName))
+      {
+         ////////////////////////////////////////////////////////////////////
+         // if no lastStepName is given, start at the process's first step //
+         ////////////////////////////////////////////////////////////////////
+         if(CollectionUtils.nullSafeIsEmpty(process.getStepList()))
+         {
+            throw (new QException("Process [" + process.getName() + "] does not have a step list defined."));
+         }
+         step = process.getStepList().get(0);
+      }
+      else
+      {
+         /////////////////////////////////////
+         // else run the given lastStepName //
+         /////////////////////////////////////
+         processState.clearNextStepName();
+         step = process.getStep(lastStepName);
+         if(step == null)
+         {
+            throw (new QException("Could not find step by name [" + lastStepName + "]"));
+         }
+      }
+
+      /////////////////////////////////////////////////////////////////////////
+      // for the flow of:                                                    //
+      // we were on a frontend step (as a sub-step of a state machine step), //
+      // and now we're here to run that state-step's backend step -          //
+      // find the state-machine step containing this frontend step.          //
+      /////////////////////////////////////////////////////////////////////////
+      String skipSubStepsUntil = null;
+      if(step instanceof QFrontendStepMetaData frontendStepMetaData)
+      {
+         QStateMachineStep stateMachineStep = getStateMachineStepContainingSubStep(process, frontendStepMetaData.getName());
+         if(stateMachineStep == null)
+         {
+            throw (new QException("Could not find stateMachineStep that contains last-frontend step: " + frontendStepMetaData.getName()));
+         }
+         step = stateMachineStep;
+
+         //////////////////////////////////////////////////////////////////////////////////
+         // set this flag, to know to skip this frontend step in the sub-step loop below //
+         //////////////////////////////////////////////////////////////////////////////////
+         skipSubStepsUntil = frontendStepMetaData.getName();
+      }
+
+      if(!(step instanceof QStateMachineStep stateMachineStep))
+      {
+         throw (new QException("Have a non-stateMachineStep in a process using stateMachine flow... " + step.getClass().getName()));
+      }
+
+      ///////////////////////
+      // run the sub-steps //
+      ///////////////////////
+      boolean ranAnySubSteps = false;
+      for(QStepMetaData subStep : stateMachineStep.getSubSteps())
+      {
+         ///////////////////////////////////////////////////////////////////////////////////////////////
+         // ok, well, skip them if this flag is set (and clear the flag once we've hit this sub-step) //
+         ///////////////////////////////////////////////////////////////////////////////////////////////
+         if(skipSubStepsUntil != null)
+         {
+            if(skipSubStepsUntil.equals(subStep.getName()))
+            {
+               skipSubStepsUntil = null;
+            }
+            continue;
+         }
+
+         ranAnySubSteps = true;
+         if(subStep instanceof QFrontendStepMetaData frontendStep)
+         {
+            LoopTodo loopTodo = prepareForFrontendStep(runProcessInput, process, frontendStep, processState);
+            if(loopTodo == LoopTodo.BREAK)
+            {
+               return;
+            }
+         }
+         else if(subStep instanceof QBackendStepMetaData backendStepMetaData)
+         {
+            RunBackendStepOutput runBackendStepOutput = runBackendStep(process, processState, stateKey, runProcessInput, runProcessOutput, backendStepMetaData, step);
+            Optional<String>     nextStepName         = runBackendStepOutput.getProcessState().getNextStepName();
+
+            if(nextStepName.isEmpty() && StringUtils.hasContent(stateMachineStep.getDefaultNextStepName()))
+            {
+               nextStepName = Optional.of(stateMachineStep.getDefaultNextStepName());
+            }
+
+            if(nextStepName.isPresent())
+            {
+               //////////////////////////////////////////////////////////////////////////////////////////////////////
+               // if we've been given a next-step-name, go to that step now.                                       //
+               // it might be a backend-only stateMachineStep, in which case, we should run that backend step now. //
+               // or it might be a frontend-then-backend step, in which case, we want to go to that frontend step. //
+               // if we weren't given a next-step-name, then we should stay in the same state - either to finish   //
+               // its sub-steps, or, to fall out of the loop and end the process.                                  //
+               //////////////////////////////////////////////////////////////////////////////////////////////////////
+               processState.clearNextStepName();
+               runStateMachineStep(nextStepName.get(), process, processState, stateKey, runProcessInput, runProcessOutput, stackDepth + 1);
+               return;
+            }
+         }
+         else
+         {
+            //////////////////////////////////////////////////
+            // in case we have a different step type, throw //
+            //////////////////////////////////////////////////
+            throw (new QException("Unsure how to run a step of type: " + step.getClass().getName()));
+         }
+      }
+
+      if(!ranAnySubSteps)
+      {
+         if(StringUtils.hasContent(stateMachineStep.getDefaultNextStepName()))
+         {
+            runStateMachineStep(stateMachineStep.getDefaultNextStepName(), process, processState, stateKey, runProcessInput, runProcessOutput, stackDepth + 1);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QStateMachineStep getStateMachineStepContainingSubStep(QProcessMetaData process, String stepName)
+   {
+      for(QStepMetaData step : process.getAllSteps().values())
+      {
+         if(step instanceof QStateMachineStep stateMachineStep)
+         {
+            for(QStepMetaData subStep : stateMachineStep.getSubSteps())
+            {
+               if(subStep.getName().equals(stepName))
+               {
+                  return (stateMachineStep);
+               }
+            }
+         }
+      }
+
+      return (null);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -335,12 +523,12 @@ public class RunProcessAction
          ///////////////////////////////////////////////////
          runProcessInput.seedFromProcessState(optionalProcessState.get());
 
-         ///////////////////////////////////////////////////////////////////////////////////////////////////
+         /////////////////////////////////////////////////////////////////////////////////////////////////////
-         // if we're restoring an old state, we can discard a previously stored updatedFrontendStepList - //
+         // if we're restoring an old state, we can discard a previously stored processMetaDataAdjustment - //
-         // it is only needed on the transitional edge from a backend-step to a frontend step, but not    //
+         // it is only needed on the transitional edge from a backend-step to a frontend step, but not      //
-         // in the other directly                                                                         //
+         // in the other directly                                                                           //
-         ///////////////////////////////////////////////////////////////////////////////////////////////////
+         /////////////////////////////////////////////////////////////////////////////////////////////////////
-         optionalProcessState.get().setUpdatedFrontendStepList(null);
+         optionalProcessState.get().setProcessMetaDataAdjustment(null);
 
          ///////////////////////////////////////////////////////////////////////////
          // if there were values from the caller, put those (back) in the request //
@@ -355,16 +543,40 @@ public class RunProcessAction
       }
 
       ProcessState processState = optionalProcessState.get();
-      processState.clearNextStepName();
       return processState;
    }
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private RunBackendStepOutput runBackendStep(QProcessMetaData process, ProcessState processState, UUIDAndTypeStateKey stateKey, RunProcessInput runProcessInput, RunProcessOutput runProcessOutput, QBackendStepMetaData backendStepMetaData, QStepMetaData step) throws Exception
+   {
+      ///////////////////////
+      // Run backend steps //
+      ///////////////////////
+      LOG.debug("Running backend step [" + step.getName() + "] in process [" + process.getName() + "]");
+      RunBackendStepOutput runBackendStepOutput = runBackendStep(runProcessInput, process, runProcessOutput, stateKey, backendStepMetaData, process, processState);
+
+      //////////////////////////////////////////////////////////////////////////////////////////////
+      // similarly, if the step produced a processMetaDataAdjustment, propagate that data outward //
+      //////////////////////////////////////////////////////////////////////////////////////////////
+      if(runBackendStepOutput.getProcessMetaDataAdjustment() != null)
+      {
+         LOG.debug("Process step [" + step.getName() + "] generated a ProcessMetaDataAdjustment [" + runBackendStepOutput.getProcessMetaDataAdjustment() + "]!");
+         runProcessOutput.setProcessMetaDataAdjustment(runBackendStepOutput.getProcessMetaDataAdjustment());
+      }
+
+      return runBackendStepOutput;
+   }
+
+
+
    /*******************************************************************************
     ** Run a single backend step.
     *******************************************************************************/
-   protected RunBackendStepOutput runBackendStep(RunProcessInput runProcessInput, QProcessMetaData process, RunProcessOutput runProcessOutput, UUIDAndTypeStateKey stateKey, QBackendStepMetaData backendStep, QProcessMetaData qProcessMetaData, ProcessState processState) throws Exception
+   RunBackendStepOutput runBackendStep(RunProcessInput runProcessInput, QProcessMetaData process, RunProcessOutput runProcessOutput, UUIDAndTypeStateKey stateKey, QBackendStepMetaData backendStep, QProcessMetaData qProcessMetaData, ProcessState processState) throws Exception
    {
       RunBackendStepInput runBackendStepInput = new RunBackendStepInput(processState);
       runBackendStepInput.setProcessName(process.getName());
@@ -517,9 +729,13 @@ public class RunProcessAction
    /*******************************************************************************
     **
     *******************************************************************************/
-   protected String determineBasepullKeyValue(QProcessMetaData process, BasepullConfiguration basepullConfiguration) throws QException
+   protected String determineBasepullKeyValue(QProcessMetaData process, RunProcessInput runProcessInput, BasepullConfiguration basepullConfiguration) throws QException
    {
       String basepullKeyValue = (basepullConfiguration.getKeyValue() != null) ? basepullConfiguration.getKeyValue() : process.getName();
+      if(runProcessInput.getValueString(BASEPULL_KEY_VALUE) != null)
+      {
+         basepullKeyValue = runProcessInput.getValueString(BASEPULL_KEY_VALUE);
+      }
 
       //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
       // if process specifies that it uses variants, look for that data in the session and append to our basepull key //
@@ -551,7 +767,7 @@ public class RunProcessAction
       String basepullTableName            = basepullConfiguration.getTableName();
       String basepullKeyFieldName         = basepullConfiguration.getKeyField();
       String basepullLastRunTimeFieldName = basepullConfiguration.getLastRunTimeFieldName();
-      String basepullKeyValue             = determineBasepullKeyValue(process, basepullConfiguration);
+      String basepullKeyValue             = determineBasepullKeyValue(process, runProcessInput, basepullConfiguration);
 
       ///////////////////////////////////////
       // get the stored basepull timestamp //
@@ -631,7 +847,7 @@ public class RunProcessAction
       String  basepullKeyFieldName                 = basepullConfiguration.getKeyField();
       String  basepullLastRunTimeFieldName         = basepullConfiguration.getLastRunTimeFieldName();
       Integer basepullHoursBackForInitialTimestamp = basepullConfiguration.getHoursBackForInitialTimestamp();
-      String  basepullKeyValue                     = determineBasepullKeyValue(process, basepullConfiguration);
+      String  basepullKeyValue                     = determineBasepullKeyValue(process, runProcessInput, basepullConfiguration);
 
       ///////////////////////////////////////
       // get the stored basepull timestamp //

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

@@ -63,6 +63,8 @@ import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QueryHint;
 import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.CriteriaMissingInputValueBehavior;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.FilterUseCase;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.JoinsContext;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
@@ -614,7 +616,56 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
          return;
       }
 
-      queryFilter.interpretValues(reportInput.getInputValues());
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // for reports defined in meta-data, the established rule is, that missing input variable values are discarded. //
+      // but for non-meta-data reports (e.g., user-saved), we expect an exception for missing values.                 //
+      // so, set those use-cases up.                                                                                  //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      FilterUseCase filterUseCase;
+      if(StringUtils.hasContent(reportInput.getReportName()) && QContext.getQInstance().getReport(reportInput.getReportName()) != null)
+      {
+         filterUseCase = new ReportFromMetaDataFilterUseCase();
+      }
+      else
+      {
+         filterUseCase = new ReportNotFromMetaDataFilterUseCase();
+      }
+
+      queryFilter.interpretValues(reportInput.getInputValues(), filterUseCase);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class ReportFromMetaDataFilterUseCase implements FilterUseCase
+   {
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.REMOVE_FROM_FILTER;
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class ReportNotFromMetaDataFilterUseCase implements FilterUseCase
+   {
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.THROW_EXCEPTION;
+      }
    }
 
 

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

@@ -54,6 +54,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
 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.data.QRecordEntity;
 import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
@@ -266,6 +267,22 @@ public class QueryAction
 
 
 
+   /*******************************************************************************
+    ** shorthand way to call for the most common use-case, when you just want the
+    ** entities to be returned, and you just want to pass in a table name and filter.
+    *******************************************************************************/
+   public static <T extends QRecordEntity> List<T> execute(String tableName, Class<T> entityClass, QQueryFilter filter) throws QException
+   {
+      QueryAction queryAction = new QueryAction();
+      QueryInput  queryInput  = new QueryInput();
+      queryInput.setTableName(tableName);
+      queryInput.setFilter(filter);
+      QueryOutput queryOutput = queryAction.execute(queryInput);
+      return (queryOutput.getRecordEntities(entityClass));
+   }
+
+
+
    /*******************************************************************************
     ** shorthand way to call for the most common use-case, when you just want the
     ** records to be returned, and you just want to pass in a table name and filter.

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

@@ -28,7 +28,6 @@ import java.time.LocalDateTime;
 import java.time.LocalTime;
 import java.time.ZonedDateTime;
 import java.time.format.DateTimeFormatter;
-import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -468,7 +467,8 @@ public class QValueFormatter
    {
       for(QFieldMetaData field : table.getFields().values())
       {
-         if(field.getType().equals(QFieldType.BLOB))
+         Optional<FieldAdornment> fileDownloadAdornment = field.getAdornment(AdornmentType.FILE_DOWNLOAD);
+         if(fileDownloadAdornment.isPresent())
          {
             //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
             // file name comes from:                                                                                            //
@@ -478,20 +478,7 @@ public class QValueFormatter
             // - tableLabel primaryKey fieldLabel                                                                               //
             // - and - if the FILE_DOWNLOAD adornment had a DEFAULT_EXTENSION, then it gets added (preceded by a dot)           //
             //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-            Optional<FieldAdornment>  fileDownloadAdornment = field.getAdornment(AdornmentType.FILE_DOWNLOAD);
+            Map<String, Serializable> adornmentValues = fileDownloadAdornment.get().getValues();
-            Map<String, Serializable> adornmentValues       = Collections.emptyMap();
-
-            if(fileDownloadAdornment.isPresent())
-            {
-               adornmentValues = fileDownloadAdornment.get().getValues();
-            }
-            else
-            {
-               ///////////////////////////////////////////////////////
-               // don't change blobs unless they are file-downloads //
-               ///////////////////////////////////////////////////////
-               continue;
-            }
 
             String fileNameField    = ValueUtils.getValueAsString(adornmentValues.get(AdornmentType.FileDownloadValues.FILE_NAME_FIELD));
             String fileNameFormat   = ValueUtils.getValueAsString(adornmentValues.get(AdornmentType.FileDownloadValues.FILE_NAME_FORMAT));
@@ -542,7 +529,13 @@ public class QValueFormatter
                   }
                }
 
-               record.setValue(field.getName(), "/data/" + table.getName() + "/" + primaryKey + "/" + field.getName() + "/" + fileName);
+               /////////////////////////////////////////////
+               // if field type is blob, update its value //
+               /////////////////////////////////////////////
+               if(QFieldType.BLOB.equals(field.getType()))
+               {
+                  record.setValue(field.getName(), "/data/" + table.getName() + "/" + primaryKey + "/" + field.getName() + "/" + fileName);
+               }
                record.setDisplayValue(field.getName(), fileName);
             }
          }

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

@@ -260,9 +260,6 @@ public class SearchPossibleValueSourceAction
          }
       }
 
-      // todo - skip & limit as params
-      queryFilter.setLimit(250);
-
       ///////////////////////////////////////////////////////////////////////////////////////////////////////
       // if given a default filter, make it the 'top level' filter and the one we just created a subfilter //
       ///////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -272,6 +269,9 @@ public class SearchPossibleValueSourceAction
          queryFilter = input.getDefaultQueryFilter();
       }
 
+      // todo - skip & limit as params
+      queryFilter.setLimit(250);
+
       queryFilter.setOrderBys(possibleValueSource.getOrderByFields());
 
       queryInput.setFilter(queryFilter);

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

@@ -0,0 +1,55 @@
+/*
+ * 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;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerHelper;
+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.
+ *******************************************************************************/
+public abstract class AbstractMetaDataProducerBasedQQQApplication extends AbstractQQQApplication
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public abstract String getMetaDataPackageName();
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QInstance defineQInstance() throws QException
+   {
+      QInstance qInstance = new QInstance();
+      MetaDataProducerHelper.processAllMetaDataProducersInPackage(qInstance, getMetaDataPackageName());
+      return (qInstance);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/AbstractQQQApplication.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.instances;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QInstanceValidationException;
+import com.kingsrook.qqq.backend.core.instances.validation.plugins.QInstanceValidatorPluginInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+
+
+/*******************************************************************************
+ ** Base class to provide the definition of a QQQ-based application.
+ **
+ ** Essentially, just how to define its meta-data - in the form of a QInstance.
+ **
+ ** Also provides means to define the instance validation plugins to be used.
+ *******************************************************************************/
+public abstract class AbstractQQQApplication
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public abstract QInstance defineQInstance() throws QException;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public QInstance defineValidatedQInstance() throws QException, QInstanceValidationException
+   {
+      QInstance qInstance = defineQInstance();
+
+      QInstanceValidator.removeAllValidatorPlugins();
+      for(QInstanceValidatorPluginInterface<?> validatorPlugin : CollectionUtils.nonNullList(getValidatorPlugins()))
+      {
+         QInstanceValidator.addValidatorPlugin(validatorPlugin);
+      }
+
+      QInstanceValidator qInstanceValidator = new QInstanceValidator();
+      qInstanceValidator.validate(qInstance);
+      return (qInstance);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   protected List<QInstanceValidatorPluginInterface<?>> getValidatorPlugins()
+   {
+      return new ArrayList<>();
+   }
+}

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

@@ -58,6 +58,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QStateMachineStep;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QSupplementalProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportDataSource;
@@ -410,10 +411,27 @@ public class QInstanceEnricher
     **
     *******************************************************************************/
    private void enrichStep(QStepMetaData step)
+   {
+      enrichStep(step, false);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void enrichStep(QStepMetaData step, boolean isSubStep)
    {
       if(!StringUtils.hasContent(step.getLabel()))
       {
-         step.setLabel(nameToLabel(step.getName()));
+         if(isSubStep && (step.getName().endsWith(".backend") || step.getName().endsWith(".frontend")))
+         {
+            step.setLabel(nameToLabel(step.getName().replaceFirst("\\.(backend|frontend)", "")));
+         }
+         else
+         {
+            step.setLabel(nameToLabel(step.getName()));
+         }
       }
 
       step.getInputFields().forEach(this::enrichField);
@@ -434,6 +452,13 @@ public class QInstanceEnricher
             frontendStepMetaData.getRecordListFields().forEach(this::enrichField);
          }
       }
+      else if(step instanceof QStateMachineStep stateMachineStep)
+      {
+         for(QStepMetaData subStep : CollectionUtils.nonNullList(stateMachineStep.getSubSteps()))
+         {
+            enrichStep(subStep, true);
+         }
+      }
    }
 
 

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

@@ -43,6 +43,7 @@ import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandler
 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.MetaDataFilterInterface;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.actions.reporting.customizers.ReportCustomRecordSourceInterface;
 import com.kingsrook.qqq.backend.core.actions.scripts.TestScriptActionInterface;
@@ -74,6 +75,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppChildMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
 import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
@@ -185,6 +187,7 @@ public class QInstanceValidator
       //////////////////////////////////////////////////////////////////////////
       try
       {
+         validateInstanceAttributes(qInstance);
          validateBackends(qInstance);
          validateAuthentication(qInstance);
          validateAutomationProviders(qInstance);
@@ -225,6 +228,19 @@ public class QInstanceValidator
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void validateInstanceAttributes(QInstance qInstance)
+   {
+      if(qInstance.getMetaDataFilter() != null)
+      {
+         validateSimpleCodeReference("Instance metaDataFilter ", qInstance.getMetaDataFilter(), MetaDataFilterInterface.class);
+      }
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -928,13 +944,8 @@ public class QInstanceValidator
       assertCondition(Objects.equals(fieldName, field.getName()),
          "Inconsistent naming in table " + tableName + " for field " + fieldName + "/" + field.getName() + ".");
 
-      if(field.getPossibleValueSourceName() != null)
-      {
-         assertCondition(qInstance.getPossibleValueSource(field.getPossibleValueSourceName()) != null,
-            "Unrecognized possibleValueSourceName " + field.getPossibleValueSourceName() + " in table " + tableName + " for field " + fieldName + ".");
-      }
-
       String prefix = "Field " + fieldName + " in table " + tableName + " ";
+      validateFieldPossibleValueSourceAttributes(qInstance, field, prefix);
 
       ///////////////////////////////////////////////////
       // validate things we know about field behaviors //
@@ -1039,6 +1050,31 @@ public class QInstanceValidator
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void validateFieldPossibleValueSourceAttributes(QInstance qInstance, QFieldMetaData field, String prefix)
+   {
+      if(field.getPossibleValueSourceName() != null)
+      {
+         assertCondition(qInstance.getPossibleValueSource(field.getPossibleValueSourceName()) != null,
+            prefix + "has an unrecognized possibleValueSourceName " + field.getPossibleValueSourceName());
+
+         assertCondition(field.getInlinePossibleValueSource() == null, prefix.trim() + " has both a possibleValueSourceName and an inlinePossibleValueSource, which is not allowed.");
+      }
+
+      if(field.getInlinePossibleValueSource() != null)
+      {
+         String name = "inlinePossibleValueSource for " + prefix.trim();
+         if(assertCondition(QPossibleValueSourceType.ENUM.equals(field.getInlinePossibleValueSource().getType()), name + " must have a type of ENUM."))
+         {
+            validatePossibleValueSource(qInstance, name, field.getInlinePossibleValueSource());
+         }
+      }
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -1546,6 +1582,16 @@ public class QInstanceValidator
                }
             }
 
+            for(QFieldMetaData field : process.getInputFields())
+            {
+               validateFieldPossibleValueSourceAttributes(qInstance, field, "Process " + processName + ", input field " + field.getName());
+            }
+
+            for(QFieldMetaData field : process.getOutputFields())
+            {
+               validateFieldPossibleValueSourceAttributes(qInstance, field, "Process " + processName + ", output field " + field.getName());
+            }
+
             if(process.getCancelStep() != null)
             {
                if(assertCondition(process.getCancelStep().getCode() != null, "Cancel step is missing a code reference, in process " + processName))
@@ -1948,78 +1994,88 @@ public class QInstanceValidator
          qInstance.getPossibleValueSources().forEach((pvsName, possibleValueSource) ->
          {
             assertCondition(Objects.equals(pvsName, possibleValueSource.getName()), "Inconsistent naming for possibleValueSource: " + pvsName + "/" + possibleValueSource.getName() + ".");
-            if(assertCondition(possibleValueSource.getType() != null, "Missing type for possibleValueSource: " + pvsName))
+            validatePossibleValueSource(qInstance, pvsName, possibleValueSource);
+         });
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void validatePossibleValueSource(QInstance qInstance, String name, QPossibleValueSource possibleValueSource)
+   {
+      if(assertCondition(possibleValueSource.getType() != null, "Missing type for possibleValueSource: " + name))
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         // assert about fields that should and should not be set, based on possible value source type //
+         // do additional type-specific validations as well                                            //
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         switch(possibleValueSource.getType())
+         {
+            case ENUM ->
             {
-               ////////////////////////////////////////////////////////////////////////////////////////////////
+               assertCondition(!StringUtils.hasContent(possibleValueSource.getTableName()), "enum-type possibleValueSource " + name + " should not have a tableName.");
-               // assert about fields that should and should not be set, based on possible value source type //
+               assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "enum-type possibleValueSource " + name + " should not have searchFields.");
-               // do additional type-specific validations as well                                            //
+               assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getOrderByFields()), "enum-type possibleValueSource " + name + " should not have orderByFields.");
-               ////////////////////////////////////////////////////////////////////////////////////////////////
+               assertCondition(possibleValueSource.getCustomCodeReference() == null, "enum-type possibleValueSource " + name + " should not have a customCodeReference.");
-               switch(possibleValueSource.getType())
+
+               assertCondition(CollectionUtils.nullSafeHasContents(possibleValueSource.getEnumValues()), "enum-type possibleValueSource " + name + " is missing enum values");
+            }
+            case TABLE ->
+            {
+               assertCondition(CollectionUtils.nullSafeIsEmpty(possibleValueSource.getEnumValues()), "table-type possibleValueSource " + name + " should not have enum values.");
+               assertCondition(possibleValueSource.getCustomCodeReference() == null, "table-type possibleValueSource " + name + " should not have a customCodeReference.");
+
+               QTableMetaData tableMetaData = null;
+               if(assertCondition(StringUtils.hasContent(possibleValueSource.getTableName()), "table-type possibleValueSource " + name + " is missing a tableName."))
                {
-                  case ENUM ->
+                  tableMetaData = qInstance.getTable(possibleValueSource.getTableName());
-                  {
+                  assertCondition(tableMetaData != null, "Unrecognized table " + possibleValueSource.getTableName() + " for possibleValueSource " + name + ".");
-                     assertCondition(!StringUtils.hasContent(possibleValueSource.getTableName()), "enum-type possibleValueSource " + pvsName + " should not have a tableName.");
-                     assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "enum-type possibleValueSource " + pvsName + " should not have searchFields.");
-                     assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getOrderByFields()), "enum-type possibleValueSource " + pvsName + " should not have orderByFields.");
-                     assertCondition(possibleValueSource.getCustomCodeReference() == null, "enum-type possibleValueSource " + pvsName + " should not have a customCodeReference.");
-
-                     assertCondition(CollectionUtils.nullSafeHasContents(possibleValueSource.getEnumValues()), "enum-type possibleValueSource " + pvsName + " is missing enum values");
-                  }
-                  case TABLE ->
-                  {
-                     assertCondition(CollectionUtils.nullSafeIsEmpty(possibleValueSource.getEnumValues()), "table-type possibleValueSource " + pvsName + " should not have enum values.");
-                     assertCondition(possibleValueSource.getCustomCodeReference() == null, "table-type possibleValueSource " + pvsName + " should not have a customCodeReference.");
-
-                     QTableMetaData tableMetaData = null;
-                     if(assertCondition(StringUtils.hasContent(possibleValueSource.getTableName()), "table-type possibleValueSource " + pvsName + " is missing a tableName."))
-                     {
-                        tableMetaData = qInstance.getTable(possibleValueSource.getTableName());
-                        assertCondition(tableMetaData != null, "Unrecognized table " + possibleValueSource.getTableName() + " for possibleValueSource " + pvsName + ".");
-                     }
-
-                     if(assertCondition(CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "table-type possibleValueSource " + pvsName + " is missing searchFields."))
-                     {
-                        if(tableMetaData != null)
-                        {
-                           QTableMetaData finalTableMetaData = tableMetaData;
-                           for(String searchField : possibleValueSource.getSearchFields())
-                           {
-                              assertNoException(() -> finalTableMetaData.getField(searchField), "possibleValueSource " + pvsName + " has an unrecognized searchField: " + searchField);
-                           }
-                        }
-                     }
-
-                     if(assertCondition(CollectionUtils.nullSafeHasContents(possibleValueSource.getOrderByFields()), "table-type possibleValueSource " + pvsName + " is missing orderByFields."))
-                     {
-                        if(tableMetaData != null)
-                        {
-                           QTableMetaData finalTableMetaData = tableMetaData;
-
-                           for(QFilterOrderBy orderByField : possibleValueSource.getOrderByFields())
-                           {
-                              assertNoException(() -> finalTableMetaData.getField(orderByField.getFieldName()), "possibleValueSource " + pvsName + " has an unrecognized orderByField: " + orderByField.getFieldName());
-                           }
-                        }
-                     }
-                  }
-                  case CUSTOM ->
-                  {
-                     assertCondition(CollectionUtils.nullSafeIsEmpty(possibleValueSource.getEnumValues()), "custom-type possibleValueSource " + pvsName + " should not have enum values.");
-                     assertCondition(!StringUtils.hasContent(possibleValueSource.getTableName()), "custom-type possibleValueSource " + pvsName + " should not have a tableName.");
-                     assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "custom-type possibleValueSource " + pvsName + " should not have searchFields.");
-                     assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getOrderByFields()), "custom-type possibleValueSource " + pvsName + " should not have orderByFields.");
-
-                     if(assertCondition(possibleValueSource.getCustomCodeReference() != null, "custom-type possibleValueSource " + pvsName + " is missing a customCodeReference."))
-                     {
-                        validateSimpleCodeReference("PossibleValueSource " + pvsName + " custom code reference: ", possibleValueSource.getCustomCodeReference(), QCustomPossibleValueProvider.class);
-                     }
-                  }
-                  default -> errors.add("Unexpected possibleValueSource type: " + possibleValueSource.getType());
                }
 
-               runPlugins(QPossibleValueSource.class, possibleValueSource, qInstance);
+               if(assertCondition(CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "table-type possibleValueSource " + name + " is missing searchFields."))
+               {
+                  if(tableMetaData != null)
+                  {
+                     QTableMetaData finalTableMetaData = tableMetaData;
+                     for(String searchField : possibleValueSource.getSearchFields())
+                     {
+                        assertNoException(() -> finalTableMetaData.getField(searchField), "possibleValueSource " + name + " has an unrecognized searchField: " + searchField);
+                     }
+                  }
+               }
+
+               if(assertCondition(CollectionUtils.nullSafeHasContents(possibleValueSource.getOrderByFields()), "table-type possibleValueSource " + name + " is missing orderByFields."))
+               {
+                  if(tableMetaData != null)
+                  {
+                     QTableMetaData finalTableMetaData = tableMetaData;
+
+                     for(QFilterOrderBy orderByField : possibleValueSource.getOrderByFields())
+                     {
+                        assertNoException(() -> finalTableMetaData.getField(orderByField.getFieldName()), "possibleValueSource " + name + " has an unrecognized orderByField: " + orderByField.getFieldName());
+                     }
+                  }
+               }
             }
-         });
+            case CUSTOM ->
+            {
+               assertCondition(CollectionUtils.nullSafeIsEmpty(possibleValueSource.getEnumValues()), "custom-type possibleValueSource " + name + " should not have enum values.");
+               assertCondition(!StringUtils.hasContent(possibleValueSource.getTableName()), "custom-type possibleValueSource " + name + " should not have a tableName.");
+               assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "custom-type possibleValueSource " + name + " should not have searchFields.");
+               assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getOrderByFields()), "custom-type possibleValueSource " + name + " should not have orderByFields.");
+
+               if(assertCondition(possibleValueSource.getCustomCodeReference() != null, "custom-type possibleValueSource " + name + " is missing a customCodeReference."))
+               {
+                  validateSimpleCodeReference("PossibleValueSource " + name + " custom code reference: ", possibleValueSource.getCustomCodeReference(), QCustomPossibleValueProvider.class);
+               }
+            }
+            default -> errors.add("Unexpected possibleValueSource type: " + possibleValueSource.getType());
+         }
+
+         runPlugins(QPossibleValueSource.class, possibleValueSource, qInstance);
       }
    }
 

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

@@ -31,6 +31,16 @@ import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
  *******************************************************************************/
 public class MetaDataInput extends AbstractActionInput
 {
+   private String frontendName;
+   private String frontendVersion;
+
+   private String middlewareName;
+   private String middlewareVersion;
+
+   private String applicationName;
+   private String applicationVersion;
+
+
 
    /*******************************************************************************
     **
@@ -39,4 +49,190 @@ public class MetaDataInput extends AbstractActionInput
    {
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for frontendName
+    *******************************************************************************/
+   public String getFrontendName()
+   {
+      return (this.frontendName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for frontendName
+    *******************************************************************************/
+   public void setFrontendName(String frontendName)
+   {
+      this.frontendName = frontendName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for frontendName
+    *******************************************************************************/
+   public MetaDataInput withFrontendName(String frontendName)
+   {
+      this.frontendName = frontendName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for frontendVersion
+    *******************************************************************************/
+   public String getFrontendVersion()
+   {
+      return (this.frontendVersion);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for frontendVersion
+    *******************************************************************************/
+   public void setFrontendVersion(String frontendVersion)
+   {
+      this.frontendVersion = frontendVersion;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for frontendVersion
+    *******************************************************************************/
+   public MetaDataInput withFrontendVersion(String frontendVersion)
+   {
+      this.frontendVersion = frontendVersion;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for middlewareName
+    *******************************************************************************/
+   public String getMiddlewareName()
+   {
+      return (this.middlewareName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for middlewareName
+    *******************************************************************************/
+   public void setMiddlewareName(String middlewareName)
+   {
+      this.middlewareName = middlewareName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for middlewareName
+    *******************************************************************************/
+   public MetaDataInput withMiddlewareName(String middlewareName)
+   {
+      this.middlewareName = middlewareName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for middlewareVersion
+    *******************************************************************************/
+   public String getMiddlewareVersion()
+   {
+      return (this.middlewareVersion);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for middlewareVersion
+    *******************************************************************************/
+   public void setMiddlewareVersion(String middlewareVersion)
+   {
+      this.middlewareVersion = middlewareVersion;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for middlewareVersion
+    *******************************************************************************/
+   public MetaDataInput withMiddlewareVersion(String middlewareVersion)
+   {
+      this.middlewareVersion = middlewareVersion;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for applicationName
+    *******************************************************************************/
+   public String getApplicationName()
+   {
+      return (this.applicationName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for applicationName
+    *******************************************************************************/
+   public void setApplicationName(String applicationName)
+   {
+      this.applicationName = applicationName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for applicationName
+    *******************************************************************************/
+   public MetaDataInput withApplicationName(String applicationName)
+   {
+      this.applicationName = applicationName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for applicationVersion
+    *******************************************************************************/
+   public String getApplicationVersion()
+   {
+      return (this.applicationVersion);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for applicationVersion
+    *******************************************************************************/
+   public void setApplicationVersion(String applicationVersion)
+   {
+      this.applicationVersion = applicationVersion;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for applicationVersion
+    *******************************************************************************/
+   public MetaDataInput withApplicationVersion(String applicationVersion)
+   {
+      this.applicationVersion = applicationVersion;
+      return (this);
+   }
+
 }

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

@@ -0,0 +1,139 @@
+/*
+ * 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.model.actions.processes;
+
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Object that stores adjustments that a process wants to make, at run-time,
+ ** to its meta-data.
+ **
+ ** e.g., changing the steps; updating fields (e.g., changing an inline PVS,
+ ** or an isRequired attribute)
+ *******************************************************************************/
+public class ProcessMetaDataAdjustment
+{
+   private static final QLogger LOG = QLogger.getLogger(ProcessMetaDataAdjustment.class);
+
+   private List<QFrontendStepMetaData> updatedFrontendStepList = null;
+   private Map<String, QFieldMetaData> updatedFields           = null;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public ProcessMetaDataAdjustment withUpdatedField(QFieldMetaData field)
+   {
+      if(updatedFields == null)
+      {
+         updatedFields = new LinkedHashMap<>();
+      }
+
+      if(!StringUtils.hasContent(field.getName()))
+      {
+         LOG.warn("Missing name on field in withUpdatedField - no update will happen.");
+      }
+      else
+      {
+         if(updatedFields.containsKey(field.getName()))
+         {
+            LOG.info("UpdatedFields map already contained a field with this name - overwriting it.", logPair("fieldName", field.getName()));
+         }
+
+         updatedFields.put(field.getName(), field);
+      }
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for updatedFrontendStepList
+    *******************************************************************************/
+   public List<QFrontendStepMetaData> getUpdatedFrontendStepList()
+   {
+      return (this.updatedFrontendStepList);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updatedFrontendStepList
+    *******************************************************************************/
+   public void setUpdatedFrontendStepList(List<QFrontendStepMetaData> updatedFrontendStepList)
+   {
+      this.updatedFrontendStepList = updatedFrontendStepList;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for updatedFrontendStepList
+    *******************************************************************************/
+   public ProcessMetaDataAdjustment withUpdatedFrontendStepList(List<QFrontendStepMetaData> updatedFrontendStepList)
+   {
+      this.updatedFrontendStepList = updatedFrontendStepList;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for updatedFields
+    *******************************************************************************/
+   public Map<String, QFieldMetaData> getUpdatedFields()
+   {
+      return (this.updatedFields);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updatedFields
+    *******************************************************************************/
+   public void setUpdatedFields(Map<String, QFieldMetaData> updatedFields)
+   {
+      this.updatedFields = updatedFields;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for updatedFields
+    *******************************************************************************/
+   public ProcessMetaDataAdjustment withUpdatedFields(Map<String, QFieldMetaData> updatedFields)
+   {
+      this.updatedFields = updatedFields;
+      return (this);
+   }
+
+}

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

@@ -29,7 +29,6 @@ import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
-import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
 
 
 /*******************************************************************************
@@ -42,10 +41,7 @@ public class ProcessState implements Serializable
    private List<String>              stepList     = new ArrayList<>();
    private Optional<String>          nextStepName = Optional.empty();
 
-   /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   private ProcessMetaDataAdjustment processMetaDataAdjustment = null;
-   // maybe, remove this altogether - just let the frontend compute & send if needed... but how does it know last version...? //
-   /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-   private List<QFrontendStepMetaData> updatedFrontendStepList = null;
 
 
 
@@ -148,33 +144,36 @@ public class ProcessState implements Serializable
 
 
 
+
+
    /*******************************************************************************
-    ** Getter for updatedFrontendStepList
+    ** Getter for processMetaDataAdjustment
     *******************************************************************************/
-   public List<QFrontendStepMetaData> getUpdatedFrontendStepList()
+   public ProcessMetaDataAdjustment getProcessMetaDataAdjustment()
    {
-      return (this.updatedFrontendStepList);
+      return (this.processMetaDataAdjustment);
    }
 
 
 
    /*******************************************************************************
-    ** Setter for updatedFrontendStepList
+    ** Setter for processMetaDataAdjustment
     *******************************************************************************/
-   public void setUpdatedFrontendStepList(List<QFrontendStepMetaData> updatedFrontendStepList)
+   public void setProcessMetaDataAdjustment(ProcessMetaDataAdjustment processMetaDataAdjustment)
    {
-      this.updatedFrontendStepList = updatedFrontendStepList;
+      this.processMetaDataAdjustment = processMetaDataAdjustment;
    }
 
 
 
    /*******************************************************************************
-    ** Fluent setter for updatedFrontendStepList
+    ** Fluent setter for processMetaDataAdjustment
     *******************************************************************************/
-   public ProcessState withUpdatedFrontendStepList(List<QFrontendStepMetaData> updatedFrontendStepList)
+   public ProcessState withProcessMetaDataAdjustment(ProcessMetaDataAdjustment processMetaDataAdjustment)
    {
-      this.updatedFrontendStepList = updatedFrontendStepList;
+      this.processMetaDataAdjustment = processMetaDataAdjustment;
       return (this);
    }
 
+
 }

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

@@ -374,7 +374,13 @@ public class RunBackendStepOutput extends AbstractActionOutput implements Serial
          .map(step -> (QFrontendStepMetaData) step)
          .toList());
 
-      setUpdatedFrontendStepList(updatedFrontendStepList);
+      ProcessMetaDataAdjustment processMetaDataAdjustment = getProcessMetaDataAdjustment();
+      if(processMetaDataAdjustment == null)
+      {
+         processMetaDataAdjustment = new ProcessMetaDataAdjustment();
+      }
+      processMetaDataAdjustment.setUpdatedFrontendStepList(updatedFrontendStepList);
+      setProcessMetaDataAdjustment(processMetaDataAdjustment);
    }
 
 
@@ -411,21 +417,21 @@ public class RunBackendStepOutput extends AbstractActionOutput implements Serial
 
 
    /*******************************************************************************
-    ** Getter for updatedFrontendStepList
+    ** Getter for ProcessMetaDataAdjustment (pass-through to processState)
     *******************************************************************************/
-   public List<QFrontendStepMetaData> getUpdatedFrontendStepList()
+   public ProcessMetaDataAdjustment getProcessMetaDataAdjustment()
    {
-      return (this.processState.getUpdatedFrontendStepList());
+      return (this.processState.getProcessMetaDataAdjustment());
    }
 
 
 
    /*******************************************************************************
-    ** Setter for updatedFrontendStepList
+    ** Setter for updatedFrontendStepList (pass-through to processState)
     *******************************************************************************/
-   public void setUpdatedFrontendStepList(List<QFrontendStepMetaData> updatedFrontendStepList)
+   public void setProcessMetaDataAdjustment(ProcessMetaDataAdjustment processMetaDataAdjustment)
    {
-      this.processState.setUpdatedFrontendStepList(updatedFrontendStepList);
+      this.processState.setProcessMetaDataAdjustment(processMetaDataAdjustment);
    }
 
 }

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

@@ -33,6 +33,7 @@ import java.util.Optional;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.utils.ObjectUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 
 
@@ -336,7 +337,12 @@ public class RunProcessOutput extends AbstractActionOutput implements Serializab
     *******************************************************************************/
    public void setUpdatedFrontendStepList(List<QFrontendStepMetaData> updatedFrontendStepList)
    {
-      this.processState.setUpdatedFrontendStepList(updatedFrontendStepList);
+      if(this.processState.getProcessMetaDataAdjustment() == null)
+      {
+         this.processState.setProcessMetaDataAdjustment(new ProcessMetaDataAdjustment());
+      }
+
+      this.processState.getProcessMetaDataAdjustment().setUpdatedFrontendStepList(updatedFrontendStepList);
    }
 
 
@@ -346,7 +352,27 @@ public class RunProcessOutput extends AbstractActionOutput implements Serializab
     *******************************************************************************/
    public List<QFrontendStepMetaData> getUpdatedFrontendStepList()
    {
-      return this.processState.getUpdatedFrontendStepList();
+      return ObjectUtils.tryElse(() -> this.processState.getProcessMetaDataAdjustment().getUpdatedFrontendStepList(), null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for processMetaDataAdjustment
+    *******************************************************************************/
+   public ProcessMetaDataAdjustment getProcessMetaDataAdjustment()
+   {
+      return (this.processState.getProcessMetaDataAdjustment());
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for processMetaDataAdjustment
+    *******************************************************************************/
+   public void setProcessMetaDataAdjustment(ProcessMetaDataAdjustment processMetaDataAdjustment)
+   {
+      this.processState.setProcessMetaDataAdjustment(processMetaDataAdjustment);
    }
 
 }

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

@@ -0,0 +1,66 @@
+/*
+ * 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.model.actions.tables.query;
+
+
+/***************************************************************************
+ ** Possible behaviors for doing interpretValues on a filter, and a criteria
+ ** has a variable value (either as a string-that-looks-like-a-variable,
+ ** as in ${input.foreignId} for a PVS filter, or a FilterVariableExpression),
+ ** and a value for that variable isn't available.
+ **
+ ** Used in conjunction with FilterUseCase and its implementations, e.g.,
+ ** PossibleValueSearchFilterUseCase.
+ ***************************************************************************/
+public enum CriteriaMissingInputValueBehavior
+{
+   //////////////////////////////////////////////////////////////////////
+   // this was the original behavior, before we added this enum.  but, //
+   // it doesn't ever seem entirely valid, and isn't currently used.   //
+   //////////////////////////////////////////////////////////////////////
+   INTERPRET_AS_NULL_VALUE,
+
+   //////////////////////////////////////////////////////////////////////////
+   // make the criteria behave as though it's not in the filter at all.    //
+   // effectively by changing its operator to TRUE, so it always matches.  //
+   // original intended use is for possible-values on  query screens,      //
+   // where a foreign-id isn't present, so we want to show all PV options. //
+   //////////////////////////////////////////////////////////////////////////
+   REMOVE_FROM_FILTER,
+
+   //////////////////////////////////////////////////////////////////////////////////////
+   // make the criteria such that it makes no rows ever match.                         //
+   // e.g., changes it to a FALSE.  I suppose, within an OR, that might                //
+   // not be powerful enough...  but, it solves the immediate use-case in              //
+   // front of us, which is forms, where a PV field should show no values              //
+   // until a foreign key field has a value.                                           //
+   // Note that this use-case used to have the same end-effect by such                 //
+   // variables being interpreted as nulls - but this approach feels more intentional. //
+   //////////////////////////////////////////////////////////////////////////////////////
+   MAKE_NO_MATCHES,
+
+   ///////////////////////////////////////////////////////////////////////////////////////////
+   // throw an exception if a value isn't available.  This is the overall default,          //
+   // and originally was what we did for FilterVariableExpressions, e.g., for saved reports //
+   ///////////////////////////////////////////////////////////////////////////////////////////
+   THROW_EXCEPTION
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/actions/tables/query/FilterUseCase.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.model.actions.tables.query;
+
+
+/*******************************************************************************
+ ** Interface where we can associate behaviors with various use cases for
+ ** QQueryFilters - the original being, how to handle (in the interpretValues
+ ** method) how to handle missing input values.
+ **
+ ** Includes a default implementation, with a default behavior - which is to
+ ** throw an exception upon missing criteria variable values.
+ *******************************************************************************/
+public interface FilterUseCase
+{
+   FilterUseCase DEFAULT = new DefaultFilterUseCase();
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior();
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   class DefaultFilterUseCase implements FilterUseCase
+   {
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      @Override
+      public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+      {
+         return CriteriaMissingInputValueBehavior.THROW_EXCEPTION;
+      }
+   }
+}

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

@@ -82,7 +82,7 @@ public class JoinsContext
    /////////////////////////////////////////////////////////////////////////////
    // we will get a TON of more output if this gets turned up, so be cautious //
    /////////////////////////////////////////////////////////////////////////////
-   private Level logLevel = Level.OFF;
+   private Level logLevel          = Level.OFF;
    private Level logLevelForFilter = Level.OFF;
 
 
@@ -404,6 +404,12 @@ public class JoinsContext
                chainIsInner = false;
             }
 
+            if(hasAllAccessKey(recordSecurityLock))
+            {
+               queryJoin.withType(QueryJoin.Type.LEFT);
+               chainIsInner = false;
+            }
+
             addQueryJoin(queryJoin, "forRecordSecurityLock (non-flipped)", "- ");
             addedQueryJoins.add(queryJoin);
             tmpTable = instance.getTable(join.getRightTable());
@@ -423,6 +429,12 @@ public class JoinsContext
                chainIsInner = false;
             }
 
+            if(hasAllAccessKey(recordSecurityLock))
+            {
+               queryJoin.withType(QueryJoin.Type.LEFT);
+               chainIsInner = false;
+            }
+
             addQueryJoin(queryJoin, "forRecordSecurityLock (flipped)", "- ");
             addedQueryJoins.add(queryJoin);
             tmpTable = instance.getTable(join.getLeftTable());
@@ -456,44 +468,53 @@ public class JoinsContext
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private boolean hasAllAccessKey(RecordSecurityLock recordSecurityLock)
+   {
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // check if the key type has an all-access key, and if so, if it's set to true for the current user/session //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      QSecurityKeyType securityKeyType = instance.getSecurityKeyType(recordSecurityLock.getSecurityKeyType());
+      if(StringUtils.hasContent(securityKeyType.getAllAccessKeyName()))
+      {
+         QSession session = QContext.getQSession();
+         if(session.hasSecurityKeyValue(securityKeyType.getAllAccessKeyName(), true, QFieldType.BOOLEAN))
+         {
+            return (true);
+         }
+      }
+
+      return (false);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
    private void addSubFilterForRecordSecurityLock(RecordSecurityLock recordSecurityLock, QTableMetaData table, String tableNameOrAlias, boolean isOuter, QueryJoin sourceQueryJoin)
    {
-      QSession session = QContext.getQSession();
+      boolean haveAllAccessKey = hasAllAccessKey(recordSecurityLock);
-
+      if(haveAllAccessKey)
-      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
-      // check if the key type has an all-access key, and if so, if it's set to true for the current user/session //
-      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
-      QSecurityKeyType securityKeyType  = instance.getSecurityKeyType(recordSecurityLock.getSecurityKeyType());
-      boolean          haveAllAccessKey = false;
-      if(StringUtils.hasContent(securityKeyType.getAllAccessKeyName()))
       {
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         if(sourceQueryJoin != null)
-         // if we have all-access on this key, then we don't need a criterion for it (as long as we're in an AND filter) //
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-         if(session.hasSecurityKeyValue(securityKeyType.getAllAccessKeyName(), true, QFieldType.BOOLEAN))
          {
-            haveAllAccessKey = true;
+            ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            // in case the queryJoin object is re-used between queries, and its security criteria need to be different (!!), reset it //
+            // this can be exposed in tests - maybe not entirely expected in real-world, but seems safe enough                        //
+            ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            sourceQueryJoin.withSecurityCriteria(new ArrayList<>());
+         }
 
-            if(sourceQueryJoin != null)
+         ////////////////////////////////////////////////////////////////////////////////////////
-            {
+         // if we're in an AND filter, then we don't need a criteria for this lock, so return. //
-               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         ////////////////////////////////////////////////////////////////////////////////////////
-               // in case the queryJoin object is re-used between queries, and its security criteria need to be different (!!), reset it //
+         boolean inAnAndFilter = securityFilterCursor.getBooleanOperator() == QQueryFilter.BooleanOperator.AND;
-               // this can be exposed in tests - maybe not entirely expected in real-world, but seems safe enough                        //
+         if(inAnAndFilter)
-               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         {
-               sourceQueryJoin.withSecurityCriteria(new ArrayList<>());
+            return;
-            }
-
-            ////////////////////////////////////////////////////////////////////////////////////////
-            // if we're in an AND filter, then we don't need a criteria for this lock, so return. //
-            ////////////////////////////////////////////////////////////////////////////////////////
-            boolean inAnAndFilter = securityFilterCursor.getBooleanOperator() == QQueryFilter.BooleanOperator.AND;
-            if(inAnAndFilter)
-            {
-               return;
-            }
          }
       }
 
@@ -545,7 +566,7 @@ public class JoinsContext
       }
       else
       {
-         List<Serializable> securityKeyValues = session.getSecurityKeyValues(recordSecurityLock.getSecurityKeyType(), type);
+         List<Serializable> securityKeyValues = QContext.getQSession().getSecurityKeyValues(recordSecurityLock.getSecurityKeyType(), type);
          if(CollectionUtils.nullSafeIsEmpty(securityKeyValues))
          {
             ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

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

@@ -528,8 +528,27 @@ public class QQueryFilter implements Serializable, Cloneable
     ** Note - it may be very important that you call this method on a clone of a
     ** QQueryFilter - e.g., if it's one that defined in metaData, and that we don't
     ** want to be (permanently) changed!!
-    *******************************************************************************/
+    **
+    ** This overload does not take in a FilterUseCase - it uses FilterUseCase.DEFAULT
+    ******************************************************************************/
    public void interpretValues(Map<String, Serializable> inputValues) throws QException
+   {
+      interpretValues(inputValues, FilterUseCase.DEFAULT);
+   }
+
+
+
+   /*******************************************************************************
+    ** Replace any criteria values that look like ${input.XXX} with the value of XXX
+    ** from the supplied inputValues map - where the handling of missing values
+    ** is specified in the inputted FilterUseCase parameter
+    **
+    ** Note - it may be very important that you call this method on a clone of a
+    ** QQueryFilter - e.g., if it's one that defined in metaData, and that we don't
+    ** want to be (permanently) changed!!
+    **
+    *******************************************************************************/
+   public void interpretValues(Map<String, Serializable> inputValues, FilterUseCase useCase) throws QException
    {
       List<Exception> caughtExceptions = new ArrayList<>();
 
@@ -545,6 +564,9 @@ public class QQueryFilter implements Serializable, Cloneable
             {
                try
                {
+                  Serializable interpretedValue = value;
+                  Exception    caughtException  = null;
+
                   if(value instanceof AbstractFilterExpression<?>)
                   {
                      ///////////////////////////////////////////////////////////////////////
@@ -553,17 +575,54 @@ public class QQueryFilter implements Serializable, Cloneable
                      ///////////////////////////////////////////////////////////////////////
                      if(value instanceof FilterVariableExpression filterVariableExpression)
                      {
-                        newValues.add(filterVariableExpression.evaluateInputValues(inputValues));
+                        try
-                     }
+                        {
-                     else
+                           interpretedValue = filterVariableExpression.evaluateInputValues(inputValues);
-                     {
+                        }
-                        newValues.add(value);
+                        catch(Exception e)
+                        {
+                           caughtException = e;
+                           interpretedValue = InputNotFound.instance;
+                        }
+                     }
+                  }
+                  else
+                  {
+                     /////////////////////////////////////////////////////////////////////////////////////////////////////////
+                     // for non-expressions, cast the value to a string, and see if it can be resolved a variable.          //
+                     // there are 3 possible cases here:                                                                    //
+                     // 1: it doesn't look like a variable, so it just comes back as a string version of whatever went in.  //
+                     // 2: it was resolved from a variable to a value, e.g., ${input.someVar} => someValue                  //
+                     // 3: it looked like a variable, but no value for that variable was present in the interpreter's value //
+                     // map - so we'll get back the InputNotFound.instance.                                                 //
+                     /////////////////////////////////////////////////////////////////////////////////////////////////////////
+                     String valueAsString = ValueUtils.getValueAsString(value);
+                     interpretedValue = variableInterpreter.interpretForObject(valueAsString, InputNotFound.instance);
+                  }
+
+                  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+                  // if interpreting a value returned the not-found value, or an empty string,                                            //
+                  // then decide how to handle the missing value, based on the use-case input                                             //
+                  // Note: questionable, using "" here, but that's what reality is passing a lot for cases we want to treat as missing... //
+                  //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+                  if(interpretedValue == InputNotFound.instance || "".equals(interpretedValue))
+                  {
+                     CriteriaMissingInputValueBehavior missingInputValueBehavior = getMissingInputValueBehavior(useCase);
+
+                     switch(missingInputValueBehavior)
+                     {
+                        case REMOVE_FROM_FILTER -> criterion.setOperator(QCriteriaOperator.TRUE);
+                        case MAKE_NO_MATCHES -> criterion.setOperator(QCriteriaOperator.FALSE);
+                        case INTERPRET_AS_NULL_VALUE -> newValues.add(null);
+
+                        /////////////////////////////////////////////////
+                        // handle case in the default: THROW_EXCEPTION //
+                        /////////////////////////////////////////////////
+                        default -> throw (Objects.requireNonNullElseGet(caughtException, () -> new QUserFacingException("Missing value for criteria on field: " + criterion.getFieldName())));
                      }
                   }
                   else
                   {
-                     String       valueAsString    = ValueUtils.getValueAsString(value);
-                     Serializable interpretedValue = variableInterpreter.interpretForObject(valueAsString);
                      newValues.add(interpretedValue);
                   }
                }
@@ -586,6 +645,44 @@ public class QQueryFilter implements Serializable, Cloneable
 
 
 
+   /***************************************************************************
+    ** Note:  in the original build of this, it felt like we *might* want to be
+    ** able to specify these behaviors at the individual criteria level, where
+    ** the implementation would be to add to QFilterCriteria:
+    ** - Map<FilterUseCase, CriteriaMissingInputValueBehavior> missingInputValueBehaviors;
+    ** - CriteriaMissingInputValueBehavior getMissingInputValueBehaviorForUseCase(FilterUseCase useCase) {}
+    *
+    ** (and maybe do that in a sub-class of QFilterCriteria, so it isn't always
+    ** there?  idk...) and then here we'd call:
+    ** - CriteriaMissingInputValueBehavior missingInputValueBehavior = criterion.getMissingInputValueBehaviorForUseCase(useCase);
+    *
+    ** But, we don't actually have that use-case at hand now, so - let's keep it
+    ** just at the level we need for now.
+    **
+    ***************************************************************************/
+   private CriteriaMissingInputValueBehavior getMissingInputValueBehavior(FilterUseCase useCase)
+   {
+      if(useCase == null)
+      {
+         useCase = FilterUseCase.DEFAULT;
+      }
+
+      CriteriaMissingInputValueBehavior missingInputValueBehavior = useCase.getDefaultCriteriaMissingInputValueBehavior();
+      if(missingInputValueBehavior == null)
+      {
+         missingInputValueBehavior = useCase.getDefaultCriteriaMissingInputValueBehavior();
+      }
+
+      if(missingInputValueBehavior == null)
+      {
+         missingInputValueBehavior = FilterUseCase.DEFAULT.getDefaultCriteriaMissingInputValueBehavior();
+      }
+
+      return (missingInputValueBehavior);
+   }
+
+
+
    /*******************************************************************************
     ** Getter for skip
     *******************************************************************************/
@@ -678,4 +775,28 @@ public class QQueryFilter implements Serializable, Cloneable
    {
       return Objects.hash(criteria, orderBys, booleanOperator, subFilters, skip, limit);
    }
+
+
+
+   /***************************************************************************
+    ** "Token" object to be used as the defaultIfLooksLikeVariableButNotFound
+    ** parameter to variableInterpreter.interpretForObject, so we can be
+    ** very clear that we got this default back (e.g., instead of a null,
+    ** which could maybe mean something else?)
+    ***************************************************************************/
+   private static final class InputNotFound implements Serializable
+   {
+      private static InputNotFound instance = new InputNotFound();
+
+
+
+      /*******************************************************************************
+       ** private singleton constructor
+       *******************************************************************************/
+      private InputNotFound()
+      {
+
+      }
+   }
+
 }

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

@@ -25,6 +25,7 @@ package com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions;
 import java.io.Serializable;
 import java.util.Map;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 
 
 /*******************************************************************************
@@ -35,7 +36,7 @@ public abstract class AbstractFilterExpression<T extends Serializable> implement
    /*******************************************************************************
     **
     *******************************************************************************/
-   public abstract T evaluate() throws QException;
+   public abstract T evaluate(QFieldMetaData field) throws QException;
 
 
 
@@ -47,7 +48,7 @@ public abstract class AbstractFilterExpression<T extends Serializable> implement
     *******************************************************************************/
    public T evaluateInputValues(Map<String, Serializable> inputValues) throws QException
    {
-      return evaluate();
+      return evaluate(null);
    }
 
 

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

@@ -26,6 +26,7 @@ import java.io.Serializable;
 import java.util.Map;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 
 
@@ -45,7 +46,7 @@ public class FilterVariableExpression extends AbstractFilterExpression<Serializa
     **
     *******************************************************************************/
    @Override
-   public Serializable evaluate() throws QException
+   public Serializable evaluate(QFieldMetaData field) throws QException
    {
       throw (new QUserFacingException("Missing variable value."));
    }

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

@@ -22,23 +22,42 @@
 package com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions;
 
 
+import java.io.Serializable;
 import java.time.Instant;
+import java.time.ZoneId;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+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.utils.ValueUtils;
 
 
 /*******************************************************************************
  **
  *******************************************************************************/
-public class Now extends AbstractFilterExpression<Instant>
+public class Now extends AbstractFilterExpression<Serializable>
 {
 
    /*******************************************************************************
     **
     *******************************************************************************/
    @Override
-   public Instant evaluate() throws QException
+   public Serializable evaluate(QFieldMetaData field) throws QException
    {
-      return (Instant.now());
+      QFieldType type = field == null ? QFieldType.DATE_TIME : field.getType();
+
+      if(type.equals(QFieldType.DATE_TIME))
+      {
+         return (Instant.now());
+      }
+      else if(type.equals(QFieldType.DATE))
+      {
+         ZoneId zoneId = ValueUtils.getSessionOrInstanceZoneId();
+         return (Instant.now().atZone(zoneId).toLocalDate());
+      }
+      else
+      {
+         throw (new QException("Unsupported field type [" + type + "]"));
+      }
    }
 
 }

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

@@ -22,19 +22,24 @@
 package com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions;
 
 
+import java.io.Serializable;
 import java.time.Instant;
+import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.ZoneId;
 import java.time.ZoneOffset;
 import java.time.temporal.ChronoUnit;
 import java.util.concurrent.TimeUnit;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+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.utils.ValueUtils;
 
 
 /*******************************************************************************
  **
  *******************************************************************************/
-public class NowWithOffset extends AbstractFilterExpression<Instant>
+public class NowWithOffset extends AbstractFilterExpression<Serializable>
 {
    private Operator   operator;
    private int        amount;
@@ -123,7 +128,30 @@ public class NowWithOffset extends AbstractFilterExpression<Instant>
     **
     *******************************************************************************/
    @Override
-   public Instant evaluate() throws QException
+   public Serializable evaluate(QFieldMetaData field) throws QException
+   {
+      QFieldType type = field == null ? QFieldType.DATE_TIME : field.getType();
+
+      if(type.equals(QFieldType.DATE_TIME))
+      {
+         return (evaluateForDateTime());
+      }
+      else if(type.equals(QFieldType.DATE))
+      {
+         return (evaluateForDate());
+      }
+      else
+      {
+         throw (new QException("Unsupported field type [" + type + "]"));
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private Instant evaluateForDateTime()
    {
       /////////////////////////////////////////////////////////////////////////////
       // Instant doesn't let us plus/minus WEEK, MONTH, or YEAR...               //
@@ -147,6 +175,26 @@ public class NowWithOffset extends AbstractFilterExpression<Instant>
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private LocalDate evaluateForDate()
+   {
+      ZoneId    zoneId = ValueUtils.getSessionOrInstanceZoneId();
+      LocalDate now    = Instant.now().atZone(zoneId).toLocalDate();
+
+      if(operator.equals(Operator.PLUS))
+      {
+         return (now.plus(amount, timeUnit));
+      }
+      else
+      {
+         return (now.minus(amount, timeUnit));
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Getter for operator
     **

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

@@ -22,27 +22,32 @@
 package com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions;
 
 
+import java.io.Serializable;
 import java.time.DayOfWeek;
 import java.time.Instant;
+import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.ZoneId;
 import java.time.temporal.ChronoField;
 import java.time.temporal.ChronoUnit;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QRuntimeException;
+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.utils.ValueUtils;
 
 
 /*******************************************************************************
  **
  *******************************************************************************/
-public class ThisOrLastPeriod extends AbstractFilterExpression<Instant>
+public class ThisOrLastPeriod extends AbstractFilterExpression<Serializable>
 {
    private Operator   operator;
    private ChronoUnit timeUnit;
 
 
 
+
    /***************************************************************************
     **
     ***************************************************************************/
@@ -88,7 +93,7 @@ public class ThisOrLastPeriod extends AbstractFilterExpression<Instant>
     ** Factory
     **
     *******************************************************************************/
-   public static ThisOrLastPeriod last(int amount, ChronoUnit timeUnit)
+   public static ThisOrLastPeriod last(ChronoUnit timeUnit)
    {
       return (new ThisOrLastPeriod(Operator.LAST, timeUnit));
    }
@@ -99,7 +104,31 @@ public class ThisOrLastPeriod extends AbstractFilterExpression<Instant>
     **
     *******************************************************************************/
    @Override
-   public Instant evaluate() throws QException
+   public Serializable evaluate(QFieldMetaData field) throws QException
+   {
+      QFieldType type = field == null ? QFieldType.DATE_TIME : field.getType();
+
+      if(type.equals(QFieldType.DATE_TIME))
+      {
+         return (evaluateForDateTime());
+      }
+      else if(type.equals(QFieldType.DATE))
+      {
+         // return (evaluateForDateTime());
+         return (evaluateForDate());
+      }
+      else
+      {
+         throw (new QException("Unsupported field type [" + type + "]"));
+      }
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private Instant evaluateForDateTime()
    {
       ZoneId zoneId = ValueUtils.getSessionOrInstanceZoneId();
 
@@ -154,7 +183,57 @@ public class ThisOrLastPeriod extends AbstractFilterExpression<Instant>
 
             return operator.equals(Operator.THIS) ? startOfThisYear : startOfLastYear;
          }
-         default -> throw (new QRuntimeException("Unsupported timeUnit: " + timeUnit));
+         default -> throw (new QRuntimeException("Unsupported unit: " + timeUnit));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public LocalDate evaluateForDate()
+   {
+      ZoneId    zoneId = ValueUtils.getSessionOrInstanceZoneId();
+      LocalDate today  = Instant.now().atZone(zoneId).toLocalDate();
+
+      switch(timeUnit)
+      {
+         case DAYS ->
+         {
+            return operator.equals(Operator.THIS) ? today : today.minusDays(1);
+         }
+         case WEEKS ->
+         {
+            LocalDate startOfThisWeek = today;
+            while(startOfThisWeek.get(ChronoField.DAY_OF_WEEK) != DayOfWeek.SUNDAY.getValue())
+            {
+               ////////////////////////////////////////
+               // go backwards until sunday is found //
+               ////////////////////////////////////////
+               startOfThisWeek = startOfThisWeek.minusDays(1);
+            }
+            return operator.equals(Operator.THIS) ? startOfThisWeek : startOfThisWeek.minusDays(7);
+         }
+         case MONTHS ->
+         {
+            Instant       startOfThisMonth    = ValueUtils.getStartOfMonthInZoneId(zoneId.getId());
+            LocalDateTime startOfThisMonthLDT = LocalDateTime.ofInstant(startOfThisMonth, ZoneId.of(zoneId.getId()));
+            LocalDateTime startOfLastMonthLDT = startOfThisMonthLDT.minusMonths(1);
+            Instant       startOfLastMonth    = startOfLastMonthLDT.toInstant(ZoneId.of(zoneId.getId()).getRules().getOffset(Instant.now()));
+
+            return (operator.equals(Operator.THIS) ? startOfThisMonth : startOfLastMonth).atZone(zoneId).toLocalDate();
+         }
+         case YEARS ->
+         {
+            Instant       startOfThisYear    = ValueUtils.getStartOfYearInZoneId(zoneId.getId());
+            LocalDateTime startOfThisYearLDT = LocalDateTime.ofInstant(startOfThisYear, zoneId);
+            LocalDateTime startOfLastYearLDT = startOfThisYearLDT.minusYears(1);
+            Instant       startOfLastYear    = startOfLastYearLDT.toInstant(zoneId.getRules().getOffset(Instant.now()));
+
+            return (operator.equals(Operator.THIS) ? startOfThisYear : startOfLastYear).atZone(zoneId).toLocalDate();
+         }
+         default -> throw (new QRuntimeException("Unsupported unit: " + timeUnit));
       }
    }
 

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

@@ -31,6 +31,7 @@ import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
 public class StorageInput extends AbstractTableActionInput
 {
    private String reference;
+   private String contentType;
 
 
 
@@ -74,4 +75,35 @@ public class StorageInput extends AbstractTableActionInput
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for contentType
+    *******************************************************************************/
+   public String getContentType()
+   {
+      return (this.contentType);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for contentType
+    *******************************************************************************/
+   public void setContentType(String contentType)
+   {
+      this.contentType = contentType;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for contentType
+    *******************************************************************************/
+   public StorageInput withContentType(String contentType)
+   {
+      this.contentType = contentType;
+      return (this);
+   }
+
 }

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

@@ -220,7 +220,7 @@ public class AuditsMetaDataProvider
          .withRecordLabelFormat("%s %s")
          .withRecordLabelFields("auditTableId", "recordId")
          .withPrimaryKeyField("id")
-         .withField(new QFieldMetaData("id", QFieldType.INTEGER))
+         .withField(new QFieldMetaData("id", QFieldType.LONG))
          .withField(new QFieldMetaData("auditTableId", QFieldType.INTEGER).withPossibleValueSourceName(TABLE_NAME_AUDIT_TABLE))
          .withField(new QFieldMetaData("auditUserId", QFieldType.INTEGER).withPossibleValueSourceName(TABLE_NAME_AUDIT_USER))
          .withField(new QFieldMetaData("recordId", QFieldType.INTEGER))
@@ -243,8 +243,8 @@ public class AuditsMetaDataProvider
          .withRecordLabelFormat("%s")
          .withRecordLabelFields("id")
          .withPrimaryKeyField("id")
-         .withField(new QFieldMetaData("id", QFieldType.INTEGER))
+         .withField(new QFieldMetaData("id", QFieldType.LONG))
-         .withField(new QFieldMetaData("auditId", QFieldType.INTEGER).withPossibleValueSourceName(TABLE_NAME_AUDIT))
+         .withField(new QFieldMetaData("auditId", QFieldType.LONG).withPossibleValueSourceName(TABLE_NAME_AUDIT))
          .withField(new QFieldMetaData("message", QFieldType.STRING).withMaxLength(250).withBehavior(ValueTooLongBehavior.TRUNCATE_ELLIPSIS))
          .withField(new QFieldMetaData("fieldName", QFieldType.STRING).withMaxLength(100).withBehavior(ValueTooLongBehavior.TRUNCATE_ELLIPSIS))
          .withField(new QFieldMetaData("oldValue", QFieldType.STRING).withMaxLength(250).withBehavior(ValueTooLongBehavior.TRUNCATE_ELLIPSIS))

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

@@ -22,6 +22,9 @@
 package com.kingsrook.qqq.backend.core.model.dashboard.widgets;
 
 
+import java.util.List;
+
+
 /*******************************************************************************
  ** Model containing datastructure expected by frontend alert widget
  **
@@ -40,8 +43,10 @@ public class AlertData extends QWidgetData
 
 
 
-   private String    html;
+   private String       html;
-   private AlertType alertType;
+   private AlertType    alertType;
+   private Boolean      hideWidget = false;
+   private List<String> bulletList;
 
 
 
@@ -139,4 +144,66 @@ public class AlertData extends QWidgetData
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for hideWidget
+    *******************************************************************************/
+   public boolean getHideWidget()
+   {
+      return (this.hideWidget);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for hideWidget
+    *******************************************************************************/
+   public void setHideWidget(boolean hideWidget)
+   {
+      this.hideWidget = hideWidget;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for hideWidget
+    *******************************************************************************/
+   public AlertData withHideWidget(boolean hideWidget)
+   {
+      this.hideWidget = hideWidget;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for bulletList
+    *******************************************************************************/
+   public List<String> getBulletList()
+   {
+      return (this.bulletList);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for bulletList
+    *******************************************************************************/
+   public void setBulletList(List<String> bulletList)
+   {
+      this.bulletList = bulletList;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for bulletList
+    *******************************************************************************/
+   public AlertData withBulletList(List<String> bulletList)
+   {
+      this.bulletList = bulletList;
+      return (this);
+   }
+
 }

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

@@ -39,9 +39,13 @@ public class ChildRecordListData extends QWidgetData
    private QueryOutput    queryOutput;
    private QTableMetaData childTableMetaData;
 
+   private String  tableName;
    private String  tablePath;
    private String  viewAllLink;
    private Integer totalRows;
+   private Boolean disableRowClick   = false;
+   private Boolean allowRecordEdit   = false;
+   private Boolean allowRecordDelete = false;
 
    private boolean                   canAddChildRecord = false;
    private Map<String, Serializable> defaultValuesForNewChildRecords;
@@ -352,4 +356,141 @@ public class ChildRecordListData extends QWidgetData
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for tableName
+    *******************************************************************************/
+   public String getTableName()
+   {
+      return (this.tableName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for tableName
+    *******************************************************************************/
+   public void setTableName(String tableName)
+   {
+      this.tableName = tableName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for tableName
+    *******************************************************************************/
+   public ChildRecordListData withTableName(String tableName)
+   {
+      this.tableName = tableName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for tablePath
+    *******************************************************************************/
+   public ChildRecordListData withTablePath(String tablePath)
+   {
+      this.tablePath = tablePath;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for disableRowClick
+    *******************************************************************************/
+   public Boolean getDisableRowClick()
+   {
+      return (this.disableRowClick);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for disableRowClick
+    *******************************************************************************/
+   public void setDisableRowClick(Boolean disableRowClick)
+   {
+      this.disableRowClick = disableRowClick;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for disableRowClick
+    *******************************************************************************/
+   public ChildRecordListData withDisableRowClick(Boolean disableRowClick)
+   {
+      this.disableRowClick = disableRowClick;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for allowRecordEdit
+    *******************************************************************************/
+   public Boolean getAllowRecordEdit()
+   {
+      return (this.allowRecordEdit);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for allowRecordEdit
+    *******************************************************************************/
+   public void setAllowRecordEdit(Boolean allowRecordEdit)
+   {
+      this.allowRecordEdit = allowRecordEdit;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for allowRecordEdit
+    *******************************************************************************/
+   public ChildRecordListData withAllowRecordEdit(Boolean allowRecordEdit)
+   {
+      this.allowRecordEdit = allowRecordEdit;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for allowRecordDelete
+    *******************************************************************************/
+   public Boolean getAllowRecordDelete()
+   {
+      return (this.allowRecordDelete);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for allowRecordDelete
+    *******************************************************************************/
+   public void setAllowRecordDelete(Boolean allowRecordDelete)
+   {
+      this.allowRecordDelete = allowRecordDelete;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for allowRecordDelete
+    *******************************************************************************/
+   public ChildRecordListData withAllowRecordDelete(Boolean allowRecordDelete)
+   {
+      this.allowRecordDelete = allowRecordDelete;
+      return (this);
+   }
 }
+
+
+

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

@@ -40,9 +40,24 @@ public class CompositeWidgetData extends AbstractBlockWidgetData<CompositeWidget
 {
    private List<AbstractBlockWidgetData<?, ?, ?, ?>> blocks = new ArrayList<>();
 
-   private Map<String, Serializable> styleOverrides = new HashMap<>();
+   private ModalMode modalMode;
 
-   private Layout layout;
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum ModalMode
+   {
+      MODAL
+   }
+
+
+
+   private Layout                    layout;
+   private Map<String, Serializable> styleOverrides        = new HashMap<>();
+   private String                    overlayHtml;
+   private Map<String, Serializable> overlayStyleOverrides = new HashMap<>();
 
 
 
@@ -51,12 +66,14 @@ public class CompositeWidgetData extends AbstractBlockWidgetData<CompositeWidget
     *******************************************************************************/
    public enum Layout
    {
-      /////////////////////////////////////////////////////////////
+      /////////////////////////////////////////////////////////
-      // note, these are used in QQQ FMD CompositeWidgetData.tsx //
+      // note, these are used in QQQ FMD CompositeWidget.tsx //
-      /////////////////////////////////////////////////////////////
+      // and qqq-android CompositeWidgetBlock.kt             //
+      /////////////////////////////////////////////////////////
       FLEX_COLUMN,
       FLEX_ROW_WRAPPED,
       FLEX_ROW_SPACE_BETWEEN,
+      FLEX_ROW_CENTER,
       TABLE_SUB_ROW_DETAILS,
       BADGES_WRAPPER
    }
@@ -218,4 +235,122 @@ public class CompositeWidgetData extends AbstractBlockWidgetData<CompositeWidget
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for overlayHtml
+    *******************************************************************************/
+   public String getOverlayHtml()
+   {
+      return (this.overlayHtml);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for overlayHtml
+    *******************************************************************************/
+   public void setOverlayHtml(String overlayHtml)
+   {
+      this.overlayHtml = overlayHtml;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for overlayHtml
+    *******************************************************************************/
+   public CompositeWidgetData withOverlayHtml(String overlayHtml)
+   {
+      this.overlayHtml = overlayHtml;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for overlayStyleOverrides
+    *******************************************************************************/
+   public Map<String, Serializable> getOverlayStyleOverrides()
+   {
+      return (this.overlayStyleOverrides);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for overlayStyleOverrides
+    *******************************************************************************/
+   public void setOverlayStyleOverrides(Map<String, Serializable> overlayStyleOverrides)
+   {
+      this.overlayStyleOverrides = overlayStyleOverrides;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for overlayStyleOverrides
+    *******************************************************************************/
+   public CompositeWidgetData withOverlayStyleOverrides(Map<String, Serializable> overlayStyleOverrides)
+   {
+      this.overlayStyleOverrides = overlayStyleOverrides;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public CompositeWidgetData withOverlayStyleOverride(String key, Serializable value)
+   {
+      addOverlayStyleOverride(key, value);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void addOverlayStyleOverride(String key, Serializable value)
+   {
+      if(this.overlayStyleOverrides == null)
+      {
+         this.overlayStyleOverrides = new HashMap<>();
+      }
+      this.overlayStyleOverrides.put(key, value);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for modalMode
+    *******************************************************************************/
+   public ModalMode getModalMode()
+   {
+      return (this.modalMode);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for modalMode
+    *******************************************************************************/
+   public void setModalMode(ModalMode modalMode)
+   {
+      this.modalMode = modalMode;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for modalMode
+    *******************************************************************************/
+   public CompositeWidgetData withModalMode(ModalMode modalMode)
+   {
+      this.modalMode = modalMode;
+      return (this);
+   }
+
 }

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

@@ -31,7 +31,7 @@ import java.util.Map;
  ** Base class for the data returned by rendering a Widget.
  **
  *******************************************************************************/
-public abstract class QWidgetData
+public abstract class QWidgetData implements Serializable
 {
    private String       label;
    private String       sublabel;

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

@@ -24,6 +24,7 @@ package com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks;
 
 import java.util.HashMap;
 import java.util.Map;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.CompositeWidgetData;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.QWidgetData;
 
 
@@ -51,6 +52,11 @@ public abstract class AbstractBlockWidgetData<
    private V  values;
    private SX styles;
 
+   ///////////////////////////////////////////////////////////////////////////////////
+   // optional field name to act as a 'guard' for the block - e.g., only include it //
+   // if the value for this field is true                                           //
+   ///////////////////////////////////////////////////////////////////////////////////
+   private String conditional;
 
 
    /*******************************************************************************
@@ -203,6 +209,19 @@ public abstract class AbstractBlockWidgetData<
 
 
 
+   /*******************************************************************************
+    ** Fluent setter for tooltip
+    **
+    *******************************************************************************/
+   @SuppressWarnings("unchecked")
+   public T withTooltip(CompositeWidgetData data)
+   {
+      this.tooltip = new BlockTooltip(data);
+      return (T) (this);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -398,6 +417,7 @@ public abstract class AbstractBlockWidgetData<
    }
 
 
+
    /*******************************************************************************
     ** Getter for blockId
     *******************************************************************************/
@@ -429,4 +449,34 @@ public abstract class AbstractBlockWidgetData<
    }
 
 
+   /*******************************************************************************
+    ** Getter for conditional
+    *******************************************************************************/
+   public String getConditional()
+   {
+      return (this.conditional);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for conditional
+    *******************************************************************************/
+   public void setConditional(String conditional)
+   {
+      this.conditional = conditional;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for conditional
+    *******************************************************************************/
+   public AbstractBlockWidgetData withConditional(String conditional)
+   {
+      this.conditional = conditional;
+      return (this);
+   }
+
+
 }

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

@@ -22,14 +22,18 @@
 package com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks;
 
 
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.CompositeWidgetData;
+
+
 /*******************************************************************************
  ** A tooltip used within a (widget) block.
  **
  *******************************************************************************/
 public class BlockTooltip
 {
-   private String    title;
+   private CompositeWidgetData blockData;
-   private Placement placement = Placement.BOTTOM;
+   private String              title;
+   private Placement           placement = Placement.BOTTOM;
 
 
 
@@ -62,6 +66,17 @@ public class BlockTooltip
 
 
 
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public BlockTooltip(CompositeWidgetData blockData)
+   {
+      this.blockData = blockData;
+   }
+
+
+
    /*******************************************************************************
     ** Getter for title
     *******************************************************************************/
@@ -122,4 +137,35 @@ public class BlockTooltip
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for blockData
+    *******************************************************************************/
+   public CompositeWidgetData getBlockData()
+   {
+      return (this.blockData);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for blockData
+    *******************************************************************************/
+   public void setBlockData(CompositeWidgetData blockData)
+   {
+      this.blockData = blockData;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for blockData
+    *******************************************************************************/
+   public BlockTooltip withBlockData(CompositeWidgetData blockData)
+   {
+      this.blockData = blockData;
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/audio/AudioBlockData.java

@@ -0,0 +1,45 @@
+/*
+ * 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.model.dashboard.widgets.blocks.audio;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.AbstractBlockWidgetData;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseSlots;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseStyles;
+
+
+/*******************************************************************************
+ ** block that plays an audio file
+ *******************************************************************************/
+public class AudioBlockData extends AbstractBlockWidgetData<AudioBlockData, AudioValues, BaseSlots, BaseStyles>
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public String getBlockTypeName()
+   {
+      return "AUDIO";
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/audio/AudioValues.java

@@ -0,0 +1,130 @@
+/*
+ * 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.model.dashboard.widgets.blocks.audio;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockValuesInterface;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class AudioValues implements BlockValuesInterface
+{
+   private String  path;
+   private boolean showControls = false;
+   private boolean autoPlay     = true;
+
+
+
+   /*******************************************************************************
+    ** Getter for path
+    *******************************************************************************/
+   public String getPath()
+   {
+      return (this.path);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for path
+    *******************************************************************************/
+   public void setPath(String path)
+   {
+      this.path = path;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for path
+    *******************************************************************************/
+   public AudioValues withPath(String path)
+   {
+      this.path = path;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for showControls
+    *******************************************************************************/
+   public boolean getShowControls()
+   {
+      return (this.showControls);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for showControls
+    *******************************************************************************/
+   public void setShowControls(boolean showControls)
+   {
+      this.showControls = showControls;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for showControls
+    *******************************************************************************/
+   public AudioValues withShowControls(boolean showControls)
+   {
+      this.showControls = showControls;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for autoPlay
+    *******************************************************************************/
+   public boolean getAutoPlay()
+   {
+      return (this.autoPlay);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for autoPlay
+    *******************************************************************************/
+   public void setAutoPlay(boolean autoPlay)
+   {
+      this.autoPlay = autoPlay;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for autoPlay
+    *******************************************************************************/
+   public AudioValues withAutoPlay(boolean autoPlay)
+   {
+      this.autoPlay = autoPlay;
+      return (this);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/base/BaseStyles.java

@@ -30,4 +30,335 @@ import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockStyles
  *******************************************************************************/
 public class BaseStyles implements BlockStylesInterface
 {
+   private Directional<String> padding;
+
+   private String backgroundColor;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static class Directional<T>
+   {
+      private T top;
+      private T bottom;
+      private T left;
+      private T right;
+
+
+
+      /*******************************************************************************
+       ** Constructor
+       **
+       *******************************************************************************/
+      public Directional()
+      {
+      }
+
+
+
+      /*******************************************************************************
+       ** Constructor
+       **
+       *******************************************************************************/
+      public Directional(T top, T right, T bottom, T left)
+      {
+         this.top = top;
+         this.right = right;
+         this.bottom = bottom;
+         this.left = left;
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> of(T top, T right, T bottom, T left)
+      {
+         return (new Directional<>(top, right, bottom, left));
+      }
+
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> of(T value)
+      {
+         return (new Directional<>(value, value, value, value));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofTop(T top)
+      {
+         return (new Directional<>(top, null, null, null));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofRight(T right)
+      {
+         return (new Directional<>(null, right, null, null));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofBottom(T bottom)
+      {
+         return (new Directional<>(null, null, bottom, null));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofLeft(T left)
+      {
+         return (new Directional<>(null, null, null, left));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofX(T x)
+      {
+         return (new Directional<>(null, x, null, x));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofY(T y)
+      {
+         return (new Directional<>(y, null, y, null));
+      }
+
+
+
+      /***************************************************************************
+       **
+       ***************************************************************************/
+      public static <T> Directional<T> ofXY(T x, T y)
+      {
+         return (new Directional<>(y, x, y, x));
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for top
+       **
+       *******************************************************************************/
+      public T getTop()
+      {
+         return top;
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for top
+       **
+       *******************************************************************************/
+      public void setTop(T top)
+      {
+         this.top = top;
+      }
+
+
+
+      /*******************************************************************************
+       ** Fluent setter for top
+       **
+       *******************************************************************************/
+      public Directional<T> withTop(T top)
+      {
+         this.top = top;
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for bottom
+       **
+       *******************************************************************************/
+      public T getBottom()
+      {
+         return bottom;
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for bottom
+       **
+       *******************************************************************************/
+      public void setBottom(T bottom)
+      {
+         this.bottom = bottom;
+      }
+
+
+
+      /*******************************************************************************
+       ** Fluent setter for bottom
+       **
+       *******************************************************************************/
+      public Directional<T> withBottom(T bottom)
+      {
+         this.bottom = bottom;
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for left
+       **
+       *******************************************************************************/
+      public T getLeft()
+      {
+         return left;
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for left
+       **
+       *******************************************************************************/
+      public void setLeft(T left)
+      {
+         this.left = left;
+      }
+
+
+
+      /*******************************************************************************
+       ** Fluent setter for left
+       **
+       *******************************************************************************/
+      public Directional<T> withLeft(T left)
+      {
+         this.left = left;
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for right
+       **
+       *******************************************************************************/
+      public T getRight()
+      {
+         return right;
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for right
+       **
+       *******************************************************************************/
+      public void setRight(T right)
+      {
+         this.right = right;
+      }
+
+
+
+      /*******************************************************************************
+       ** Fluent setter for right
+       **
+       *******************************************************************************/
+      public Directional<T> withRight(T right)
+      {
+         this.right = right;
+         return (this);
+      }
+
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for padding
+    *******************************************************************************/
+   public Directional<String> getPadding()
+   {
+      return (this.padding);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for padding
+    *******************************************************************************/
+   public void setPadding(Directional<String> padding)
+   {
+      this.padding = padding;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for padding
+    *******************************************************************************/
+   public BaseStyles withPadding(Directional<String> padding)
+   {
+      this.padding = padding;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for backgroundColor
+    *******************************************************************************/
+   public String getBackgroundColor()
+   {
+      return (this.backgroundColor);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for backgroundColor
+    *******************************************************************************/
+   public void setBackgroundColor(String backgroundColor)
+   {
+      this.backgroundColor = backgroundColor;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for backgroundColor
+    *******************************************************************************/
+   public BaseStyles withBackgroundColor(String backgroundColor)
+   {
+      this.backgroundColor = backgroundColor;
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/button/ButtonBlockData.java

@@ -0,0 +1,46 @@
+/*
+ * 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.model.dashboard.widgets.blocks.button;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.AbstractBlockWidgetData;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseSlots;
+
+
+/*******************************************************************************
+ ** a button (for a process - not sure yet what this could do in a standalone
+ ** widget?) to submit the process screen to run a specific action (e.g., not just
+ ** 'next'), or do other control-ish things
+ *******************************************************************************/
+public class ButtonBlockData extends AbstractBlockWidgetData<ButtonBlockData, ButtonValues, BaseSlots, ButtonStyles>
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public String getBlockTypeName()
+   {
+      return "BUTTON";
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/button/ButtonStyles.java

@@ -0,0 +1,143 @@
+/*
+ * 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.model.dashboard.widgets.blocks.button;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockStylesInterface;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ButtonStyles implements BlockStylesInterface
+{
+   private String color;
+   private String format;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum StandardColor
+   {
+      SUCCESS,
+      WARNING,
+      ERROR,
+      INFO,
+      MUTED
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum StandardFormat
+   {
+      OUTLINED,
+      FILLED,
+      TEXT
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for color
+    *******************************************************************************/
+   public String getColor()
+   {
+      return (this.color);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for color
+    *******************************************************************************/
+   public void setColor(String color)
+   {
+      this.color = color;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for color
+    *******************************************************************************/
+   public ButtonStyles withColor(String color)
+   {
+      this.color = color;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for format
+    *******************************************************************************/
+   public String getFormat()
+   {
+      return (this.format);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for format
+    *******************************************************************************/
+   public void setFormat(String format)
+   {
+      this.format = format;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for format
+    *******************************************************************************/
+   public ButtonStyles withFormat(String format)
+   {
+      this.format = format;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Setter for format
+    *******************************************************************************/
+   public void setFormat(StandardFormat format)
+   {
+      this.format = (format == null ? null : format.name().toLowerCase());
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for format
+    *******************************************************************************/
+   public ButtonStyles withFormat(StandardFormat format)
+   {
+      setFormat(format);
+      return (this);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/button/ButtonValues.java

@@ -0,0 +1,218 @@
+/*
+ * 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.model.dashboard.widgets.blocks.button;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockValuesInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ButtonValues implements BlockValuesInterface
+{
+   private String label;
+   private String actionCode;
+   private String controlCode;
+
+   private QIcon startIcon;
+   private QIcon endIcon;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public ButtonValues()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public ButtonValues(String label, String actionCode)
+   {
+      setLabel(label);
+      setActionCode(actionCode);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for label
+    *******************************************************************************/
+   public String getLabel()
+   {
+      return (this.label);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for label
+    *******************************************************************************/
+   public void setLabel(String label)
+   {
+      this.label = label;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for label
+    *******************************************************************************/
+   public ButtonValues withLabel(String label)
+   {
+      this.label = label;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for actionCode
+    *******************************************************************************/
+   public String getActionCode()
+   {
+      return (this.actionCode);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for actionCode
+    *******************************************************************************/
+   public void setActionCode(String actionCode)
+   {
+      this.actionCode = actionCode;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for actionCode
+    *******************************************************************************/
+   public ButtonValues withActionCode(String actionCode)
+   {
+      this.actionCode = actionCode;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for startIcon
+    *******************************************************************************/
+   public QIcon getStartIcon()
+   {
+      return (this.startIcon);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for startIcon
+    *******************************************************************************/
+   public void setStartIcon(QIcon startIcon)
+   {
+      this.startIcon = startIcon;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for startIcon
+    *******************************************************************************/
+   public ButtonValues withStartIcon(QIcon startIcon)
+   {
+      this.startIcon = startIcon;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for endIcon
+    *******************************************************************************/
+   public QIcon getEndIcon()
+   {
+      return (this.endIcon);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for endIcon
+    *******************************************************************************/
+   public void setEndIcon(QIcon endIcon)
+   {
+      this.endIcon = endIcon;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for endIcon
+    *******************************************************************************/
+   public ButtonValues withEndIcon(QIcon endIcon)
+   {
+      this.endIcon = endIcon;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for controlCode
+    *******************************************************************************/
+   public String getControlCode()
+   {
+      return (this.controlCode);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for controlCode
+    *******************************************************************************/
+   public void setControlCode(String controlCode)
+   {
+      this.controlCode = controlCode;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for controlCode
+    *******************************************************************************/
+   public ButtonValues withControlCode(String controlCode)
+   {
+      this.controlCode = controlCode;
+      return (this);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/image/ImageBlockData.java

@@ -0,0 +1,44 @@
+/*
+ * 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.model.dashboard.widgets.blocks.image;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.AbstractBlockWidgetData;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseSlots;
+
+
+/*******************************************************************************
+ ** block to display an image
+ *******************************************************************************/
+public class ImageBlockData extends AbstractBlockWidgetData<ImageBlockData, ImageValues, BaseSlots, ImageStyles>
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public String getBlockTypeName()
+   {
+      return "IMAGE";
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/image/ImageStyles.java

@@ -0,0 +1,108 @@
+/*
+ * 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.model.dashboard.widgets.blocks.image;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseStyles;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ImageStyles extends BaseStyles
+{
+   private String width;
+   private String height;
+
+
+   /*******************************************************************************
+    ** Fluent setter for padding
+    *******************************************************************************/
+   @Override
+   public ImageStyles withPadding(Directional<String> padding)
+   {
+      super.setPadding(padding);
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for width
+    *******************************************************************************/
+   public String getWidth()
+   {
+      return (this.width);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for width
+    *******************************************************************************/
+   public void setWidth(String width)
+   {
+      this.width = width;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for width
+    *******************************************************************************/
+   public ImageStyles withWidth(String width)
+   {
+      this.width = width;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for height
+    *******************************************************************************/
+   public String getHeight()
+   {
+      return (this.height);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for height
+    *******************************************************************************/
+   public void setHeight(String height)
+   {
+      this.height = height;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for height
+    *******************************************************************************/
+   public ImageStyles withHeight(String height)
+   {
+      this.height = height;
+      return (this);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/image/ImageValues.java

@@ -0,0 +1,98 @@
+/*
+ * 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.model.dashboard.widgets.blocks.image;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockValuesInterface;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ImageValues implements BlockValuesInterface
+{
+   private String path;
+   private String alt;
+
+
+
+   /*******************************************************************************
+    ** Getter for path
+    *******************************************************************************/
+   public String getPath()
+   {
+      return (this.path);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for path
+    *******************************************************************************/
+   public void setPath(String path)
+   {
+      this.path = path;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for path
+    *******************************************************************************/
+   public ImageValues withPath(String path)
+   {
+      this.path = path;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for alt
+    *******************************************************************************/
+   public String getAlt()
+   {
+      return (this.alt);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for alt
+    *******************************************************************************/
+   public void setAlt(String alt)
+   {
+      this.alt = alt;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for alt
+    *******************************************************************************/
+   public ImageValues withAlt(String alt)
+   {
+      this.alt = alt;
+      return (this);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/inputfield/InputFieldBlockData.java

@@ -0,0 +1,45 @@
+/*
+ * 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.model.dashboard.widgets.blocks.inputfield;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.AbstractBlockWidgetData;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseSlots;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.base.BaseStyles;
+
+
+/*******************************************************************************
+ ** block to display an input field - initially targeted at widgets-in-processes
+ *******************************************************************************/
+public class InputFieldBlockData extends AbstractBlockWidgetData<InputFieldBlockData, InputFieldValues, BaseSlots, BaseStyles>
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public String getBlockTypeName()
+   {
+      return "INPUT_FIELD";
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/inputfield/InputFieldValues.java

@@ -0,0 +1,217 @@
+/*
+ * 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.model.dashboard.widgets.blocks.inputfield;
+
+
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockValuesInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class InputFieldValues implements BlockValuesInterface
+{
+   private QFieldMetaData fieldMetaData;
+
+   private Boolean autoFocus;
+   private Boolean submitOnEnter;
+   private Boolean hideSoftKeyboard;
+   private String  placeholder;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public InputFieldValues()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public InputFieldValues(QFieldMetaData fieldMetaData)
+   {
+      setFieldMetaData(fieldMetaData);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fieldMetaData
+    *******************************************************************************/
+   public QFieldMetaData getFieldMetaData()
+   {
+      return (this.fieldMetaData);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for fieldMetaData
+    *******************************************************************************/
+   public void setFieldMetaData(QFieldMetaData fieldMetaData)
+   {
+      this.fieldMetaData = fieldMetaData;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fieldMetaData
+    *******************************************************************************/
+   public InputFieldValues withFieldMetaData(QFieldMetaData fieldMetaData)
+   {
+      this.fieldMetaData = fieldMetaData;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for autoFocus
+    *******************************************************************************/
+   public Boolean getAutoFocus()
+   {
+      return (this.autoFocus);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for autoFocus
+    *******************************************************************************/
+   public void setAutoFocus(Boolean autoFocus)
+   {
+      this.autoFocus = autoFocus;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for autoFocus
+    *******************************************************************************/
+   public InputFieldValues withAutoFocus(Boolean autoFocus)
+   {
+      this.autoFocus = autoFocus;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for submitOnEnter
+    *******************************************************************************/
+   public Boolean getSubmitOnEnter()
+   {
+      return (this.submitOnEnter);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for submitOnEnter
+    *******************************************************************************/
+   public void setSubmitOnEnter(Boolean submitOnEnter)
+   {
+      this.submitOnEnter = submitOnEnter;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for submitOnEnter
+    *******************************************************************************/
+   public InputFieldValues withSubmitOnEnter(Boolean submitOnEnter)
+   {
+      this.submitOnEnter = submitOnEnter;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for placeholder
+    *******************************************************************************/
+   public String getPlaceholder()
+   {
+      return (this.placeholder);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for placeholder
+    *******************************************************************************/
+   public void setPlaceholder(String placeholder)
+   {
+      this.placeholder = placeholder;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for placeholder
+    *******************************************************************************/
+   public InputFieldValues withPlaceholder(String placeholder)
+   {
+      this.placeholder = placeholder;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for hideSoftKeyboard
+    *******************************************************************************/
+   public Boolean getHideSoftKeyboard()
+   {
+      return (this.hideSoftKeyboard);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for hideSoftKeyboard
+    *******************************************************************************/
+   public void setHideSoftKeyboard(Boolean hideSoftKeyboard)
+   {
+      this.hideSoftKeyboard = hideSoftKeyboard;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for hideSoftKeyboard
+    *******************************************************************************/
+   public InputFieldValues withHideSoftKeyboard(Boolean hideSoftKeyboard)
+   {
+      this.hideSoftKeyboard = hideSoftKeyboard;
+      return (this);
+   }
+
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/text/TextStyles.java

@@ -30,4 +30,325 @@ import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockStyles
  *******************************************************************************/
 public class TextStyles implements BlockStylesInterface
 {
+   private String color;
+   private String format;
+   private String weight;
+   private String size;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum StandardColor
+   {
+      SUCCESS,
+      WARNING,
+      ERROR,
+      INFO,
+      MUTED
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum StandardFormat
+   {
+      DEFAULT,
+      ALERT,
+      BANNER
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum StandardSize
+   {
+      LARGEST,
+      HEADLINE,
+      TITLE,
+      BODY,
+      SMALLEST
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public enum StandardWeight
+   {
+      EXTRA_LIGHT("extralight"),
+      THIN("thin"),
+      MEDIUM("medium"),
+      SEMI_BOLD("semibold"),
+      BLACK("black"),
+      BOLD("bold"),
+      EXTRA_BOLD("extrabold"),
+      W100("100"),
+      W200("200"),
+      W300("300"),
+      W400("400"),
+      W500("500"),
+      W600("600"),
+      W700("700"),
+      W800("800"),
+      W900("900");
+
+      private final String value;
+
+
+
+      /*******************************************************************************
+       ** Constructor
+       **
+       *******************************************************************************/
+      StandardWeight(String value)
+      {
+         this.value = value;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for value
+       **
+       *******************************************************************************/
+      public String getValue()
+      {
+         return value;
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public TextStyles()
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public TextStyles(StandardColor standardColor)
+   {
+      setColor(standardColor);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for format
+    *******************************************************************************/
+   public String getFormat()
+   {
+      return (this.format);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for format
+    *******************************************************************************/
+   public void setFormat(String format)
+   {
+      this.format = format;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for format
+    *******************************************************************************/
+   public TextStyles withFormat(String format)
+   {
+      this.format = format;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for format
+    *******************************************************************************/
+   public void setFormat(StandardFormat format)
+   {
+      this.format = format == null ? null : format.name().toLowerCase();
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for format
+    *******************************************************************************/
+   public TextStyles withFormat(StandardFormat format)
+   {
+      this.setFormat(format);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for weight
+    *******************************************************************************/
+   public String getWeight()
+   {
+      return (this.weight);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for weight
+    *******************************************************************************/
+   public void setWeight(String weight)
+   {
+      this.weight = weight;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for weight
+    *******************************************************************************/
+   public TextStyles withWeight(String weight)
+   {
+      this.weight = weight;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for weight
+    *******************************************************************************/
+   public void setWeight(StandardWeight weight)
+   {
+      setWeight(weight == null ? null : weight.getValue());
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for weight
+    *******************************************************************************/
+   public TextStyles withWeight(StandardWeight weight)
+   {
+      setWeight(weight);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for size
+    *******************************************************************************/
+   public String getSize()
+   {
+      return (this.size);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for size
+    *******************************************************************************/
+   public void setSize(String size)
+   {
+      this.size = size;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for size
+    *******************************************************************************/
+   public TextStyles withSize(String size)
+   {
+      this.size = size;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Setter for size
+    *******************************************************************************/
+   public void setSize(StandardSize size)
+   {
+      this.size = (size == null ? null : size.name().toLowerCase());
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for size
+    *******************************************************************************/
+   public TextStyles withSize(StandardSize size)
+   {
+      setSize(size);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for color
+    *******************************************************************************/
+   public String getColor()
+   {
+      return (this.color);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for color
+    *******************************************************************************/
+   public void setColor(String color)
+   {
+      this.color = color;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for color
+    *******************************************************************************/
+   public TextStyles withColor(String color)
+   {
+      this.color = color;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for color
+    *******************************************************************************/
+   public void setColor(StandardColor color)
+   {
+      this.color = color == null ? null : color.name();
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for color
+    *******************************************************************************/
+   public TextStyles withColor(StandardColor color)
+   {
+      setColor(color);
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/dashboard/widgets/blocks/text/TextValues.java

@@ -23,6 +23,7 @@ package com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.text;
 
 
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockValuesInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 
 
 /*******************************************************************************
@@ -32,6 +33,9 @@ public class TextValues implements BlockValuesInterface
 {
    private String text;
 
+   private QIcon startIcon;
+   private QIcon endIcon;
+
 
 
    /*******************************************************************************
@@ -84,4 +88,66 @@ public class TextValues implements BlockValuesInterface
       return (this);
    }
 
+
+   /*******************************************************************************
+    ** Getter for startIcon
+    *******************************************************************************/
+   public QIcon getStartIcon()
+   {
+      return (this.startIcon);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for startIcon
+    *******************************************************************************/
+   public void setStartIcon(QIcon startIcon)
+   {
+      this.startIcon = startIcon;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for startIcon
+    *******************************************************************************/
+   public TextValues withStartIcon(QIcon startIcon)
+   {
+      this.startIcon = startIcon;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for endIcon
+    *******************************************************************************/
+   public QIcon getEndIcon()
+   {
+      return (this.endIcon);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for endIcon
+    *******************************************************************************/
+   public void setEndIcon(QIcon endIcon)
+   {
+      this.endIcon = endIcon;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for endIcon
+    *******************************************************************************/
+   public TextValues withEndIcon(QIcon endIcon)
+   {
+      this.endIcon = endIcon;
+      return (this);
+   }
+
+
 }

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

@@ -22,9 +22,6 @@
 package com.kingsrook.qqq.backend.core.model.metadata;
 
 
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
-
-
 /*******************************************************************************
  ** Abstract class that knows how to produce meta data objects.  Useful with
  ** MetaDataProducerHelper, to put point at a package full of these, and populate

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

@@ -22,7 +22,6 @@
 package com.kingsrook.qqq.backend.core.model.metadata;
 
 
-import java.io.IOException;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Modifier;
 import java.util.ArrayList;
@@ -30,14 +29,12 @@ import java.util.Comparator;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
-import com.google.common.collect.ImmutableSet;
-import com.google.common.reflect.ClassPath;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.utils.ClassPathUtils;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
@@ -51,8 +48,6 @@ public class MetaDataProducerHelper
    private static Map<Class<?>, Integer> comparatorValuesByType = new HashMap<>();
    private static Integer                defaultComparatorValue;
 
-   private static ImmutableSet<ClassPath.ClassInfo> topLevelClasses;
-
    static
    {
       ////////////////////////////////////////////////////////////////////////////////////////
@@ -87,7 +82,7 @@ public class MetaDataProducerHelper
          ////////////////////////////////////////////////////////////////////////
          // find all the meta data producer classes in (and under) the package //
          ////////////////////////////////////////////////////////////////////////
-         classesInPackage = getClassesInPackage(packageName);
+         classesInPackage = ClassPathUtils.getClassesInPackage(packageName);
       }
       catch(Exception e)
       {
@@ -176,51 +171,4 @@ public class MetaDataProducerHelper
 
    }
 
-
-
-   /*******************************************************************************
-    ** from https://stackoverflow.com/questions/520328/can-you-find-all-classes-in-a-package-using-reflection
-    ** (since the original, from ChatGPT, didn't work in jars, despite GPT hallucinating that it would)
-    *******************************************************************************/
-   private static List<Class<?>> getClassesInPackage(String packageName) throws IOException
-   {
-      List<Class<?>> classes = new ArrayList<>();
-      ClassLoader    loader  = Thread.currentThread().getContextClassLoader();
-
-      for(ClassPath.ClassInfo info : getTopLevelClasses(loader))
-      {
-         if(info.getName().startsWith(packageName))
-         {
-            classes.add(info.load());
-         }
-      }
-
-      return (classes);
-   }
-
-
-
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   private static ImmutableSet<ClassPath.ClassInfo> getTopLevelClasses(ClassLoader loader) throws IOException
-   {
-      if(topLevelClasses == null)
-      {
-         topLevelClasses = ClassPath.from(loader).getTopLevelClasses();
-      }
-
-      return (topLevelClasses);
-   }
-
-
-
-   /*******************************************************************************
-    **
-    *******************************************************************************/
-   public static void clearTopLevelClassCache()
-   {
-      topLevelClasses = null;
-   }
-
 }

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

@@ -1,6 +1,6 @@
 /*
  * QQQ - Low-code Application Framework for Engineers.
- * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 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/
@@ -19,12 +19,10 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-package com.kingsrook.qqq.backend.core.model;
+package com.kingsrook.qqq.backend.core.model.metadata;
 
 
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerOutput;
-import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 
 
 /*******************************************************************************

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

@@ -43,6 +43,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.audits.QAuditRules;
 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.branding.QBrandingMetaData;
+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.frontend.AppTreeNode;
 import com.kingsrook.qqq.backend.core.model.metadata.frontend.AppTreeNodeType;
@@ -113,6 +114,8 @@ public class QInstance
    private QPermissionRules defaultPermissionRules = QPermissionRules.defaultInstance();
    private QAuditRules      defaultAuditRules      = QAuditRules.defaultInstanceLevelNone();
 
+   private QCodeReference metaDataFilter = null;
+
    //////////////////////////////////////////////////////////////////////////////////////
    // todo - lock down the object (no more changes allowed) after it's been validated? //
    //  if doing so, may need to copy all of the collections into read-only versions... //
@@ -1485,4 +1488,35 @@ public class QInstance
       QInstanceHelpContentManager.removeHelpContentByRoleSetFromList(roles, listForSlot);
    }
 
+
+   /*******************************************************************************
+    ** Getter for metaDataFilter
+    *******************************************************************************/
+   public QCodeReference getMetaDataFilter()
+   {
+      return (this.metaDataFilter);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for metaDataFilter
+    *******************************************************************************/
+   public void setMetaDataFilter(QCodeReference metaDataFilter)
+   {
+      this.metaDataFilter = metaDataFilter;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for metaDataFilter
+    *******************************************************************************/
+   public QInstance withMetaDataFilter(QCodeReference metaDataFilter)
+   {
+      this.metaDataFilter = metaDataFilter;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/authentication/QAuthenticationMetaData.java

@@ -177,7 +177,7 @@ public class QAuthenticationMetaData implements TopLevelMetaDataInterface
    /*******************************************************************************
     **
     *******************************************************************************/
-   public QAuthenticationMetaData withVales(Map<String, String> values)
+   public QAuthenticationMetaData withValues(Map<String, String> values)
    {
       this.values = values;
       return (this);

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/code/QCodeReferenceLambda.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.model.metadata.code;
+
+
+/*******************************************************************************
+ ** Specialized type of QCodeReference that takes a lambda function object.
+ **
+ ** Originally intended for more concise setup of backend steps in tests - but,
+ ** may be generally useful.
+ *******************************************************************************/
+public class QCodeReferenceLambda<T> extends QCodeReference
+{
+   private final T lambda;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public QCodeReferenceLambda(T lambda)
+   {
+      this.lambda = lambda;
+      this.setCodeType(QCodeType.JAVA);
+      this.setName("[Lambda:" + lambda.toString() + "]");
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for lambda
+    **
+    *******************************************************************************/
+   public T getLambda()
+   {
+      return lambda;
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/fields/QFieldMetaData.java

@@ -42,6 +42,7 @@ import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.help.HelpRole;
 import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
 import com.kingsrook.qqq.backend.core.model.metadata.security.FieldSecurityLock;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
@@ -73,10 +74,12 @@ public class QFieldMetaData implements Cloneable
    // propose doing that in a secondary field, e.g., "onlyEditableOn=insert|update" //
    ///////////////////////////////////////////////////////////////////////////////////
 
-   private String displayFormat = "%s";
+   private String       displayFormat = "%s";
    private Serializable defaultValue;
-   private String       possibleValueSourceName;
+
-   private QQueryFilter possibleValueSourceFilter;
+   private String               possibleValueSourceName;
+   private QQueryFilter         possibleValueSourceFilter;
+   private QPossibleValueSource inlinePossibleValueSource;
 
    private Integer               maxLength;
    private Set<FieldBehavior<?>> behaviors;
@@ -1058,4 +1061,35 @@ public class QFieldMetaData implements Cloneable
       QInstanceHelpContentManager.removeHelpContentByRoleSetFromList(roles, this.helpContents);
    }
 
+
+   /*******************************************************************************
+    ** Getter for inlinePossibleValueSource
+    *******************************************************************************/
+   public QPossibleValueSource getInlinePossibleValueSource()
+   {
+      return (this.inlinePossibleValueSource);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for inlinePossibleValueSource
+    *******************************************************************************/
+   public void setInlinePossibleValueSource(QPossibleValueSource inlinePossibleValueSource)
+   {
+      this.inlinePossibleValueSource = inlinePossibleValueSource;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for inlinePossibleValueSource
+    *******************************************************************************/
+   public QFieldMetaData withInlinePossibleValueSource(QPossibleValueSource inlinePossibleValueSource)
+   {
+      this.inlinePossibleValueSource = inlinePossibleValueSource;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/frontend/AppTreeNode.java

@@ -26,6 +26,7 @@ import java.util.ArrayList;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppChildMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 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;
@@ -45,7 +46,7 @@ public class AppTreeNode
    private String            label;
    private List<AppTreeNode> children;
 
-   private String iconName;
+   private QIcon icon;
 
 
 
@@ -82,7 +83,7 @@ public class AppTreeNode
       if(appChildMetaData.getIcon() != null)
       {
          // todo - propagate icons from parents, if they aren't set here...
-         this.iconName = appChildMetaData.getIcon().getName();
+         this.icon = appChildMetaData.getIcon();
       }
    }
 
@@ -138,7 +139,18 @@ public class AppTreeNode
     *******************************************************************************/
    public String getIconName()
    {
-      return iconName;
+      return (icon == null ? null : icon.getName());
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for icon
+    **
+    *******************************************************************************/
+   public QIcon getIcon()
+   {
+      return icon;
    }
 
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/frontend/QFrontendAppMetaData.java

@@ -32,6 +32,7 @@ import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QSupplementalAppMetaData;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 
@@ -45,7 +46,7 @@ public class QFrontendAppMetaData
 {
    private String name;
    private String label;
-   private String iconName;
+   private QIcon  icon;
 
    private List<String>             widgets  = new ArrayList<>();
    private List<AppTreeNode>        children = new ArrayList<>();
@@ -56,6 +57,7 @@ public class QFrontendAppMetaData
    private Map<String, QSupplementalAppMetaData> supplementalAppMetaData;
 
 
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -63,11 +65,7 @@ public class QFrontendAppMetaData
    {
       this.name = appMetaData.getName();
       this.label = appMetaData.getLabel();
-
+      this.icon = appMetaData.getIcon();
-      if(appMetaData.getIcon() != null)
-      {
-         this.iconName = appMetaData.getIcon().getName();
-      }
 
       List<String> filteredWidgets = CollectionUtils.nonNullList(appMetaData.getWidgets()).stream().filter(n -> metaDataOutput.getWidgets().containsKey(n)).toList();
       if(CollectionUtils.nullSafeHasContents(filteredWidgets))
@@ -81,6 +79,10 @@ public class QFrontendAppMetaData
          List<String> filteredTables    = CollectionUtils.nonNullList(section.getTables()).stream().filter(n -> metaDataOutput.getTables().containsKey(n)).toList();
          List<String> filteredProcesses = CollectionUtils.nonNullList(section.getProcesses()).stream().filter(n -> metaDataOutput.getProcesses().containsKey(n)).toList();
          List<String> filteredReports   = CollectionUtils.nonNullList(section.getReports()).stream().filter(n -> metaDataOutput.getReports().containsKey(n)).toList();
+
+         //////////////////////////////////////////////////////
+         // only include the section if it has some contents //
+         //////////////////////////////////////////////////////
          if(!filteredTables.isEmpty() || !filteredProcesses.isEmpty() || !filteredReports.isEmpty())
          {
             QAppSection clonedSection = section.clone();
@@ -174,18 +176,7 @@ public class QFrontendAppMetaData
     *******************************************************************************/
    public String getIconName()
    {
-      return iconName;
+      return (icon == null ? null : icon.getName());
-   }
-
-
-
-   /*******************************************************************************
-    ** Setter for iconName
-    **
-    *******************************************************************************/
-   public void setIconName(String iconName)
-   {
-      this.iconName = iconName;
    }
 
 
@@ -235,4 +226,15 @@ public class QFrontendAppMetaData
    {
       return supplementalAppMetaData;
    }
+
+
+
+   /*******************************************************************************
+    ** Getter for icon
+    **
+    *******************************************************************************/
+   public QIcon getIcon()
+   {
+      return icon;
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/frontend/QFrontendFieldMetaData.java

@@ -33,6 +33,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldBehaviorForFron
 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.help.QHelpContent;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 
 
@@ -56,6 +57,7 @@ public class QFrontendFieldMetaData
 
    private List<FieldAdornment> adornments;
    private List<QHelpContent>   helpContents;
+   private QPossibleValueSource inlinePossibleValueSource;
 
    private List<FieldBehaviorForFrontend> behaviors;
 
@@ -81,6 +83,7 @@ public class QFrontendFieldMetaData
       this.adornments = fieldMetaData.getAdornments();
       this.defaultValue = fieldMetaData.getDefaultValue();
       this.helpContents = fieldMetaData.getHelpContents();
+      this.inlinePossibleValueSource = fieldMetaData.getInlinePossibleValueSource();
 
       for(FieldBehavior<?> behavior : CollectionUtils.nonNullCollection(fieldMetaData.getBehaviors()))
       {
@@ -218,6 +221,17 @@ public class QFrontendFieldMetaData
 
 
 
+   /*******************************************************************************
+    ** Getter for inlinePossibleValueSource
+    **
+    *******************************************************************************/
+   public QPossibleValueSource getInlinePossibleValueSource()
+   {
+      return inlinePossibleValueSource;
+   }
+
+
+
    /*******************************************************************************
     ** Getter for fieldBehaviors
     **

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/frontend/QFrontendProcessMetaData.java

@@ -29,8 +29,10 @@ import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QStateMachineStep;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 
 
@@ -47,9 +49,10 @@ public class QFrontendProcessMetaData
    private String  tableName;
    private boolean isHidden;
 
-   private String iconName;
+   private QIcon icon;
 
    private List<QFrontendStepMetaData> frontendSteps;
+   private String                      stepFlow;
 
    private boolean hasPermission;
 
@@ -68,15 +71,27 @@ public class QFrontendProcessMetaData
       this.label = processMetaData.getLabel();
       this.tableName = processMetaData.getTableName();
       this.isHidden = processMetaData.getIsHidden();
+      this.stepFlow = processMetaData.getStepFlow().toString();
 
       if(includeSteps)
       {
          if(CollectionUtils.nullSafeHasContents(processMetaData.getStepList()))
          {
-            this.frontendSteps = processMetaData.getStepList().stream()
+            this.frontendSteps = switch(processMetaData.getStepFlow())
-               .filter(QFrontendStepMetaData.class::isInstance)
+            {
-               .map(QFrontendStepMetaData.class::cast)
+               case LINEAR -> processMetaData.getStepList().stream()
-               .collect(Collectors.toList());
+                  .filter(QFrontendStepMetaData.class::isInstance)
+                  .map(QFrontendStepMetaData.class::cast)
+                  .collect(Collectors.toList());
+
+               case STATE_MACHINE -> processMetaData.getAllSteps().values().stream()
+                  .filter(QStateMachineStep.class::isInstance)
+                  .map(QStateMachineStep.class::cast)
+                  .flatMap(step -> step.getSubSteps().stream())
+                  .filter(QFrontendStepMetaData.class::isInstance)
+                  .map(QFrontendStepMetaData.class::cast)
+                  .collect(Collectors.toList());
+            };
          }
          else
          {
@@ -84,10 +99,7 @@ public class QFrontendProcessMetaData
          }
       }
 
-      if(processMetaData.getIcon() != null)
+      this.icon = processMetaData.getIcon();
-      {
-         this.iconName = processMetaData.getIcon().getName();
-      }
 
       hasPermission = PermissionsHelper.hasProcessPermission(actionInput, name);
    }
@@ -166,7 +178,7 @@ public class QFrontendProcessMetaData
     *******************************************************************************/
    public String getIconName()
    {
-      return iconName;
+      return icon == null ? null : icon.getName();
    }
 
 
@@ -180,4 +192,25 @@ public class QFrontendProcessMetaData
       return hasPermission;
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for stepFlow
+    **
+    *******************************************************************************/
+   public String getStepFlow()
+   {
+      return stepFlow;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for icon
+    **
+    *******************************************************************************/
+   public QIcon getIcon()
+   {
+      return icon;
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/frontend/QFrontendTableMetaData.java

@@ -24,7 +24,7 @@ package com.kingsrook.qqq.backend.core.model.metadata.frontend;
 
 import java.util.ArrayList;
 import java.util.HashMap;
-import java.util.HashSet;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -40,6 +40,7 @@ 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.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 import com.kingsrook.qqq.backend.core.model.metadata.sharing.ShareableTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.Capability;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.ExposedJoin;
@@ -61,7 +62,7 @@ public class QFrontendTableMetaData
    private String  label;
    private boolean isHidden;
    private String  primaryKeyField;
-   private String  iconName;
+   private QIcon   icon;
 
    private Map<String, QFrontendFieldMetaData>     fields;
    private List<QFieldSection>                     sections;
@@ -156,10 +157,7 @@ public class QFrontendTableMetaData
          }
       }
 
-      if(tableMetaData.getIcon() != null)
+      this.icon = tableMetaData.getIcon();
-      {
-         this.iconName = tableMetaData.getIcon().getName();
-      }
 
       setCapabilities(backendForTable, tableMetaData);
 
@@ -185,7 +183,7 @@ public class QFrontendTableMetaData
     *******************************************************************************/
    private void setCapabilities(QBackendMetaData backend, QTableMetaData table)
    {
-      Set<Capability> enabledCapabilities = new HashSet<>();
+      Set<Capability> enabledCapabilities = new LinkedHashSet<>();
       for(Capability capability : Capability.values())
       {
          if(table.isCapabilityEnabled(backend, capability))
@@ -275,7 +273,7 @@ public class QFrontendTableMetaData
     *******************************************************************************/
    public String getIconName()
    {
-      return iconName;
+      return (icon == null ? null : icon.getName());
    }
 
 
@@ -397,4 +395,16 @@ public class QFrontendTableMetaData
    {
       return helpContents;
    }
+
+
+
+   /*******************************************************************************
+    ** Getter for icon
+    **
+    *******************************************************************************/
+   public QIcon getIcon()
+   {
+      return icon;
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/possiblevalues/PossibleValueSearchFilterUseCase.java

@@ -0,0 +1,72 @@
+/*
+ * 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.model.metadata.possiblevalues;
+
+
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.CriteriaMissingInputValueBehavior;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.FilterUseCase;
+
+
+/*******************************************************************************
+ ** FilterUseCase implementation for the ways that possible value searches
+ ** are performed, and where we want to have different behaviors for criteria
+ ** that are missing an input value.  That is, either for a:
+ **
+ ** - FORM - e.g., creating a new record, or in a process - where we want a
+ ** missing filter value to basically block you from selecting a value in the
+ ** PVS field - e.g., you must enter some other foreign-key value before choosing
+ ** from this possible value - at least that's the use-case we know of now.
+ **
+ ** - FILTER - e.g., a query screen - where there isn't really quite the same
+ ** scenario of choosing that foreign-key value first - so, such a PVS should
+ ** list all its values (e.g., a criteria missing an input value should be
+ ** removed from the filter).
+ *******************************************************************************/
+public enum PossibleValueSearchFilterUseCase implements FilterUseCase
+{
+   FORM(CriteriaMissingInputValueBehavior.MAKE_NO_MATCHES),
+   FILTER(CriteriaMissingInputValueBehavior.REMOVE_FROM_FILTER);
+
+
+   private final CriteriaMissingInputValueBehavior defaultCriteriaMissingInputValueBehavior;
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   PossibleValueSearchFilterUseCase(CriteriaMissingInputValueBehavior defaultCriteriaMissingInputValueBehavior)
+   {
+      this.defaultCriteriaMissingInputValueBehavior = defaultCriteriaMissingInputValueBehavior;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for defaultCriteriaMissingInputValueBehavior
+    **
+    *******************************************************************************/
+   public CriteriaMissingInputValueBehavior getDefaultCriteriaMissingInputValueBehavior()
+   {
+      return defaultCriteriaMissingInputValueBehavior;
+   }
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/processes/ProcessStepFlow.java

@@ -0,0 +1,38 @@
+/*
+ * 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.model.metadata.processes;
+
+
+/*******************************************************************************
+ ** Possible ways the steps of a process can flow.
+ **
+ ** LINEAR - (the default) - the list of steps in the process are executed in-order
+ **
+ ** STATE_MACHINE - concept of "states", each which has a backend & frontend step;
+ ** a backend step can (must?) set the field "stepState" (or "nextStepName") to
+ ** say what the next (frontend) step is.
+ *******************************************************************************/
+public enum ProcessStepFlow
+{
+   LINEAR,
+   STATE_MACHINE
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/processes/QFrontendStepMetaData.java

@@ -47,6 +47,8 @@ public class QFrontendStepMetaData extends QStepMetaData
    private List<QFieldMetaData>             recordListFields;
    private Map<String, QFieldMetaData>      formFieldMap;
 
+   private String format;
+
    private List<QHelpContent> helpContents;
 
 
@@ -403,4 +405,35 @@ public class QFrontendStepMetaData extends QStepMetaData
       QInstanceHelpContentManager.removeHelpContentByRoleSetFromList(roles, this.helpContents);
    }
 
+
+   /*******************************************************************************
+    ** Getter for format
+    *******************************************************************************/
+   public String getFormat()
+   {
+      return (this.format);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for format
+    *******************************************************************************/
+   public void setFormat(String format)
+   {
+      this.format = format;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for format
+    *******************************************************************************/
+   public QFrontendStepMetaData withFormat(String format)
+   {
+      this.format = format;
+      return (this);
+   }
+
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/processes/QProcessMetaData.java

@@ -57,6 +57,7 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
    private Integer minInputRecords = null;
    private Integer maxInputRecords = null;
 
+   private ProcessStepFlow            stepFlow = ProcessStepFlow.LINEAR;
    private List<QStepMetaData>        stepList; // these are the steps that are ran, by-default, in the order they are ran in
    private Map<String, QStepMetaData> steps; // this is the full map of possible steps
 
@@ -213,11 +214,10 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
 
 
 
-   /*******************************************************************************
+   /***************************************************************************
-    ** add a step to the stepList and map
     **
-    *******************************************************************************/
+    ***************************************************************************/
-   public QProcessMetaData addStep(QStepMetaData step)
+   public QProcessMetaData withStep(QStepMetaData step)
    {
       int index = 0;
       if(this.stepList != null)
@@ -231,11 +231,23 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
 
 
 
+   /*******************************************************************************
+    ** add a step to the stepList and map
+    **
+    *******************************************************************************/
+   @Deprecated(since = "withStep was added")
+   public QProcessMetaData addStep(QStepMetaData step)
+   {
+      return (withStep(step));
+   }
+
+
+
    /*******************************************************************************
     ** add a step to the stepList (at the specified index) and the step map
     **
     *******************************************************************************/
-   public QProcessMetaData addStep(int index, QStepMetaData step)
+   public QProcessMetaData withStep(int index, QStepMetaData step)
    {
       if(this.stepList == null)
       {
@@ -260,11 +272,23 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
 
 
 
+   /*******************************************************************************
+    ** add a step to the stepList (at the specified index) and the step map
+    **
+    *******************************************************************************/
+   @Deprecated(since = "withStep was added")
+   public QProcessMetaData addStep(int index, QStepMetaData step)
+   {
+      return (withStep(index, step));
+   }
+
+
+
    /*******************************************************************************
     ** add a step ONLY to the step map - NOT the list w/ default execution order.
     **
     *******************************************************************************/
-   public QProcessMetaData addOptionalStep(QStepMetaData step)
+   public QProcessMetaData withOptionalStep(QStepMetaData step)
    {
       if(this.steps == null)
       {
@@ -283,6 +307,18 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
 
 
 
+   /*******************************************************************************
+    ** add a step ONLY to the step map - NOT the list w/ default execution order.
+    **
+    *******************************************************************************/
+   @Deprecated(since = "withOptionalStep was added")
+   public QProcessMetaData addOptionalStep(QStepMetaData step)
+   {
+      return (withOptionalStep(step));
+   }
+
+
+
    /*******************************************************************************
     ** Setter for stepList
     **
@@ -299,7 +335,26 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
     *******************************************************************************/
    public QStepMetaData getStep(String stepName)
    {
-      return (steps.get(stepName));
+      if(steps.containsKey(stepName))
+      {
+         return steps.get(stepName);
+      }
+
+      for(QStepMetaData step : steps.values())
+      {
+         if(step instanceof QStateMachineStep stateMachineStep)
+         {
+            for(QStepMetaData subStep : stateMachineStep.getSubSteps())
+            {
+               if(subStep.getName().equals(stepName))
+               {
+                  return (subStep);
+               }
+            }
+         }
+      }
+
+      return (null);
    }
 
 
@@ -780,4 +835,35 @@ public class QProcessMetaData implements QAppChildMetaData, MetaDataWithPermissi
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for stepFlow
+    *******************************************************************************/
+   public ProcessStepFlow getStepFlow()
+   {
+      return (this.stepFlow);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for stepFlow
+    *******************************************************************************/
+   public void setStepFlow(ProcessStepFlow stepFlow)
+   {
+      this.stepFlow = stepFlow;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for stepFlow
+    *******************************************************************************/
+   public QProcessMetaData withStepFlow(ProcessStepFlow stepFlow)
+   {
+      this.stepFlow = stepFlow;
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/processes/QStateMachineStep.java

@@ -0,0 +1,188 @@
+/*
+ * 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.model.metadata.processes;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** A step for a state-machine flow based Process.
+ **
+ ** Consists of 1 or 2 sub-steps, which are frontend and/or backend.
+ *******************************************************************************/
+public class QStateMachineStep extends QStepMetaData
+{
+   private List<QStepMetaData> subSteps = new ArrayList<>();
+
+   private String defaultNextStepName;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   private QStateMachineStep(List<QStepMetaData> subSteps)
+   {
+      setStepType("stateMachine");
+      this.subSteps.addAll(subSteps);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static QStateMachineStep frontendOnly(String name, QFrontendStepMetaData frontendStepMetaData)
+   {
+      if(!StringUtils.hasContent(frontendStepMetaData.getName()))
+      {
+         frontendStepMetaData.setName(name + ".frontend");
+      }
+
+      return (new QStateMachineStep(List.of(frontendStepMetaData)).withName(name));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static QStateMachineStep backendOnly(String name, QBackendStepMetaData backendStepMetaData)
+   {
+      if(!StringUtils.hasContent(backendStepMetaData.getName()))
+      {
+         backendStepMetaData.setName(name + ".backend");
+      }
+
+      return (new QStateMachineStep(List.of(backendStepMetaData)).withName(name));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static QStateMachineStep frontendThenBackend(String name, QFrontendStepMetaData frontendStepMetaData, QBackendStepMetaData backendStepMetaData)
+   {
+      if(!StringUtils.hasContent(frontendStepMetaData.getName()))
+      {
+         frontendStepMetaData.setName(name + ".frontend");
+      }
+
+      if(!StringUtils.hasContent(backendStepMetaData.getName()))
+      {
+         backendStepMetaData.setName(name + ".backend");
+      }
+
+      return (new QStateMachineStep(List.of(frontendStepMetaData, backendStepMetaData)).withName(name));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QStateMachineStep withName(String name)
+   {
+      super.withName(name);
+      return (this);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public QStateMachineStep withLabel(String label)
+   {
+      super.withLabel(label);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for subSteps
+    **
+    *******************************************************************************/
+   public List<QStepMetaData> getSubSteps()
+   {
+      return subSteps;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for defaultNextStepName
+    *******************************************************************************/
+   public String getDefaultNextStepName()
+   {
+      return (this.defaultNextStepName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for defaultNextStepName
+    *******************************************************************************/
+   public void setDefaultNextStepName(String defaultNextStepName)
+   {
+      this.defaultNextStepName = defaultNextStepName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for defaultNextStepName
+    *******************************************************************************/
+   public QStateMachineStep withDefaultNextStepName(String defaultNextStepName)
+   {
+      this.defaultNextStepName = defaultNextStepName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Get a list of all of the input fields used by this step (all of its sub-steps)
+    *******************************************************************************/
+   @JsonIgnore
+   @Override
+   public List<QFieldMetaData> getInputFields()
+   {
+      List<QFieldMetaData> rs = new ArrayList<>();
+      for(QStepMetaData subStep : subSteps)
+      {
+         rs.addAll(subStep.getInputFields());
+      }
+      return (rs);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/metadata/sharing/ShareScopePossibleValueMetaDataProducer.java

@@ -23,7 +23,7 @@ package com.kingsrook.qqq.backend.core.model.metadata.sharing;
 
 
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
 import com.kingsrook.qqq.backend.core.processes.implementations.sharing.ShareScope;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/model/savedreports/ScheduledReportSyncToScheduledJobProcess.java

@@ -26,13 +26,13 @@ import java.io.Serializable;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportFormatPossibleValueEnum;
 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.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
@@ -114,7 +114,7 @@ public class ScheduledReportSyncToScheduledJobProcess extends AbstractTableSyncT
          scheduledJob = new ScheduledJob();
          scheduledJob.setLabel("Scheduled Report " + scheduledReport.getId());
          scheduledJob.setDescription("Job to run Scheduled Report Id " + scheduledReport.getId()
-            + " (which runs Report Id " + scheduledReport.getSavedReportId() + ")");
+                                     + " (which runs Report Id " + scheduledReport.getSavedReportId() + ")");
          scheduledJob.setSchedulerName(runBackendStepInput.getValueString(SCHEDULER_NAME_FIELD_NAME));
          scheduledJob.setType(ScheduledJobType.PROCESS.name());
          scheduledJob.setForeignKeyType(getScheduledJobForeignKeyType());

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/modules/authentication/implementations/Auth0AuthenticationModule.java

@@ -247,10 +247,7 @@ public class Auth0AuthenticationModule implements QAuthenticationModuleInterface
             //////////////////////////////////////////////////////////////
             // allow customizer to do custom things here, if so desired //
             //////////////////////////////////////////////////////////////
-            if(getCustomizer() != null)
+            finalCustomizeSession(qInstance, qSession);
-            {
-               getCustomizer().finalCustomizeSession(qInstance, qSession);
-            }
 
             return (qSession);
          }
@@ -311,10 +308,7 @@ public class Auth0AuthenticationModule implements QAuthenticationModuleInterface
          //////////////////////////////////////////////////////////////
          // allow customizer to do custom things here, if so desired //
          //////////////////////////////////////////////////////////////
-         if(getCustomizer() != null)
+         finalCustomizeSession(qInstance, qSession);
-         {
-            getCustomizer().finalCustomizeSession(qInstance, qSession);
-         }
 
          return (qSession);
       }
@@ -360,6 +354,23 @@ public class Auth0AuthenticationModule implements QAuthenticationModuleInterface
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void finalCustomizeSession(QInstance qInstance, QSession qSession)
+   {
+      if(getCustomizer() != null)
+      {
+         QContext.withTemporaryContext(QContext.capture(), () ->
+         {
+            QContext.setQSession(getChickenAndEggSession());
+            getCustomizer().finalCustomizeSession(qInstance, qSession);
+         });
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Insert a session as a new record into userSession table
     *******************************************************************************/

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/modules/backend/implementations/memory/MemoryRecordStore.java

@@ -58,6 +58,7 @@ 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.query.JoinsContext;
 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.QueryJoin;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
@@ -170,6 +171,8 @@ public class MemoryRecordStore
       Collection<QRecord> tableData = getTableData(input.getTable()).values();
       List<QRecord>       records   = new ArrayList<>();
 
+      QQueryFilter filter       = clonedOrNewFilter(input.getFilter());
+      JoinsContext joinsContext = new JoinsContext(QContext.getQInstance(), input.getTableName(), input.getQueryJoins(), filter);
       if(CollectionUtils.nullSafeHasContents(input.getQueryJoins()))
       {
          tableData = buildJoinCrossProduct(input);
@@ -185,7 +188,7 @@ public class MemoryRecordStore
             qRecord.setTableName(input.getTableName());
          }
 
-         boolean recordMatches = BackendQueryFilterUtils.doesRecordMatch(input.getFilter(), qRecord);
+         boolean recordMatches = BackendQueryFilterUtils.doesRecordMatch(input.getFilter(), joinsContext, qRecord);
 
          if(recordMatches)
          {
@@ -224,8 +227,7 @@ public class MemoryRecordStore
     *******************************************************************************/
    private Collection<QRecord> buildJoinCrossProduct(QueryInput input) throws QException
    {
-      QInstance    qInstance    = QContext.getQInstance();
+      QInstance qInstance = QContext.getQInstance();
-      JoinsContext joinsContext = new JoinsContext(qInstance, input.getTableName(), input.getQueryJoins(), input.getFilter());
 
       List<QRecord>  crossProduct = new ArrayList<>();
       QTableMetaData leftTable    = input.getTable();
@@ -373,7 +375,14 @@ public class MemoryRecordStore
          /////////////////////////////////////////////////
          if(recordToInsert.getValue(primaryKeyField.getName()) == null && (primaryKeyField.getType().equals(QFieldType.INTEGER) || primaryKeyField.getType().equals(QFieldType.LONG)))
          {
-            recordToInsert.setValue(primaryKeyField.getName(), nextSerial++);
+            if(primaryKeyField.getType().equals(QFieldType.LONG))
+            {
+               recordToInsert.setValue(primaryKeyField.getName(), (nextSerial++).longValue());
+            }
+            else
+            {
+               recordToInsert.setValue(primaryKeyField.getName(), nextSerial++);
+            }
          }
 
          ///////////////////////////////////////////////////////////////////////////////////////////////////
@@ -383,7 +392,7 @@ public class MemoryRecordStore
          {
             nextSerial = recordToInsert.getValueInteger(primaryKeyField.getName()) + 1;
          }
-         else if(primaryKeyField.getType().equals(QFieldType.LONG) && recordToInsert.getValueLong(primaryKeyField.getName()) > nextSerial)
+         else if(primaryKeyField.getType().equals(QFieldType.LONG) && recordToInsert.getValueInteger(primaryKeyField.getName()) > nextSerial)
          {
             //////////////////////////////////////
             // todo - mmm, could overflow here? //
@@ -901,4 +910,21 @@ public class MemoryRecordStore
 
       return ValueUtils.getValueAsFieldType(fieldType, aggregateValue);
    }
+
+
+
+   /*******************************************************************************
+    ** Either clone the input filter (so we can change it safely), or return a new blank filter.
+    *******************************************************************************/
+   protected QQueryFilter clonedOrNewFilter(QQueryFilter filter)
+   {
+      if(filter == null)
+      {
+         return (new QQueryFilter());
+      }
+      else
+      {
+         return (filter.clone());
+      }
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/modules/backend/implementations/utils/BackendQueryFilterUtils.java

@@ -34,14 +34,18 @@ import java.util.Objects;
 import java.util.concurrent.atomic.AtomicBoolean;
 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.query.JoinsContext;
 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.expressions.AbstractFilterExpression;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+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.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 import org.apache.commons.lang.NotImplementedException;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -58,8 +62,22 @@ public class BackendQueryFilterUtils
 
    /*******************************************************************************
     ** Test if record matches filter.
-    *******************************************************************************/
+    ******************************************************************************/
    public static boolean doesRecordMatch(QQueryFilter filter, QRecord qRecord)
+   {
+      return doesRecordMatch(filter, null, qRecord);
+   }
+
+
+
+   /*******************************************************************************
+    ** Test if record matches filter - where we are executing a QueryAction, and
+    ** we have a JoinsContext.  Note, if you don't have one of those, you can call
+    ** the overload of this method that doesn't take one, and everything downstream
+    ** /should/ be tolerant of that being absent...  You just might not have the
+    ** benefit of things like knowing field-meta-data associated with criteria...
+    *******************************************************************************/
+   public static boolean doesRecordMatch(QQueryFilter filter, JoinsContext joinsContext, QRecord qRecord)
    {
       if(filter == null || !filter.hasAnyCriteria())
       {
@@ -97,7 +115,36 @@ public class BackendQueryFilterUtils
             }
          }
 
-         boolean criterionMatches = doesCriteriaMatch(criterion, fieldName, value);
+         ///////////////////////////////////////////////////////////////////////////////////////////////
+         // Test if this criteria(on) matches the record.                                             //
+         // As criteria have become more sophisticated over time, we would like to be able to know    //
+         // what field they are for. In general, we'll try to get that from the query's JoinsContext. //
+         // But, in some scenarios, that isn't available - so - be safe and defer to simpler methods  //
+         // that might not have the full field, when necessary.                                       //
+         ///////////////////////////////////////////////////////////////////////////////////////////////
+         Boolean criterionMatches = null;
+         if(joinsContext != null)
+         {
+            JoinsContext.FieldAndTableNameOrAlias fieldAndTableNameOrAlias = null;
+            try
+            {
+               fieldAndTableNameOrAlias = joinsContext.getFieldAndTableNameOrAlias(criterion.getFieldName());
+            }
+            catch(Exception e)
+            {
+               LOG.debug("Exception getting field from joinsContext", e, logPair("fieldName", criterion.getFieldName()));
+            }
+
+            if(fieldAndTableNameOrAlias != null)
+            {
+               criterionMatches = doesCriteriaMatch(criterion, fieldAndTableNameOrAlias.field(), value);
+            }
+         }
+
+         if(criterionMatches == null)
+         {
+            criterionMatches = doesCriteriaMatch(criterion, criterion.getFieldName(), value);
+         }
 
          ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          // add this new value to the existing recordMatches value - and if we can short circuit the remaining checks, do so. //
@@ -131,11 +178,24 @@ public class BackendQueryFilterUtils
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static boolean doesCriteriaMatch(QFilterCriteria criterion, String fieldName, Serializable value)
+   {
+      QFieldMetaData field = new QFieldMetaData(fieldName, ValueUtils.inferQFieldTypeFromValue(value, QFieldType.STRING));
+      return doesCriteriaMatch(criterion, field, value);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
-   public static boolean doesCriteriaMatch(QFilterCriteria criterion, String fieldName, Serializable value)
+   private static boolean doesCriteriaMatch(QFilterCriteria criterion, QFieldMetaData field, Serializable value)
    {
+      String fieldName = field == null ? "__unknownField" : field.getName();
+
       ListIterator<Serializable> valueListIterator = criterion.getValues().listIterator();
       while(valueListIterator.hasNext())
       {
@@ -144,7 +204,7 @@ public class BackendQueryFilterUtils
          {
             try
             {
-               valueListIterator.set(expression.evaluate());
+               valueListIterator.set(expression.evaluate(field));
             }
             catch(QException qe)
             {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/automation/HealBadRecordAutomationStatusesProcessStep.java

@@ -36,7 +36,6 @@ 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.MetaDataProducerInterface;
 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;
@@ -47,6 +46,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.NowWithOffset;
 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.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.HtmlWrapper;
@@ -158,8 +158,8 @@ public class HealBadRecordAutomationStatusesProcessStep implements BackendStep,
    @Override
    public void run(RunBackendStepInput runBackendStepInput, RunBackendStepOutput runBackendStepOutput) throws QException
    {
-      int recordsUpdated = 0;
+      int     recordsUpdated = 0;
-      boolean isReview = "preview".equals(runBackendStepInput.getStepName());
+      boolean isReview       = "preview".equals(runBackendStepInput.getStepName());
 
       ////////////////////////////////////////////////////////////////////////
       // if a table name is given, validate it, and run for just that table //

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/automation/RunTableAutomationsProcessStep.java

@@ -28,9 +28,9 @@ import com.kingsrook.qqq.backend.core.actions.automation.polling.PollingAutomati
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.automation.QAutomationProviderMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/basepull/ExtractViaBasepullQueryStep.java

@@ -40,6 +40,10 @@ import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwith
  *******************************************************************************/
 public class ExtractViaBasepullQueryStep extends ExtractViaQueryStep implements BasepullExtractStepInterface
 {
+   protected static final String SECONDS_TO_SUBTRACT_FROM_THIS_RUN_TIME_KEY = "secondsToSubtractFromThisRunTimeForTimestampQuery";
+   protected static final String SECONDS_TO_SUBTRACT_FROM_LAST_RUN_TIME_KEY = "secondsToSubtractFromLastRunTimeForTimestampQuery";
+
+
 
    /*******************************************************************************
     **
@@ -124,7 +128,8 @@ public class ExtractViaBasepullQueryStep extends ExtractViaQueryStep implements
     *******************************************************************************/
    protected String getLastRunTimeString(RunBackendStepInput runBackendStepInput) throws QException
    {
-      Instant lastRunTime = runBackendStepInput.getBasepullLastRunTime();
+      Instant lastRunTime    = runBackendStepInput.getBasepullLastRunTime();
+      Instant updatedRunTime = lastRunTime;
 
       //////////////////////////////////////////////////////////////////////////////////////////////
       // allow the timestamps to be adjusted by the specified number of seconds.                  //
@@ -135,10 +140,19 @@ public class ExtractViaBasepullQueryStep extends ExtractViaQueryStep implements
       Serializable basepullConfigurationValue = runBackendStepInput.getValue(RunProcessAction.BASEPULL_CONFIGURATION);
       if(basepullConfigurationValue instanceof BasepullConfiguration basepullConfiguration && basepullConfiguration.getSecondsToSubtractFromLastRunTimeForTimestampQuery() != null)
       {
-         lastRunTime = lastRunTime.minusSeconds(basepullConfiguration.getSecondsToSubtractFromLastRunTimeForTimestampQuery());
+         updatedRunTime = lastRunTime.minusSeconds(basepullConfiguration.getSecondsToSubtractFromLastRunTimeForTimestampQuery());
       }
 
-      return (lastRunTime.toString());
+      //////////////////////////////////////////////////////////////
+      // if an override was found in the params, use that instead //
+      //////////////////////////////////////////////////////////////
+      if(runBackendStepInput.getValueString(SECONDS_TO_SUBTRACT_FROM_LAST_RUN_TIME_KEY) != null)
+      {
+         int secondsBack = Integer.parseInt(runBackendStepInput.getValueString(SECONDS_TO_SUBTRACT_FROM_LAST_RUN_TIME_KEY));
+         updatedRunTime = lastRunTime.minusSeconds(secondsBack);
+      }
+
+      return (updatedRunTime.toString());
    }
 
 
@@ -148,14 +162,24 @@ public class ExtractViaBasepullQueryStep extends ExtractViaQueryStep implements
     *******************************************************************************/
    protected String getThisRunTimeString(RunBackendStepInput runBackendStepInput) throws QException
    {
-      Instant thisRunTime = runBackendStepInput.getValueInstant(RunProcessAction.BASEPULL_THIS_RUNTIME_KEY);
+      Instant thisRunTime    = runBackendStepInput.getValueInstant(RunProcessAction.BASEPULL_THIS_RUNTIME_KEY);
+      Instant updatedRunTime = thisRunTime;
 
       Serializable basepullConfigurationValue = runBackendStepInput.getValue(RunProcessAction.BASEPULL_CONFIGURATION);
       if(basepullConfigurationValue instanceof BasepullConfiguration basepullConfiguration && basepullConfiguration.getSecondsToSubtractFromThisRunTimeForTimestampQuery() != null)
       {
-         thisRunTime = thisRunTime.minusSeconds(basepullConfiguration.getSecondsToSubtractFromThisRunTimeForTimestampQuery());
+         updatedRunTime = thisRunTime.minusSeconds(basepullConfiguration.getSecondsToSubtractFromThisRunTimeForTimestampQuery());
       }
 
-      return (thisRunTime.toString());
+      //////////////////////////////////////////////////////////////
+      // if an override was found in the params, use that instead //
+      //////////////////////////////////////////////////////////////
+      if(runBackendStepInput.getValueString(SECONDS_TO_SUBTRACT_FROM_THIS_RUN_TIME_KEY) != null)
+      {
+         int secondsBack = Integer.parseInt(runBackendStepInput.getValueString(SECONDS_TO_SUBTRACT_FROM_THIS_RUN_TIME_KEY));
+         updatedRunTime = thisRunTime.minusSeconds(secondsBack);
+      }
+
+      return (updatedRunTime.toString());
    }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/etl/streamedwithfrontend/StreamedETLExecuteStep.java

@@ -176,9 +176,9 @@ public class StreamedETLExecuteStep extends BaseStreamedETLStep implements Backe
          //////////////////////////////////////////////////////////////////////
          // propagate data from inner-step state to process-level step state //
          //////////////////////////////////////////////////////////////////////
-         if(postRunOutput.getUpdatedFrontendStepList() != null)
+         if(postRunOutput.getProcessMetaDataAdjustment() != null)
          {
-            runBackendStepOutput.setUpdatedFrontendStepList(postRunOutput.getUpdatedFrontendStepList());
+            runBackendStepOutput.setProcessMetaDataAdjustment(postRunOutput.getProcessMetaDataAdjustment());
          }
 
          /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -281,10 +281,10 @@ public class StreamedETLExecuteStep extends BaseStreamedETLStep implements Backe
          //////////////////////////////////////////////////////////////////////
          // propagate data from inner-step state to process-level step state //
          //////////////////////////////////////////////////////////////////////
-         if(streamedBackendStepOutput.getUpdatedFrontendStepList() != null)
+         if(streamedBackendStepOutput.getProcessMetaDataAdjustment() != null)
          {
             runBackendStepOutput.getProcessState().setStepList(streamedBackendStepOutput.getProcessState().getStepList());
-            runBackendStepOutput.setUpdatedFrontendStepList(streamedBackendStepOutput.getUpdatedFrontendStepList());
+            runBackendStepOutput.getProcessState().setProcessMetaDataAdjustment(streamedBackendStepOutput.getProcessMetaDataAdjustment());
          }
 
          ////////////////////////////////////////////////
@@ -299,10 +299,10 @@ public class StreamedETLExecuteStep extends BaseStreamedETLStep implements Backe
          //////////////////////////////////////////////////////////////////////
          // propagate data from inner-step state to process-level step state //
          //////////////////////////////////////////////////////////////////////
-         if(streamedBackendStepOutput.getUpdatedFrontendStepList() != null)
+         if(streamedBackendStepOutput.getProcessMetaDataAdjustment() != null)
          {
             runBackendStepOutput.getProcessState().setStepList(streamedBackendStepOutput.getProcessState().getStepList());
-            runBackendStepOutput.setUpdatedFrontendStepList(streamedBackendStepOutput.getUpdatedFrontendStepList());
+            runBackendStepOutput.getProcessState().setProcessMetaDataAdjustment(streamedBackendStepOutput.getProcessMetaDataAdjustment());
          }
 
          ///////////////////////////////////////////////////////

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/etl/streamedwithfrontend/StreamedETLPreviewStep.java

@@ -148,9 +148,9 @@ public class StreamedETLPreviewStep extends BaseStreamedETLStep implements Backe
       //////////////////////////////////////////////////////////////////////
       // propagate data from inner-step state to process-level step state //
       //////////////////////////////////////////////////////////////////////
-      if(postRunOutput.getUpdatedFrontendStepList() != null)
+      if(postRunOutput.getProcessMetaDataAdjustment() != null)
       {
-         runBackendStepOutput.setUpdatedFrontendStepList(postRunOutput.getUpdatedFrontendStepList());
+         runBackendStepOutput.setProcessMetaDataAdjustment(postRunOutput.getProcessMetaDataAdjustment());
       }
    }
 
@@ -219,10 +219,9 @@ public class StreamedETLPreviewStep extends BaseStreamedETLStep implements Backe
       //////////////////////////////////////////////////////////////////////
       // propagate data from inner-step state to process-level step state //
       //////////////////////////////////////////////////////////////////////
-      if(streamedBackendStepOutput.getUpdatedFrontendStepList() != null)
+      if(streamedBackendStepOutput.getProcessMetaDataAdjustment() != null)
       {
-         runBackendStepOutput.getProcessState().setStepList(streamedBackendStepOutput.getProcessState().getStepList());
+         runBackendStepOutput.getProcessState().setProcessMetaDataAdjustment(streamedBackendStepOutput.getProcessMetaDataAdjustment());
-         runBackendStepOutput.setUpdatedFrontendStepList(streamedBackendStepOutput.getUpdatedFrontendStepList());
       }
 
       ////////////////////////////////////////////////////

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/etl/streamedwithfrontend/StreamedETLValidateStep.java

@@ -145,9 +145,9 @@ public class StreamedETLValidateStep extends BaseStreamedETLStep implements Back
       //////////////////////////////////////////////////////////////////////
       // propagate data from inner-step state to process-level step state //
       //////////////////////////////////////////////////////////////////////
-      if(postRunOutput.getUpdatedFrontendStepList() != null)
+      if(postRunOutput.getProcessMetaDataAdjustment() != null)
       {
-         runBackendStepOutput.setUpdatedFrontendStepList(postRunOutput.getUpdatedFrontendStepList());
+         runBackendStepOutput.setProcessMetaDataAdjustment(postRunOutput.getProcessMetaDataAdjustment());
       }
    }
 
@@ -183,10 +183,9 @@ public class StreamedETLValidateStep extends BaseStreamedETLStep implements Back
       //////////////////////////////////////////////////////////////////////
       // propagate data from inner-step state to process-level step state //
       //////////////////////////////////////////////////////////////////////
-      if(streamedBackendStepOutput.getUpdatedFrontendStepList() != null)
+      if(streamedBackendStepOutput.getProcessMetaDataAdjustment() != null)
       {
-         runBackendStepOutput.getProcessState().setStepList(streamedBackendStepOutput.getProcessState().getStepList());
+         runBackendStepOutput.setProcessMetaDataAdjustment(streamedBackendStepOutput.getProcessMetaDataAdjustment());
-         runBackendStepOutput.setUpdatedFrontendStepList(streamedBackendStepOutput.getUpdatedFrontendStepList());
       }
 
       ///////////////////////////////////////////////////////

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/savedreports/RenderSavedReportMetaDataProducer.java

@@ -23,10 +23,10 @@ package com.kingsrook.qqq.backend.core.processes.implementations.savedreports;
 
 
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportFormatPossibleValueEnum;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;
@@ -58,7 +58,7 @@ public class RenderSavedReportMetaDataProducer implements MetaDataProducerInterf
    public static final String FIELD_NAME_STORAGE_TABLE_NAME = "storageTableName";
    public static final String FIELD_NAME_REPORT_FORMAT      = "reportFormat";
    public static final String FIELD_NAME_EMAIL_ADDRESS      = "reportDestinationEmailAddress";
-   public static final String FIELD_NAME_EMAIL_SUBJECT = "emailSubject";
+   public static final String FIELD_NAME_EMAIL_SUBJECT      = "emailSubject";
 
 
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/savedreports/RunScheduledReportMetaDataProducer.java

@@ -23,7 +23,7 @@ package com.kingsrook.qqq.backend.core.processes.implementations.savedreports;
 
 
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/sharing/DeleteSharedRecordProcess.java

@@ -27,12 +27,12 @@ import java.util.Objects;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.delete.DeleteInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
@@ -87,9 +87,9 @@ public class DeleteSharedRecordProcess implements BackendStep, MetaDataProducerI
    @Override
    public void run(RunBackendStepInput runBackendStepInput, RunBackendStepOutput runBackendStepOutput) throws QException
    {
-      String tableName        = runBackendStepInput.getValueString("tableName");
+      String  tableName      = runBackendStepInput.getValueString("tableName");
-      String recordIdString   = runBackendStepInput.getValueString("recordId");
+      String  recordIdString = runBackendStepInput.getValueString("recordId");
-      Integer shareId         = runBackendStepInput.getValueInteger("shareId");
+      Integer shareId        = runBackendStepInput.getValueInteger("shareId");
 
       Objects.requireNonNull(tableName, "Missing required input: tableName");
       Objects.requireNonNull(recordIdString, "Missing required input: recordId");

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/sharing/EditSharedRecordProcess.java

@@ -28,12 +28,12 @@ import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 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.model.MetaDataProducerInterface;
 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.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.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/sharing/GetSharedRecordsProcess.java

@@ -37,7 +37,6 @@ import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 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.MetaDataProducerInterface;
 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;
@@ -47,6 +46,7 @@ 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;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
@@ -134,7 +134,7 @@ public class GetSharedRecordsProcess implements BackendStep, MetaDataProducerInt
          //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
          // iterate results, building QRecords to output - note - we'll need to collect ids, then look them up in audience-source tables //
          //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-         ArrayList<QRecord> resultList = new ArrayList<>();
+         ArrayList<QRecord>                resultList  = new ArrayList<>();
          ListingHash<String, Serializable> audienceIds = new ListingHash<>();
          for(QRecord record : queryOutput.getRecords())
          {

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/sharing/InsertSharedRecordProcess.java

@@ -32,13 +32,13 @@ import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.get.GetInput;
 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.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/implementations/tablesync/AbstractTableSyncTransformStep.java

@@ -23,6 +23,9 @@ package com.kingsrook.qqq.backend.core.processes.implementations.tablesync;
 
 
 import java.io.Serializable;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -35,6 +38,7 @@ import java.util.Set;
 import java.util.stream.Collectors;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.values.QPossibleValueTranslator;
+import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
@@ -53,6 +57,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
 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.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
 import com.kingsrook.qqq.backend.core.processes.implementations.general.StandardProcessSummaryLineProducer;
@@ -72,33 +77,33 @@ import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
  *******************************************************************************/
 public abstract class AbstractTableSyncTransformStep extends AbstractTransformStep
 {
-   private static final QLogger LOG = QLogger.getLogger(AbstractTableSyncTransformStep.class);
+   protected static final QLogger LOG = QLogger.getLogger(AbstractTableSyncTransformStep.class);
 
-   private ProcessSummaryLine okToInsert = StandardProcessSummaryLineProducer.getOkToInsertLine();
+   protected ProcessSummaryLine okToInsert = StandardProcessSummaryLineProducer.getOkToInsertLine();
-   private ProcessSummaryLine okToUpdate = StandardProcessSummaryLineProducer.getOkToUpdateLine();
+   protected ProcessSummaryLine okToUpdate = StandardProcessSummaryLineProducer.getOkToUpdateLine();
 
-   private ProcessSummaryLine willNotInsert = new ProcessSummaryLine(Status.INFO)
+   protected ProcessSummaryLine willNotInsert = new ProcessSummaryLine(Status.INFO)
       .withMessageSuffix("because this process is not configured to insert records.")
       .withSingularFutureMessage("will not be inserted ")
       .withPluralFutureMessage("will not be inserted ")
       .withSingularPastMessage("was not inserted ")
       .withPluralPastMessage("were not inserted ");
 
-   private ProcessSummaryLine willNotUpdate = new ProcessSummaryLine(Status.INFO)
+   protected ProcessSummaryLine willNotUpdate = new ProcessSummaryLine(Status.INFO)
       .withMessageSuffix("because this process is not configured to update records.")
       .withSingularFutureMessage("will not be updated ")
       .withPluralFutureMessage("will not be updated ")
       .withSingularPastMessage("was not updated ")
       .withPluralPastMessage("were not updated ");
 
-   private ProcessSummaryLine errorMissingKeyField = new ProcessSummaryLine(Status.ERROR)
+   protected ProcessSummaryLine errorMissingKeyField = new ProcessSummaryLine(Status.ERROR)
       .withMessageSuffix("missing a value for the key field.")
       .withSingularFutureMessage("will not be synced, because it is ")
       .withPluralFutureMessage("will not be synced, because they are ")
       .withSingularPastMessage("was not synced, because it is ")
       .withPluralPastMessage("were not synced, because they are ");
 
-   private ProcessSummaryLine unspecifiedError = new ProcessSummaryLine(Status.ERROR)
+   protected ProcessSummaryLine unspecifiedError = new ProcessSummaryLine(Status.ERROR)
       .withMessageSuffix("of an unexpected error: ")
       .withSingularFutureMessage("will not be synced, ")
       .withPluralFutureMessage("will not be synced, ")
@@ -109,7 +114,11 @@ public abstract class AbstractTableSyncTransformStep extends AbstractTransformSt
    protected RunBackendStepOutput runBackendStepOutput = null;
    protected RecordLookupHelper   recordLookupHelper   = null;
 
-   private QPossibleValueTranslator possibleValueTranslator;
+   protected QPossibleValueTranslator possibleValueTranslator;
+
+   protected static final String SYNC_TABLE_PERFORM_INSERTS_KEY = "syncTablePerformInsertsKey";
+   protected static final String SYNC_TABLE_PERFORM_UPDATES_KEY = "syncTablePerformUpdatesKey";
+   protected static final String LOG_TRANSFORM_RESULTS          = "logTransformResults";
 
 
 
@@ -214,6 +223,7 @@ public abstract class AbstractTableSyncTransformStep extends AbstractTransformSt
    {
       if(CollectionUtils.nullSafeIsEmpty(runBackendStepInput.getRecords()))
       {
+         LOG.info("No input records were found.");
          return;
       }
 
@@ -222,6 +232,19 @@ public abstract class AbstractTableSyncTransformStep extends AbstractTransformSt
 
       SyncProcessConfig config = getSyncProcessConfig();
 
+      ////////////////////////////////////////////////////////////
+      // see if these fields have been updated via input fields //
+      ////////////////////////////////////////////////////////////
+      if(runBackendStepInput.getValueString(SYNC_TABLE_PERFORM_INSERTS_KEY) != null)
+      {
+         boolean performInserts = Boolean.parseBoolean(runBackendStepInput.getValueString(SYNC_TABLE_PERFORM_INSERTS_KEY));
+         config = new SyncProcessConfig(config.sourceTable, config.sourceTableKeyField, config.destinationTable, config.destinationTableForeignKey, performInserts, config.performUpdates);
+      }
+      if(runBackendStepInput.getValueString(SYNC_TABLE_PERFORM_UPDATES_KEY) != null)
+      {
+         boolean performUpdates = Boolean.parseBoolean(runBackendStepInput.getValueString(SYNC_TABLE_PERFORM_UPDATES_KEY));
+         config = new SyncProcessConfig(config.sourceTable, config.sourceTableKeyField, config.destinationTable, config.destinationTableForeignKey, config.performUpdates, performUpdates);
+      }
       String sourceTableKeyField             = config.sourceTableKeyField;
       String destinationTableForeignKeyField = config.destinationTableForeignKey;
       String destinationTableName            = config.destinationTable;
@@ -371,9 +394,63 @@ public abstract class AbstractTableSyncTransformStep extends AbstractTransformSt
             possibleValueTranslator.translatePossibleValuesInRecords(QContext.getQInstance().getTable(destinationTableName), runBackendStepOutput.getRecords());
          }
       }
+
+      if(Boolean.parseBoolean(runBackendStepInput.getValueString(LOG_TRANSFORM_RESULTS)))
+      {
+         logResults(runBackendStepInput, config);
+      }
    }
 
 
+
+   /*******************************************************************************
+    ** Log results of transformation
+    **
+    *******************************************************************************/
+   protected void logResults(RunBackendStepInput runBackendStepInput, SyncProcessConfig syncProcessConfig)
+   {
+      String timezone = QContext.getQSession().getValue(QSession.VALUE_KEY_USER_TIMEZONE);
+      if(timezone == null)
+      {
+         timezone = QContext.getQInstance().getDefaultTimeZoneId();
+      }
+      Instant lastRunTime = Instant.now();
+      if(runBackendStepInput.getBasepullLastRunTime() != null)
+      {
+         lastRunTime = runBackendStepInput.getBasepullLastRunTime();
+      }
+
+      ZonedDateTime dateTime = lastRunTime.atZone(ZoneId.of(timezone));
+
+      if(syncProcessConfig.performInserts)
+      {
+         if(okToInsert.getCount() == 0)
+         {
+            LOG.info("No Records were found to insert since " + QValueFormatter.formatDateTimeWithZone(dateTime) + ".");
+         }
+         else
+         {
+            String pluralized = okToInsert.getCount() > 1 ? " Records were " : " Record was ";
+            LOG.info(okToInsert.getCount() + pluralized + " found to insert since " + QValueFormatter.formatDateTimeWithZone(dateTime) + ".", logPair("primaryKeys", okToInsert.getPrimaryKeys()));
+         }
+      }
+
+      if(syncProcessConfig.performUpdates)
+      {
+         if(okToUpdate.getCount() == 0)
+         {
+            LOG.info("No Records were found to update since " + QValueFormatter.formatDateTimeWithZone(dateTime) + ".");
+         }
+         else
+         {
+            String pluralized = okToUpdate.getCount() > 1 ? " Records were " : " Record was ";
+            LOG.info(okToUpdate.getCount() + pluralized + " found to update since " + QValueFormatter.formatDateTimeWithZone(dateTime) + ".", logPair("primaryKeys", okToInsert.getPrimaryKeys()));
+         }
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Given a source record, extract what we'll use as its key from it.
     **

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/processes/locks/ProcessLockMetaDataProducer.java

@@ -24,7 +24,7 @@ package com.kingsrook.qqq.backend.core.processes.locks;
 
 import java.util.List;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/processes/RescheduleAllJobsProcess.java

@@ -25,9 +25,9 @@ package com.kingsrook.qqq.backend.core.scheduler.processes;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/processes/ScheduleAllNewJobsProcess.java

@@ -25,9 +25,9 @@ package com.kingsrook.qqq.backend.core.scheduler.processes;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/processes/UnscheduleAllJobsProcess.java

@@ -25,9 +25,9 @@ package com.kingsrook.qqq.backend.core.scheduler.processes;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/quartz/processes/PauseAllQuartzJobsProcess.java

@@ -25,9 +25,9 @@ package com.kingsrook.qqq.backend.core.scheduler.quartz.processes;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/quartz/processes/PauseQuartzJobsProcess.java

@@ -25,10 +25,10 @@ package com.kingsrook.qqq.backend.core.scheduler.quartz.processes;
 import java.util.List;
 import java.util.function.BiFunction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/quartz/processes/ResumeAllQuartzJobsProcess.java

@@ -25,9 +25,9 @@ package com.kingsrook.qqq.backend.core.scheduler.quartz.processes;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetHtmlLine;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/scheduler/quartz/processes/ResumeQuartzJobsProcess.java

@@ -25,10 +25,10 @@ package com.kingsrook.qqq.backend.core.scheduler.quartz.processes;
 import java.util.List;
 import java.util.function.BiFunction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.MetaDataProducerInterface;
 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.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/utils/ClassPathUtils.java

@@ -0,0 +1,87 @@
+/*
+ * 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.utils;
+
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.reflect.ClassPath;
+
+
+/*******************************************************************************
+ ** Utilities for reading classes - e.g., finding all in a package
+ *******************************************************************************/
+@SuppressWarnings("ALL") // the api we're using here, from google, is marked Beta
+public class ClassPathUtils
+{
+   private static ImmutableSet<ClassPath.ClassInfo> topLevelClasses;
+
+
+
+   /*******************************************************************************
+    ** from https://stackoverflow.com/questions/520328/can-you-find-all-classes-in-a-package-using-reflection
+    **
+    *******************************************************************************/
+   public static List<Class<?>> getClassesInPackage(String packageName) throws IOException
+   {
+      List<Class<?>> classes = new ArrayList<>();
+      ClassLoader    loader  = Thread.currentThread().getContextClassLoader();
+
+      for(ClassPath.ClassInfo info : getTopLevelClasses(loader))
+      {
+         if(info.getName().startsWith(packageName))
+         {
+            classes.add(info.load());
+         }
+      }
+
+      return (classes);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static ImmutableSet<ClassPath.ClassInfo> getTopLevelClasses(ClassLoader loader) throws IOException
+   {
+      if(topLevelClasses == null)
+      {
+         topLevelClasses = ClassPath.from(loader).getTopLevelClasses();
+      }
+
+      return (topLevelClasses);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void clearTopLevelClassCache()
+   {
+      topLevelClasses = null;
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/utils/CountingHash.java

@@ -94,6 +94,29 @@ public class CountingHash<K extends Serializable> extends AbstractMap<K, Integer
 
 
 
+   /*******************************************************************************
+    ** increment the value for the specified key
+    **
+    *******************************************************************************/
+   public Integer put(K key)
+   {
+      return (add(key));
+   }
+
+
+
+   /*******************************************************************************
+    ** Set the value for the specified key by the supplied value
+    **
+    *******************************************************************************/
+   public Integer put(K key, Integer value)
+   {
+      this.map.put(key, value);
+      return (value);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/utils/ValueUtils.java

@@ -41,6 +41,7 @@ import java.util.List;
 import java.util.TimeZone;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QValueException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.PossibleValueEnum;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
@@ -51,6 +52,8 @@ import com.kingsrook.qqq.backend.core.model.session.QSession;
  *******************************************************************************/
 public class ValueUtils
 {
+   private static final QLogger LOG = QLogger.getLogger(ValueUtils.class);
+
    private static final DateTimeFormatter dateTimeFormatter_yyyyMMddWithDashes = DateTimeFormatter.ofPattern("yyyy-MM-dd");
    private static final DateTimeFormatter dateTimeFormatter_MdyyyyWithSlashes  = DateTimeFormatter.ofPattern("M/d/yyyy");
    private static final DateTimeFormatter dateTimeFormatter_yyyyMMdd           = DateTimeFormatter.ofPattern("yyyyMMdd");
@@ -931,4 +934,48 @@ public class ValueUtils
       return (ZoneId.of(QContext.getQInstance().getDefaultTimeZoneId()));
    }
 
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static QFieldType inferQFieldTypeFromValue(Serializable value, QFieldType defaultIfCannotInfer)
+   {
+      if(value instanceof String)
+      {
+         return QFieldType.STRING;
+      }
+      else if(value instanceof Integer)
+      {
+         return QFieldType.INTEGER;
+      }
+      else if(value instanceof Long)
+      {
+         return QFieldType.LONG;
+      }
+      else if(value instanceof BigDecimal)
+      {
+         return QFieldType.DECIMAL;
+      }
+      else if(value instanceof Boolean)
+      {
+         return QFieldType.BOOLEAN;
+      }
+      else if(value instanceof Instant)
+      {
+         return QFieldType.DATE_TIME;
+      }
+      else if(value instanceof LocalDate)
+      {
+         return QFieldType.DATE;
+      }
+      else if(value instanceof LocalTime)
+      {
+         return QFieldType.TIME;
+      }
+
+      LOG.debug("Could not infer QFieldType from value [" + (value == null ? "null" : value.getClass().getSimpleName()) + "]");
+
+      return defaultIfCannotInfer;
+   }
 }