Test coverage on new javalin routing classes

Feature/migrate sample app to new javalin server

.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."
-   exit 1;
-fi
+############################################################################
+## adjust-pom.version.sh
+## During CircleCI builds - edit the qqq parent pom.xml, to set the
+## <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
-   echo "On a primary branch or tag [${CIRCLE_BRANCH}${CIRCLE_TAG}] - will not edit the pom version.";
+POM=$(dirname $0)/../pom.xml
+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')
-else
-   SLUG=$(echo $CIRCLE_TAG | sed 's/^snapshot-//g')
+##################################################################################
+## ## figure out if we need a SLUG:  a snapshot- tag, or an integration/ branch ##
+##################################################################################
+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"
-sed -i "s/<revision>.*/<revision>$SLUG-SNAPSHOT<\/revision>/" $POM
+echo "Updating $POM -SNAPSHOT to: -$REPLACEMENT"
+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
@@ -114,14 +127,9 @@ commands:
           command: |
             cd docs
             asciidoctor -a docinfo=shared index.adoc
-
-  upload_docs_site:
-    steps:
-      - run:
-          name: scp html to justinsgotskinnylegs.com
-          command: |
-            cd docs
-            scp index.html dkelkhoff@45.79.44.221:/mnt/first-volume/dkelkhoff/nginx/html/justinsgotskinnylegs.com/qqq-docs.html
+      - store_artifacts:
+          path: docs/index.html
+          when: always
 
 jobs:
   mvn_test:
@@ -130,6 +138,7 @@ jobs:
       ## - localstack/startup
       - install_java17
       - mvn_verify
+      - check_middleware_api_versions
 
   mvn_deploy:
     executor: localstack/default
@@ -137,6 +146,7 @@ jobs:
       ## - localstack/startup
       - install_java17
       - mvn_verify
+      - check_middleware_api_versions
       - mvn_jar_deploy
 
   publish_asciidoc:
@@ -144,7 +154,6 @@ jobs:
     steps:
       - install_asciidoctor
       - run_asciidoctor
-      - upload_docs_site
 
 workflows:
   test_only:

docs/Introduction.adoc

@@ -136,17 +136,13 @@ This speaks to the fact that this "code" is not executable code - but rather is
 **** The Filter button in the Query Screen will present a menu listing all fields from the table for the user to build ad-hoc queries against the table.
 The data-types specified for the fields (in the meta-data) dictate what operators QQQ allows the user to use against fields (e.g., Strings offer "contains" vs Numbers offer "greater than").
 **** Values for records from the table will be formatted for presentation based on the meta-data (such as a numeric field being shown with commas if it represents a quantity, or formatted as currency).
-...
-
-[start=2]
-. *Meta Data* - declarative code - java object instances (potentially which could be read from `.yaml` files or other data sources in a future version of QQQ), which tell QQQ about the backend systems, tables, processes, reports, widgets, etc, that make up the application.
-For example:
-* Details about the database you are using, and how to connect to it.
-* A database table's name, fields, their types, its keys, and basic business rules (required fields, read-only fields, field lengths).
-* The description of web API - its URL and authentication mechanism.
-* A table/path within a web API, and the fields returned in the JSON at that endpoint.
-* The specification of a custom workflow (process), including what screens are needed, with input & output values, and references to the custom application code for processing the data.
-* Details about a chart that summarizes data from a table for presentation as a dashboard widget.
+* Other kinds of information that you tell QQQ about in the form of meta-data objects includes:
+** Details about the database you are using, and how to connect to it.
+** A database table's name, fields, their types, its keys, and basic business rules (required fields, read-only fields, field lengths).
+** The specification of a custom workflow (process), including what screens are needed, with input & output values, and references to the custom application code for processing the data.
+** Details about a chart that summarizes data from a table for presentation as a dashboard widget.
+** The description of web API - its URL and authentication mechanism.
+** A table/path within a web API, and the fields returned in the JSON at that endpoint.
 // the section below is kinda dumb.  like, it says you have to write application code, but
 // then it just talks about how your app code gets for-free the same shit that QQQ does.
 // it should instead say more about what your custom app code is or does.
@@ -164,7 +160,8 @@ For example:
 // * The multi-threaded, paged producer/consumer pattern used in standard framework actions is how all custom application actions are also invoked.
 // ** For example, the standard QQQ Bulk Edit action uses the same streamed-ETL process that custom application processes can use.
 // Meaning your custom processes can take full advantage of the same complex frontend, middleware, and backend structural pieces, and you can just focus on your unique busines logic needs.
-2. *Application code* - to customize beyond what the QQQ framework does out-of-the box, and to provide application-specific business-logic.
+
+. *Application code* - to customize beyond what the QQQ framework does out-of-the box, and to provide application-specific business-logic.
 QQQ provides its programmers the same classes that it internally uses for record access, resulting in a unified application model.
 For example:
 

docs/actions/QueryAction.adoc

@@ -33,9 +33,6 @@ If the {link-table} has a `POST_QUERY_CUSTOMIZER` defined, then after records ar
 * `table` - *String, Required* - Name of the table being queried against.
 * `filter` - *<<QQueryFilter>> object* - Specification for what records should be returned, based on *<<QFilterCriteria>>* objects, and how they should be sorted, based on *<<QFilterOrderBy>>* objects.
 If a `filter` is not given, then all rows in the table will be returned by the query.
-* `skip` - *Integer* - Optional number of records to be skipped at the beginning of the result set.
-e.g., for implementing pagination.
-* `limit` - *Integer* - Optional maximum number of records to be returned by the query.
 * `transaction` - *QBackendTransaction object* - Optional transaction object.
 ** Behavior for this object is backend-dependant.
 In an RDBMS backend, this object is generally needed if you want your query to see data that may have been modified within the same transaction.
@@ -55,6 +52,14 @@ But if running a query to provide data as part of a process, then this can gener
 * `shouldMaskPassword` - *boolean, default: true* - Controls whether or not fields with `type` = `PASSWORD` should be masked, or if their actual values should be returned.
 * `queryJoins` - *List of <<QueryJoin>> objects* - Optional list of tables to be joined with the main table being queried.
 See QueryJoin below for further details.
+* `fieldNamesToInclude` - *Set of String* - Optional set of field names to be included in the records.
+** Fields from a queryJoin must be prefixed by the join table's name or alias, and a period.
+Field names from the table being queried should not have any sort of prefix.
+** A `null` set here (default) means to include all fields from the table and any queryJoins set as select=true.
+** An empty set will cause an error, as well any unrecognized field names.
+** `QueryAction` will validate the set of field names, and throw an exception if any unrecognized names are given.
+** _Note that this is an optional feature, which some backend modules may not implement.
+Meaning, they would always return all fields._
 
 ==== QQueryFilter
 A key component of *<<QueryInput>>*, a *QQueryFilter* defines both what records should be included in a query's results (e.g., an SQL `WHERE`), as well as how those results should be sorted (SQL `ORDER BY`).
@@ -68,6 +73,9 @@ In general, multiple *orderBys* can be given (depending on backend implementatio
 ** Each *subFilter* can include its own additional *subFilters*.
 ** Each *subFilter* can specify a different *booleanOperator*.
 ** For example, consider the following *QQueryFilter*, that uses two *subFilters*, and a mix of *booleanOperators*
+* `skip` - *Integer* - Optional number of records to be skipped at the beginning of the result set.
+e.g., for implementing pagination.
+* `limit` - *Integer* - Optional maximum number of records to be returned by the query.
 
 [source,java]
 ----

docs/index.adoc

@@ -6,7 +6,10 @@
 
 include::Introduction.adoc[leveloffset=+1]
 
-== Meta Data
+== Meta Data Production
+include::metaData/MetaDataProduction.adoc[leveloffset=+1]
+
+== Meta Data Types
 // Organizational units
 include::metaData/QInstance.adoc[leveloffset=+1]
 include::metaData/Backends.adoc[leveloffset=+1]

docs/metaData/MetaDataProduction.adoc

@@ -0,0 +1,363 @@
+[#MetaDataProduction]
+include::../variables.adoc[]
+
+The first thing that an application built using QQQ needs to do is to define its meta data.
+This basically means the construction of a `QInstance` object, which is populated with the
+meta data objects defining the backend(s), tables, processes, possible-value sources, joins,
+authentication provider, etc, that make your application.
+
+There are various styles that can be used for how you define your meta data, and for the
+most part they can be mixed and matched.  They will be presented here based on the historical
+evolution of how they were added to QQQ, where we generally believe that better techniques have
+been added over time.  So, you may wish to skip the earlier techniques, and jump straight to
+the end of this section.  However, it can always be instructive to learn about the past, so,
+read at your own pace.
+
+== Omni-Provider
+At the most basic level, the way to populate a `QInstance` is the simple and direct approach of creating
+one big class, possibly with just one big method, and just doing all the work directly inline there.
+
+This may (clearly) violate several good engineering principles.  However, it does have the benefit of
+being simple - if all of your meta-data is defined in one place, it can be pretty simple to find where
+that place is.  So - especially in a small project, this technique may be worth continuing to consider.
+
+Re: "doing all the work" as mentioned above - what work are we talking about?  At a minimum, we need
+to construct the following meta-data objects, and pass them into our `QInstance`:
+
+* `QAuthenticationMetaData` - how (or if!) users will be authenticated to the application.
+* `QBackendMeataData` - a backend data store.
+* `QTableMetaData` - a table (within the backend).
+* `QAppMetaData` - an organizational unit to present the other elements in a UI.
+
+Here's what a single-method omni-provider could look like:
+
+[source,java]
+.About the simplest possible single-file meta-data provider
+----
+public QInstance defineQInstance()
+{
+    QInstance qInstance = new QInstance();
+
+    qInstance.setAuthentication(new QAuthenticationMetaData()
+       .withName("anonymous")
+       .withType(QAuthenticationType.FULLY_ANONYMOUS));
+
+    qInstance.addBackend(new QBackendMetaData()
+       .withBackendType(MemoryBackendModule.class)
+       .withName("memoryBackend"));
+
+    qInstance.addTable(new QTableMetaData()
+        .withName("myTable")
+        .withPrimaryKeyField("id")
+        .withBackendName("memoryBackend")
+        .withField(new QFieldMetaData("id", QFieldType.INTEGER)));
+
+    qInstance.addApp(new QAppMetaData()
+       .withName("myApp")
+       .withSectionOfChildren(new QAppSection().withName("mySection"),
+          qInstance.getTable("myTable")))
+
+   return (qInstance);
+}
+----
+
+== Multi-method Omni-Provider
+
+The next evolution of meta-data production comes by just applying some basic better-engineering
+principles, and splitting up from a single method that constructs all the things, to at least
+using unique methods to construct each thing, then calling those methods to add their results
+to the QInstance.
+
+[source,java]
+.Multi-method omni- meta-data provider
+----
+public QInstance defineQInstance()
+{
+    QInstance qInstance = new QInstance();
+    qInstance.setAuthentication(defineAuthenticationMetaData());
+    qInstance.addBackend(defineBackendMetaData());
+    qInstance.addTable(defineMyTableMetaData());
+    qInstance.addApp(defineMyAppMetaData(qInstance));
+    return qInstance;
+}
+
+public QAuthenticationMetaData defineAuthenticationMetaData()
+{
+    return new QAuthenticationMetaData()
+       .withName("anonymous")
+       .withType(QAuthenticationType.FULLY_ANONYMOUS);
+}
+
+public QBackendMetaData defineBackendMetaData()
+{
+    return new QBackendMetaData()
+       .withBackendType(MemoryBackendModule.class)
+       .withName("memoryBackend");
+}
+
+// implementations of defineMyTableMetaData() and defineMyAppMetaData(qInstance)
+// left as an exercise for the reader
+----
+
+== Multi-class Providers
+
+Then the next logical evolution would be to put each of these single meta-data producing
+objects into its own class, along with calls to those classes.  This gets us away from the
+"5000 line" single-class, and lets us stop using the word "omni":
+
+[source,java]
+.Multi-class meta-data providers
+----
+public QInstance defineQInstance()
+{
+    QInstance qInstance = new QInstance();
+    qInstance.setAuthentication(new AuthMetaDataProvider().defineAuthenticationMetaData());
+    qInstance.addBackend(new BackendMetaDataProvider().defineBackendMetaData());
+    qInstance.addTable(new MyTableMetaDataProvider().defineTableMetaData());
+    qInstance.addApp(new MyAppMetaDataProvider().defineAppMetaData(qInstance));
+    return qInstance;
+}
+
+public class AuthMetaDataProvider
+{
+    public QAuthenticationMetaData defineAuthenticationMetaData()
+    {
+        return new QAuthenticationMetaData()
+           .withName("anonymous")
+           .withType(QAuthenticationType.FULLY_ANONYMOUS);
+    }
+}
+
+public class BackendMetaDataProvider
+{
+    public QBackendMetaData defineBackendMetaData()
+    {
+        return new QBackendMetaData()
+           .withBackendType(MemoryBackendModule.class)
+           .withName("memoryBackend");
+    }
+}
+
+// implementations of MyTableMetaDataProvider and MyAppMetaDataProvider
+// left as an exercise for the reader
+----
+
+== MetaDataProducerInterface
+
+As the size of your application grows, if you're doing per-object meta-data providers, you may find it
+burdensome, when adding a new object to your instance, to have to write code for it in two places -
+that is - a new class to produce that meta-data object, AND a single line of code to add that object
+to your `QInstance`.  As such, a mechanism exists to let you avoid that line-of-code for adding the object
+to the `QInstance`.
+
+This mechanism involves adding the `MetaDataProducerInterface` to all of your classes that produce a
+meta-data object.  This interface is generic, with a type parameter that will typically be the type of
+meta-data object you are producing, such as `QTableMetaData`, `QProcessMetaData`, or `QWidgetMetaData`,
+(technically, any class which implements `TopLevelMetaData`).  Implementers of the interface are then
+required to override just one method: `T produce(QInstance qInstance) throws QException;`
+
+Once you have your `MetaDataProducerInterface` classes defined, then there's a one-time call needed
+to add all of the objects produced by these classes to your `QInstance` - as shown here:
+
+[source,java]
+.Using MetaDataProducerInterface
+----
+public QInstance defineQInstance()
+{
+    QInstance qInstance = new QInstance();
+    MetaDataProducerHelper.processAllMetaDataProducersInPackage(qInstance,
+      "com.mydomain.myapplication");
+    return qInstance;
+}
+
+public class AuthMetaDataProducer implements MetaDataProducerInterface<QAuthenticationMetaData>
+{
+    @Override
+    public QAuthenticationMetaData produce(QInstance qInstance)
+    {
+        return new QAuthenticationMetaData()
+           .withName("anonymous")
+           .withType(QAuthenticationType.FULLY_ANONYMOUS);
+    }
+}
+
+public class BackendMetaDataProducer implements MetaDataProducerInterface<QBackendMetaData>
+{
+    @Override
+    public QBackendMetaData defineBackendMetaData()
+    {
+        return new QBackendMetaData()
+           .withBackendType(MemoryBackendModule.class)
+           .withName("memoryBackend");
+    }
+}
+
+// implementations of MyTableMetaDataProvider and MyAppMetaDataProvider
+// left as an exercise for the reader
+----
+
+=== MetaDataProducerMultiOutput
+It is worth mentioning, that sometimes it might feel like a bridge that's a bit too far, to make
+every single one of your meta-data objects require its own class.  Some may argue that it's best
+to do it that way - single responsibility principle, etc.  But, if you're producing, say, 5 widgets
+that are all related, and it's only a handful of lines of code for each one, maybe you'd rather
+produce them all in the same class.  Or maybe when you define a table, you'd like to define its
+joins and widgets at the same time.
+
+This approach can be accomplished by making the type argument for your `MetaDataProducerInterface` be
+`MetaDataProducerMultiOutput` - a simple class that just wraps a list of other `MetaDataProducerOutput`
+objects.
+
+[source,java]
+.Returning a MetaDataProducerMultiOutput
+----
+public class MyMultiProducer implements MetaDataProducerInterface<MetaDataProducerMultiOutput>
+{
+    @Override
+    public MetaDataProducerMultiOutput produce(QInstance qInstance)
+    {
+       MetaDataProducerMultiOutput output = new MetaDataProducerMultiOutput();
+
+       output.add(new QPossibleValueSource()...);
+       output.add(new QJoinMetaData()...);
+       output.add(new QJoinMetaData()...);
+       output.add(new QWidgetMetaData()...);
+       output.add(new QTableMetaData()...);
+
+       return (output);
+    }
+}
+----
+
+
+== Aside: TableMetaData with RecordEntities
+At this point, let's take a brief aside to dig deeper into the creation of a `QTableMeta` object.
+Tables, being probably the most important meta-data type in QQQ, have a lot of information that can
+be specified in their meta-data object.
+
+At the same time, if you're writing any custom code in your QQQ application
+(e.g., any processes or table customizers), where you're working with records from tables, you may
+prefer being able to work with entity beans (e.g., java classes with typed getter & setter methods),
+rather than the default object type that QQQ's ORM actions return, the `QRecord`, which carries all
+of its values in a `Map` (where you don't get compile-time checks of field names or data types).
+QQQ has a mechanism for dealing with this - in the form of the `QRecordEntity` class.
+
+So - if you want to build your application using entity beans (which is recommended, for the compile-time
+safety that they provide in custom code), you will be writing a `QRecordEntity` class for each of your tables,
+which will look like:
+
+[source,java]
+.QRecordEntity example
+----
+public class MyTable extends QRecordEntity
+{
+   public static final String TABLE_NAME = "myTable";
+
+   @QField(isEditable = false, isPrimaryKey = true)
+   private Integer id;
+
+   @QField()
+   private String name;
+
+   // no-arg constructor and constructor that takes a QRecord
+   // getters & setters (and optional fluent setters)
+}
+----
+
+The point of introducing this topic here and now is, that a `QRecordEntity` can be used to shortcut to
+defining some of the attributes in a `QTableMetaData` object.  Specifically, in a `MetaDataProducer<QTableMetaData>`
+you may say:
+
+[source,java]
+.QTableMetaDataProducer using a QRecordEntity
+----
+public QTableMetaData produce(QInstance qInstance) throws QExcpetion
+{
+  return new QTableMetaData()
+     .withName(MyTable.TABLE_NAME)
+     .withFieldsFromEntity(MyTable.class)
+     .withBackendName("memoryBackend");
+}
+----
+
+That `withFieldsFromEntity` call is one of the biggest benefits of this technique.  It allows you to avoid defining
+all of the fields in you table in two places (the entity and the table meta-data).
+
+== MetaData Producing Annotations for Entities
+
+If you are using `QRecordEntity` classes that correspond to your tables, then you can take advantage of some
+additional annotations on those classes, to produce more related meta-data objects associated with those tables.
+The point of this is to eliminate boilerplate, and simplify / speed up the process of getting a new table
+built and deployed in your application, with some bells and whistles added.
+
+=== @QMetaDataProducingEntity
+This is an annotation to go on a QRecordEntity class, which you would like to be
+processed by `MetaDataProducerHelper`, to automatically produce some meta-data
+objects.  Specifically supports:
+
+* Making a possible-value-source out of the table.
+* Processing child tables to create joins and childRecordList widgets
+
+=== @ChildTable
+This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to define
+child-tables, e.g., for producing joins and childRecordList widgets related to the table defined in the entity class.
+
+=== @ChildJoin
+This is an annotation used as a value inside a `@ChildTable` inside a `@QMetadataProducingEntity` annotation,
+to control the generation of a `QJoinMetaData`, as a `ONE_TO_MANY` type join from the table represented by
+the annotated entity, to the table referenced in the `@ChildTable` annotation.
+
+=== @ChildRecordListWidget
+This is an annotation used as a value that goes inside a `@QMetadataProducingEntity` annotation, to control
+the generation of a QWidgetMetaData - for a ChildRecordList widget.
+
+[source,java]
+.QRecordEntity with meta-data producing annotations
+----
+@QMetaDataProducingEntity(
+   producePossibleValueSource = true,
+   childTables = {
+      @ChildTable(
+         childTableEntityClass = MyChildTable.class,
+         childJoin = @ChildJoin(enabled = true),
+         childRecordListWidget = @ChildRecordListWidget(enabled = true, label = "Children"))
+   }
+)
+public class MyTable extends QRecordEntity
+{
+   public static final String TABLE_NAME = "myTable";
+   // class body left as exercise for reader
+}
+----
+
+The class given in the example above, if processed by the `MetaDataProducerHelper`, would add the following
+meta-data objects to your `QInstance`:
+
+* A `QPossibleValueSource` named `myTable`, of type `TABLE`, with `myTable` as its backing table.
+* A `QJoinMetaData` named `myTableJoinMyChildTable`, as a `ONE_TO_MANY` type, between those two tables.
+* A `QWidgetMetaData` named `myTableJoinMyChildTable`, as a `CHILD_RECORD_LIST` type, that will show a list of
+records from `myChildTable` as a widget, when viewing a record from `myTable`.
+
+== Other MetaData Producing Annotations
+
+Similar to these annotations for a `RecordEntity`, a similar one exists for a `PossibleValueEnum` class,
+to automatically write the meta-data to use that enum as a possible value source in your application:
+
+=== @QMetaDataProducingPossibleValueEnum
+This is an annotation to go on a `PossibleValueEnum` class, which you would like to be
+processed by MetaDataProducerHelper, to automatically produce a PossibleValueSource meta-data
+based on the enum.
+
+[source,java]
+.PossibleValueEnum with meta-data producing annotation
+----
+@QMetaDataProducingPossibleValueEnum(producePossibleValueSource = true)
+public enum MyOptionsEnum implements PossibleValueEnum<Integer>
+{
+   // values and methods left as exercise for reader
+}
+----
+The enum given in the example above, if processed by the `MetaDataProducerHelper`, would add the following
+meta-data object to your `QInstance`:
+
+* A `QPossibleValueSource` named `MyOptionsEnum`, of type `ENUM`, with `MyOptionsEnum` as its backing enum.

docs/metaData/QInstance.adoc

@@ -29,11 +29,21 @@ service.routes(qJavalinImplementation.getRoutes());
 service.start();
 ----
 
-*QBackendMetaData Setup Methods:*
+*QInstance Setup:*
 
 These are the methods that one is most likely to use when setting up (defining) a `QInstance` object:
 
-* asdf
+* `add(TopLevelMetaDataInterface metaData)` - Generic method that takes most of the meta-data subtypes that can be added
+to an instance, such as `QBackendMetaData`, `QTableMetaData`, `QProcessMetaData`, etc.
+There are also type-specific methods (e.g., `addTable`, `addProcess`, etc), which one can call instead - this would just
+be a matter of personal preference.
 
-*QBackendMetaData Usage Methods:*
+*QInstance Usage:*
 
+Generally you will set up a `QInstance` in your application's startup flow, and then place it in the server (e.g., javalin).
+But, if, during application-code runtime, you need access to any of the meta-data in the instance, you access it
+via the `QContext` object's static `getInstance()` method.  This can be useful, for example, to get a list of the defined
+tables in the application, or fields in a table, or details about a field, etc.
+
+It is generally considered risky and/or not a good idea at all to modify the `QInstance` after it has been validated and
+a server is running.  Future versions of QQQ may in fact restrict modifications to the instance after validation.

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.24.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/async/AsyncRecordPipeLoop.java

@@ -186,7 +186,7 @@ public class AsyncRecordPipeLoop
 
       if(recordCount > 0)
       {
-         LOG.info("End of job summary", logPair("recordCount", recordCount), logPair("jobName", jobName), logPair("millis", endTime - jobStartTime), logPair("recordsPerSecond", 1000d * (recordCount / (.001d + (endTime - jobStartTime)))));
+         LOG.debug("End of job summary", logPair("recordCount", recordCount), logPair("jobName", jobName), logPair("millis", endTime - jobStartTime), logPair("recordsPerSecond", 1000d * (recordCount / (.001d + (endTime - jobStartTime)))));
       }
 
       return (recordCount);

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

@@ -44,6 +44,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
 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.security.MultiRecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLockFilters;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -173,26 +174,53 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
       Map<String, Serializable> securityKeyValues = new HashMap<>();
       for(RecordSecurityLock recordSecurityLock : RecordSecurityLockFilters.filterForReadLocks(CollectionUtils.nonNullList(table.getRecordSecurityLocks())))
       {
-         Serializable keyValue = record == null ? null : record.getValue(recordSecurityLock.getFieldName());
-
-         if(keyValue == null && oldRecord.isPresent())
-         {
-            LOG.debug("Table with a securityLock, but value not found in field", logPair("table", table.getName()), logPair("field", recordSecurityLock.getFieldName()));
-            keyValue = oldRecord.get().getValue(recordSecurityLock.getFieldName());
-         }
-
-         if(keyValue == null)
-         {
-            LOG.debug("Table with a securityLock, but value not found in field", logPair("table", table.getName()), logPair("field", recordSecurityLock.getFieldName()), logPair("oldRecordIsPresent", oldRecord.isPresent()));
-         }
-
-         securityKeyValues.put(recordSecurityLock.getSecurityKeyType(), keyValue);
+         getRecordSecurityKeyValues(table, record, oldRecord, recordSecurityLock, securityKeyValues);
       }
       return securityKeyValues;
    }
 
 
 
+   /***************************************************************************
+    ** recursive implementation of getRecordSecurityKeyValues, for dealing with
+    ** multi-locks
+    ***************************************************************************/
+   private static void getRecordSecurityKeyValues(QTableMetaData table, QRecord record, Optional<QRecord> oldRecord, RecordSecurityLock recordSecurityLock, Map<String, Serializable> securityKeyValues)
+   {
+      //////////////////////////////////////////////////////
+      // special case with recursive call for multi-locks //
+      //////////////////////////////////////////////////////
+      if(recordSecurityLock instanceof MultiRecordSecurityLock multiRecordSecurityLock)
+      {
+         for(RecordSecurityLock subLock : RecordSecurityLockFilters.filterForReadLocks(CollectionUtils.nonNullList(multiRecordSecurityLock.getLocks())))
+         {
+            getRecordSecurityKeyValues(table, record, oldRecord, subLock, securityKeyValues);
+         }
+
+         return;
+      }
+
+      ///////////////////////////////////////////
+      // by default, deal with non-multi locks //
+      ///////////////////////////////////////////
+      Serializable keyValue = record == null ? null : record.getValue(recordSecurityLock.getFieldName());
+
+      if(keyValue == null && oldRecord.isPresent())
+      {
+         LOG.debug("Table with a securityLock, but value not found in field", logPair("table", table.getName()), logPair("field", recordSecurityLock.getFieldName()));
+         keyValue = oldRecord.get().getValue(recordSecurityLock.getFieldName());
+      }
+
+      if(keyValue == null)
+      {
+         LOG.debug("Table with a securityLock, but value not found in field", logPair("table", table.getName()), logPair("field", recordSecurityLock.getFieldName()), logPair("oldRecordIsPresent", oldRecord.isPresent()));
+      }
+
+      securityKeyValues.put(recordSecurityLock.getSecurityKeyType(), keyValue);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -218,15 +246,16 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
                   throw (new QException("Requested audit for an unrecognized table name: " + auditSingleInput.getAuditTableName()));
                }
 
-               ///////////////////////////////////////////////////
-               // validate security keys on the table are given //
-               ///////////////////////////////////////////////////
-               for(RecordSecurityLock recordSecurityLock : RecordSecurityLockFilters.filterForReadLocks(CollectionUtils.nonNullList(table.getRecordSecurityLocks())))
+               ///////////////////////////////////////////////////////
+               // validate security keys on the table are given     //
+               // originally, this case threw...                    //
+               // but i think it's better to record the audit, just //
+               // missing its security key value, then to fail...   //
+               // but, maybe should be configurable, etc...         //
+               ///////////////////////////////////////////////////////
+               if(!validateSecurityKeys(auditSingleInput, table))
                {
-                  if(auditSingleInput.getSecurityKeyValues() == null || !auditSingleInput.getSecurityKeyValues().containsKey(recordSecurityLock.getSecurityKeyType()))
-                  {
-                     throw (new QException("Missing securityKeyValue [" + recordSecurityLock.getSecurityKeyType() + "] in audit request for table " + auditSingleInput.getAuditTableName()));
-                  }
+                  LOG.debug("Missing securityKeyValue in audit request", logPair("table", auditSingleInput.getAuditTableName()), logPair("auditMessage", auditSingleInput.getMessage()), logPair("recordId", auditSingleInput.getRecordId()));
                }
 
                ////////////////////////////////////////////////
@@ -272,7 +301,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...");
@@ -304,6 +333,70 @@ public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static boolean validateSecurityKeys(AuditSingleInput auditSingleInput, QTableMetaData table)
+   {
+      boolean allAreValid = true;
+      for(RecordSecurityLock recordSecurityLock : RecordSecurityLockFilters.filterForReadLocks(CollectionUtils.nonNullList(table.getRecordSecurityLocks())))
+      {
+         boolean lockIsValid = validateSecurityKeysForLock(auditSingleInput, recordSecurityLock);
+         if(!lockIsValid)
+         {
+            allAreValid = false;
+         }
+      }
+
+      return (allAreValid);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static boolean validateSecurityKeysForLock(AuditSingleInput auditSingleInput, RecordSecurityLock recordSecurityLock)
+   {
+      if(recordSecurityLock instanceof MultiRecordSecurityLock multiRecordSecurityLock)
+      {
+         boolean allSubLocksAreValid = true;
+         boolean anySubLocksAreValid = false;
+         for(RecordSecurityLock lock : RecordSecurityLockFilters.filterForReadLocks(CollectionUtils.nonNullList(multiRecordSecurityLock.getLocks())))
+         {
+            boolean subLockIsValid = validateSecurityKeysForLock(auditSingleInput, lock);
+            if(subLockIsValid)
+            {
+               anySubLocksAreValid = true;
+            }
+            else
+            {
+               allSubLocksAreValid = false;
+            }
+         }
+
+         if(multiRecordSecurityLock.getOperator().equals(MultiRecordSecurityLock.BooleanOperator.OR))
+         {
+            return (anySubLocksAreValid);
+         }
+         else if(multiRecordSecurityLock.getOperator().equals(MultiRecordSecurityLock.BooleanOperator.AND))
+         {
+            return (allSubLocksAreValid);
+         }
+      }
+      else
+      {
+         if(auditSingleInput.getSecurityKeyValues() == null || !auditSingleInput.getSecurityKeyValues().containsKey(recordSecurityLock.getSecurityKeyType()))
+         {
+            return (false);
+         }
+      }
+
+      return (true);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/

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

@@ -24,10 +24,12 @@ package com.kingsrook.qqq.backend.core.actions.customizers;
 
 import java.io.Serializable;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
+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.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -143,4 +145,19 @@ public interface RecordCustomizerUtilityInterface
       }
    }
 
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default Map<Serializable, QRecord> getOldRecordMap(List<QRecord> oldRecordList, UpdateInput updateInput)
+   {
+      Map<Serializable, QRecord> oldRecordMap = new HashMap<>();
+      for(QRecord qRecord : oldRecordList)
+      {
+         oldRecordMap.put(qRecord.getValue(updateInput.getTable().getPrimaryKeyField()), qRecord);
+      }
+
+      return (oldRecordMap);
+   }
+
 }

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));
-         treeNodes.put(appName, new AppTreeNode(app));
+         if(!filter.allowApp(metaDataInput, 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 = codeClass.getConstructor().newInstance();
+         Object codeObject;
+         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();
-
-         STEP_LOOP:
-         while(true)
+         switch(Objects.requireNonNull(process.getStepFlow(), "Process [" + process.getName() + "] has a null stepFlow."))
          {
-            ///////////////////////////////////////////////////////////////////////////////////////////////////////
-            // 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)
-            {
-               ////////////////////////////////////////////////////////////////
-               // 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()));
-            }
+            case LINEAR -> runLinearStepLoop(process, processState, stateKey, runProcessInput, runProcessOutput);
+            case STATE_MACHINE -> runStateMachineStep(runProcessInput.getStartAfterStep(), process, processState, stateKey, runProcessInput, runProcessOutput, 0);
+            default -> throw (new QException("Unhandled process step flow: " + process.getStepFlow()));
          }
 
          ///////////////////////////////////////////////////////////////////////////
@@ -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 - //
-         // it is only needed on the transitional edge from a backend-step to a frontend step, but not    //
-         // in the other directly                                                                         //
-         ///////////////////////////////////////////////////////////////////////////////////////////////////
-         optionalProcessState.get().setUpdatedFrontendStepList(null);
+         /////////////////////////////////////////////////////////////////////////////////////////////////////
+         // 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      //
+         // in the other directly                                                                           //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////
+         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

@@ -42,6 +42,7 @@ import com.kingsrook.qqq.backend.core.actions.AbstractQActionFunction;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncRecordPipeLoop;
 import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
 import com.kingsrook.qqq.backend.core.actions.reporting.customizers.DataSourceQueryInputCustomizer;
+import com.kingsrook.qqq.backend.core.actions.reporting.customizers.ReportCustomRecordSourceInterface;
 import com.kingsrook.qqq.backend.core.actions.reporting.customizers.ReportViewCustomizer;
 import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
@@ -62,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;
@@ -302,10 +305,19 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
       JoinsContext joinsContext = null;
       if(dataSource != null)
       {
+         ///////////////////////////////////////////////////////////////////////////////////////
+         // count records, if applicable, from the data source - for populating into the      //
+         // countByDataSource map, as well as for checking if too many rows (e.g., for excel) //
+         ///////////////////////////////////////////////////////////////////////////////////////
+         countDataSourceRecords(reportInput, dataSource, reportFormat);
+
+         ///////////////////////////////////////////////////////////////////////////////////////////
+         // if there's a source table, set up a joins context, to use below for looking up fields //
+         ///////////////////////////////////////////////////////////////////////////////////////////
          if(StringUtils.hasContent(dataSource.getSourceTable()))
          {
-            joinsContext = new JoinsContext(QContext.getQInstance(), dataSource.getSourceTable(), cloneDataSourceQueryJoins(dataSource), dataSource.getQueryFilter() == null ? null : dataSource.getQueryFilter().clone());
-            countDataSourceRecords(reportInput, dataSource, reportFormat);
+            QQueryFilter queryFilter = dataSource.getQueryFilter() == null ? new QQueryFilter() : dataSource.getQueryFilter().clone();
+            joinsContext = new JoinsContext(QContext.getQInstance(), dataSource.getSourceTable(), dataSource.getQueryJoins(), queryFilter);
          }
       }
 
@@ -329,6 +341,7 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
             field.setName(column.getName());
             if(StringUtils.hasContent(column.getLabel()))
             {
+
                field.setLabel(column.getLabel());
             }
             fields.add(field);
@@ -346,23 +359,33 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
     *******************************************************************************/
    private void countDataSourceRecords(ReportInput reportInput, QReportDataSource dataSource, ReportFormat reportFormat) throws QException
    {
-      QQueryFilter queryFilter = dataSource.getQueryFilter() == null ? new QQueryFilter() : dataSource.getQueryFilter().clone();
-      setInputValuesInQueryFilter(reportInput, queryFilter);
-
-      CountInput countInput = new CountInput();
-      countInput.setTableName(dataSource.getSourceTable());
-      countInput.setFilter(queryFilter);
-      countInput.setQueryJoins(cloneDataSourceQueryJoins(dataSource));
-      CountOutput countOutput = new CountAction().execute(countInput);
-
-      if(countOutput.getCount() != null)
+      Integer count = null;
+      if(dataSource.getCustomRecordSource() != null)
       {
-         countByDataSource.put(dataSource.getName(), countOutput.getCount());
+         // todo - add `count` method to interface?
+      }
+      else if(StringUtils.hasContent(dataSource.getSourceTable()))
+      {
+         QQueryFilter queryFilter = dataSource.getQueryFilter() == null ? new QQueryFilter() : dataSource.getQueryFilter().clone();
+         setInputValuesInQueryFilter(reportInput, queryFilter);
 
-         if(reportFormat.getMaxRows() != null && countOutput.getCount() > reportFormat.getMaxRows())
+         CountInput countInput = new CountInput();
+         countInput.setTableName(dataSource.getSourceTable());
+         countInput.setFilter(queryFilter);
+         countInput.setQueryJoins(cloneDataSourceQueryJoins(dataSource));
+         CountOutput countOutput = new CountAction().execute(countInput);
+
+         count = countOutput.getCount();
+      }
+
+      if(count != null)
+      {
+         countByDataSource.put(dataSource.getName(), count);
+
+         if(reportFormat.getMaxRows() != null && count > reportFormat.getMaxRows())
          {
             throw (new QUserFacingException("The requested report would include more rows ("
-               + String.format("%,d", countOutput.getCount()) + ") than the maximum allowed ("
+               + String.format("%,d", count) + ") than the maximum allowed ("
                + String.format("%,d", reportFormat.getMaxRows()) + ") for the selected file format (" + reportFormat + ")."));
          }
       }
@@ -423,13 +446,19 @@ public class GenerateReportAction extends AbstractQActionFunction<ReportInput, R
       String        tableLabel    = ObjectUtils.tryElse(() -> QContext.getQInstance().getTable(dataSource.getSourceTable()).getLabel(), Objects.requireNonNullElse(dataSource.getSourceTable(), ""));
       AtomicInteger consumedCount = new AtomicInteger(0);
 
-      /////////////////////////////////////////////////////////////////
-      // run a record pipe loop, over the query for this data source //
-      /////////////////////////////////////////////////////////////////
+      /////////////////////////////////////////////////////////////////////////////////////////////////
+      // run a record pipe loop, over the query (or other data-supplier/source) for this data source //
+      /////////////////////////////////////////////////////////////////////////////////////////////////
       RecordPipe recordPipe = new BufferedRecordPipe(1000);
       new AsyncRecordPipeLoop().run("Report[" + reportInput.getReportName() + "]", null, recordPipe, (callback) ->
       {
-         if(dataSource.getSourceTable() != null)
+         if(dataSource.getCustomRecordSource() != null)
+         {
+            ReportCustomRecordSourceInterface recordSource = QCodeLoader.getAdHoc(ReportCustomRecordSourceInterface.class, dataSource.getCustomRecordSource());
+            recordSource.execute(reportInput, dataSource, recordPipe);
+            return (true);
+         }
+         else if(dataSource.getSourceTable() != null)
          {
             QQueryFilter queryFilter = dataSource.getQueryFilter() == null ? new QQueryFilter() : dataSource.getQueryFilter().clone();
             setInputValuesInQueryFilter(reportInput, queryFilter);
@@ -587,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/reporting/customizers/ReportCustomRecordSourceInterface.java

@@ -0,0 +1,43 @@
+/*
+ * 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.reporting.customizers;
+
+
+import com.kingsrook.qqq.backend.core.actions.reporting.RecordPipe;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportInput;
+import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportDataSource;
+
+
+/*******************************************************************************
+ ** Interface to be implemented to do a custom source of data for a report
+ ** (instead of just a query against a table).
+ *******************************************************************************/
+public interface ReportCustomRecordSourceInterface
+{
+
+   /***************************************************************************
+    ** Given the report input, put records into the pipe, for the report.
+    ***************************************************************************/
+   void execute(ReportInput reportInput, QReportDataSource reportDataSource, RecordPipe recordPipe) throws QException;
+
+}

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

@@ -124,10 +124,11 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
    private Writer              activeSheetWriter = null;
    private StreamedSheetWriter sheetWriter       = null;
 
-   private QReportView                       currentView      = null;
-   private Map<String, List<QFieldMetaData>> fieldsPerView    = new HashMap<>();
-   private Map<String, Integer>              rowsPerView      = new HashMap<>();
-   private Map<String, String>               labelViewsByName = new HashMap<>();
+   private QReportView                       currentView              = null;
+   private Map<String, List<QFieldMetaData>> fieldsPerView            = new HashMap<>();
+   private Map<String, Integer>              rowsPerView              = new HashMap<>();
+   private Map<String, String>               labelViewsByName         = new HashMap<>();
+   private Map<String, String>               sheetReferenceByViewName = new HashMap<>();
 
 
 
@@ -180,6 +181,7 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
             String    sheetReference = sheet.getPackagePart().getPartName().getName().substring(1);
             sheetMapByExcelReference.put(sheetReference, sheet);
             sheetMapByViewName.put(view.getName(), sheet);
+            sheetReferenceByViewName.put(view.getName(), sheetReference);
             sheetCounter++;
          }
 
@@ -446,7 +448,7 @@ public class ExcelPoiBasedStreamingExportStreamer implements ExportStreamerInter
          // - with a new output stream writer    //
          // - and with a SpreadsheetWriter       //
          //////////////////////////////////////////
-         zipOutputStream.putNextEntry(new ZipEntry("xl/worksheets/sheet" + this.sheetIndex++ + ".xml"));
+         zipOutputStream.putNextEntry(new ZipEntry(sheetReferenceByViewName.get(view.getName())));
          activeSheetWriter = new OutputStreamWriter(zipOutputStream);
          sheetWriter = new StreamedSheetWriter(activeSheetWriter);
 

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

@@ -26,6 +26,7 @@ import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
@@ -50,8 +51,10 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperat
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.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;
@@ -64,6 +67,7 @@ import com.kingsrook.qqq.backend.core.modules.backend.QBackendModuleDispatcher;
 import com.kingsrook.qqq.backend.core.modules.backend.QBackendModuleInterface;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.ListingHash;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 
 
@@ -101,6 +105,8 @@ public class QueryAction
          throw (new QException("A table named [" + queryInput.getTableName() + "] was not found in the active QInstance"));
       }
 
+      validateFieldNamesToInclude(queryInput);
+
       QBackendMetaData backend = queryInput.getBackend();
       postQueryRecordCustomizer = QCodeLoader.getTableCustomizer(table, TableCustomizers.POST_QUERY_RECORD.getRole());
       this.queryInput = queryInput;
@@ -158,6 +164,125 @@ public class QueryAction
 
 
 
+   /***************************************************************************
+    ** if QueryInput contains a set of FieldNamesToInclude, then validate that
+    ** those are known field names in the table being queried, or a selected
+    ** queryJoin.
+    ***************************************************************************/
+   static void validateFieldNamesToInclude(QueryInput queryInput) throws QException
+   {
+      Set<String> fieldNamesToInclude = queryInput.getFieldNamesToInclude();
+      if(fieldNamesToInclude == null)
+      {
+         ////////////////////////////////
+         // null set means select all. //
+         ////////////////////////////////
+         return;
+      }
+
+      if(fieldNamesToInclude.isEmpty())
+      {
+         /////////////////////////////////////
+         // empty set, however, is an error //
+         /////////////////////////////////////
+         throw (new QException("An empty set of fieldNamesToInclude was given as queryInput, which is not allowed."));
+      }
+
+      List<String>                unrecognizedFieldNames = new ArrayList<>();
+      Map<String, QTableMetaData> selectedQueryJoins     = null;
+      for(String fieldName : fieldNamesToInclude)
+      {
+         if(fieldName.contains("."))
+         {
+            ////////////////////////////////////////////////
+            // handle names with dots - fields from joins //
+            ////////////////////////////////////////////////
+            String[] parts = fieldName.split("\\.");
+            if(parts.length != 2)
+            {
+               unrecognizedFieldNames.add(fieldName);
+            }
+            else
+            {
+               String tableOrAlias  = parts[0];
+               String fieldNamePart = parts[1];
+
+               ////////////////////////////////////////////
+               // build map of queryJoins being selected //
+               ////////////////////////////////////////////
+               if(selectedQueryJoins == null)
+               {
+                  selectedQueryJoins = new HashMap<>();
+                  for(QueryJoin queryJoin : CollectionUtils.nonNullList(queryInput.getQueryJoins()))
+                  {
+                     if(queryJoin.getSelect())
+                     {
+                        String         joinTableOrAlias = queryJoin.getJoinTableOrItsAlias();
+                        QTableMetaData joinTable        = QContext.getQInstance().getTable(queryJoin.getJoinTable());
+                        if(joinTable != null)
+                        {
+                           selectedQueryJoins.put(joinTableOrAlias, joinTable);
+                        }
+                     }
+                  }
+               }
+
+               if(!selectedQueryJoins.containsKey(tableOrAlias))
+               {
+                  ///////////////////////////////////////////
+                  // unrecognized tableOrAlias is an error //
+                  ///////////////////////////////////////////
+                  unrecognizedFieldNames.add(fieldName);
+               }
+               else
+               {
+                  QTableMetaData joinTable = selectedQueryJoins.get(tableOrAlias);
+                  if(!joinTable.getFields().containsKey(fieldNamePart))
+                  {
+                     //////////////////////////////////////////////////////////
+                     // unrecognized field within the join table is an error //
+                     //////////////////////////////////////////////////////////
+                     unrecognizedFieldNames.add(fieldName);
+                  }
+               }
+            }
+         }
+         else
+         {
+            ///////////////////////////////////////////////////////////////////////
+            // non-join fields - just ensure field name is in table's fields map //
+            ///////////////////////////////////////////////////////////////////////
+            if(!queryInput.getTable().getFields().containsKey(fieldName))
+            {
+               unrecognizedFieldNames.add(fieldName);
+            }
+         }
+      }
+
+      if(!unrecognizedFieldNames.isEmpty())
+      {
+         throw (new QException("QueryInput contained " + unrecognizedFieldNames.size() + " unrecognized field name" + StringUtils.plural(unrecognizedFieldNames) + ": " + StringUtils.join(",", unrecognizedFieldNames)));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** 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/tables/helpers/UniqueKeyHelper.java

@@ -50,6 +50,7 @@ import com.kingsrook.qqq.backend.core.utils.ValueUtils;
  *******************************************************************************/
 public class UniqueKeyHelper
 {
+   private static Integer pageSize = 1000;
 
    /*******************************************************************************
     **
@@ -60,62 +61,71 @@ public class UniqueKeyHelper
       Map<List<Serializable>, Serializable> existingRecords = new HashMap<>();
       if(ukFieldNames != null)
       {
-         QueryInput queryInput = new QueryInput();
-         queryInput.setTableName(table.getName());
-         queryInput.setTransaction(transaction);
+         for(List<QRecord> page : CollectionUtils.getPages(recordList, pageSize))
+         {
+            QueryInput queryInput = new QueryInput();
+            queryInput.setTableName(table.getName());
+            queryInput.setTransaction(transaction);
 
-         QQueryFilter filter = new QQueryFilter();
-         if(ukFieldNames.size() == 1)
-         {
-            List<Serializable> values = recordList.stream()
-               .filter(r -> CollectionUtils.nullSafeIsEmpty(r.getErrors()))
-               .map(r -> r.getValue(ukFieldNames.get(0)))
-               .collect(Collectors.toList());
-            filter.addCriteria(new QFilterCriteria(ukFieldNames.get(0), QCriteriaOperator.IN, values));
-         }
-         else
-         {
-            filter.setBooleanOperator(QQueryFilter.BooleanOperator.OR);
-            for(QRecord record : recordList)
+            QQueryFilter filter = new QQueryFilter();
+            if(ukFieldNames.size() == 1)
             {
-               if(CollectionUtils.nullSafeHasContents(record.getErrors()))
+               List<Serializable> values = page.stream()
+                  .filter(r -> CollectionUtils.nullSafeIsEmpty(r.getErrors()))
+                  .map(r -> r.getValue(ukFieldNames.get(0)))
+                  .collect(Collectors.toList());
+
+               if(values.isEmpty())
                {
                   continue;
                }
 
-               QQueryFilter subFilter = new QQueryFilter();
-               filter.addSubFilter(subFilter);
-               for(String fieldName : ukFieldNames)
+               filter.addCriteria(new QFilterCriteria(ukFieldNames.get(0), QCriteriaOperator.IN, values));
+            }
+            else
+            {
+               filter.setBooleanOperator(QQueryFilter.BooleanOperator.OR);
+               for(QRecord record : page)
                {
-                  Serializable value = record.getValue(fieldName);
-                  if(value == null)
+                  if(CollectionUtils.nullSafeHasContents(record.getErrors()))
                   {
-                     subFilter.addCriteria(new QFilterCriteria(fieldName, QCriteriaOperator.IS_BLANK));
+                     continue;
                   }
-                  else
+
+                  QQueryFilter subFilter = new QQueryFilter();
+                  filter.addSubFilter(subFilter);
+                  for(String fieldName : ukFieldNames)
                   {
-                     subFilter.addCriteria(new QFilterCriteria(fieldName, QCriteriaOperator.EQUALS, value));
+                     Serializable value = record.getValue(fieldName);
+                     if(value == null)
+                     {
+                        subFilter.addCriteria(new QFilterCriteria(fieldName, QCriteriaOperator.IS_BLANK));
+                     }
+                     else
+                     {
+                        subFilter.addCriteria(new QFilterCriteria(fieldName, QCriteriaOperator.EQUALS, value));
+                     }
                   }
                }
+
+               if(CollectionUtils.nullSafeIsEmpty(filter.getSubFilters()))
+               {
+                  ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+                  // if we didn't build any sub-filters (because all records have errors in them), don't run a query w/ no clauses - continue to next page //
+                  ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+                  continue;
+               }
             }
 
-            if(CollectionUtils.nullSafeIsEmpty(filter.getSubFilters()))
+            queryInput.setFilter(filter);
+            QueryOutput queryOutput = new QueryAction().execute(queryInput);
+            for(QRecord record : queryOutput.getRecords())
             {
-               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-               // if we didn't build any sub-filters (because all records have errors in them), don't run a query w/ no clauses - rather - return early. //
-               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-               return (existingRecords);
-            }
-         }
-
-         queryInput.setFilter(filter);
-         QueryOutput queryOutput = new QueryAction().execute(queryInput);
-         for(QRecord record : queryOutput.getRecords())
-         {
-            Optional<List<Serializable>> keyValues = getKeyValues(table, uniqueKey, record, allowNullKeyValuesToEqual);
-            if(keyValues.isPresent())
-            {
-               existingRecords.put(keyValues.get(), record.getValue(table.getPrimaryKeyField()));
+               Optional<List<Serializable>> keyValues = getKeyValues(table, uniqueKey, record, allowNullKeyValuesToEqual);
+               if(keyValues.isPresent())
+               {
+                  existingRecords.put(keyValues.get(), record.getValue(table.getPrimaryKeyField()));
+               }
             }
          }
       }
@@ -200,4 +210,26 @@ public class UniqueKeyHelper
       }
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for pageSize
+    **
+    *******************************************************************************/
+   public static Integer getPageSize()
+   {
+      return pageSize;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for pageSize
+    **
+    *******************************************************************************/
+   public static void setPageSize(Integer pageSize)
+   {
+      UniqueKeyHelper.pageSize = pageSize;
+   }
+
 }

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       = Collections.emptyMap();
-
-            if(fileDownloadAdornment.isPresent())
-            {
-               adornmentValues = fileDownloadAdornment.get().getValues();
-            }
-            else
-            {
-               ///////////////////////////////////////////////////////
-               // don't change blobs unless they are file-downloads //
-               ///////////////////////////////////////////////////////
-               continue;
-            }
+            Map<String, Serializable> adornmentValues = fileDownloadAdornment.get().getValues();
 
             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,19 @@ public class QValueFormatter
                   }
                }
 
-               record.setValue(field.getName(), "/data/" + table.getName() + "/" + primaryKey + "/" + field.getName() + "/" + fileName);
+               ////////////////////////////////////////////////////////////////////////////////////////////////
+               // if field type is blob OR if there's a supplemental process or code-ref that needs to run - //
+               // then update its value to be a callback-url that'll give access to the bytes to download    //
+               // implied here is that a String value (w/o supplemental code/proc) has its value stay as a   //
+               // URL, which is where the file is directly downloaded from.  And in the case of a String     //
+               // with code-to-run, then the code should run, followed by a redirect to the value URL.       //
+               ////////////////////////////////////////////////////////////////////////////////////////////////
+               if(QFieldType.BLOB.equals(field.getType())
+                  || adornmentValues.containsKey(AdornmentType.FileDownloadValues.SUPPLEMENTAL_CODE_REFERENCE)
+                  || adornmentValues.containsKey(AdornmentType.FileDownloadValues.SUPPLEMENTAL_PROCESS_NAME))
+               {
+                  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 (or under) 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/ConfigFilesBasedQQQApplication.java

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

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

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

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/instances/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;
@@ -288,7 +289,21 @@ public class QInstanceEnricher
 
       if(table.getFields() != null)
       {
-         table.getFields().values().forEach(this::enrichField);
+         for(Map.Entry<String, QFieldMetaData> entry : table.getFields().entrySet())
+         {
+            String         name  = entry.getKey();
+            QFieldMetaData field = entry.getValue();
+
+            ////////////////////////////////////////////////////////////////////////////
+            // in case the field wasn't given a name, use its key from the fields map //
+            ////////////////////////////////////////////////////////////////////////////
+            if(!StringUtils.hasContent(field.getName()))
+            {
+               field.setName(name);
+            }
+
+            enrichField(field);
+         }
 
          for(QSupplementalTableMetaData supplementalTableMetaData : CollectionUtils.nonNullMap(table.getSupplementalMetaData()).values())
          {
@@ -410,10 +425,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 +466,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,7 +43,9 @@ 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;
 import com.kingsrook.qqq.backend.core.actions.values.QCustomPossibleValueProvider;
 import com.kingsrook.qqq.backend.core.exceptions.QInstanceValidationException;
@@ -68,11 +70,13 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.ValueTooLongBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppChildMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 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;
@@ -184,6 +188,7 @@ public class QInstanceValidator
       //////////////////////////////////////////////////////////////////////////
       try
       {
+         validateInstanceAttributes(qInstance);
          validateBackends(qInstance);
          validateAuthentication(qInstance);
          validateAutomationProviders(qInstance);
@@ -224,6 +229,19 @@ public class QInstanceValidator
 
 
 
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private void validateInstanceAttributes(QInstance qInstance)
+   {
+      if(qInstance.getMetaDataFilter() != null)
+      {
+         validateSimpleCodeReference("Instance metaDataFilter ", qInstance.getMetaDataFilter(), MetaDataFilterInterface.class);
+      }
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -763,14 +781,37 @@ public class QInstanceValidator
          if(assertCondition(StringUtils.hasContent(association.getName()), "missing a name for an Association on table " + table.getName()))
          {
             String messageSuffix = " for Association " + association.getName() + " on table " + table.getName();
+            boolean recognizedTable = false;
             if(assertCondition(StringUtils.hasContent(association.getAssociatedTableName()), "missing associatedTableName" + messageSuffix))
             {
-               assertCondition(qInstance.getTable(association.getAssociatedTableName()) != null, "unrecognized associatedTableName " + association.getAssociatedTableName() + messageSuffix);
+               if(assertCondition(qInstance.getTable(association.getAssociatedTableName()) != null, "unrecognized associatedTableName " + association.getAssociatedTableName() + messageSuffix))
+               {
+                  recognizedTable = true;
+               }
             }
 
             if(assertCondition(StringUtils.hasContent(association.getJoinName()), "missing joinName" + messageSuffix))
             {
-               assertCondition(qInstance.getJoin(association.getJoinName()) != null, "unrecognized joinName " + association.getJoinName() + messageSuffix);
+               QJoinMetaData join = qInstance.getJoin(association.getJoinName());
+               if(assertCondition(join != null, "unrecognized joinName " + association.getJoinName() + messageSuffix))
+               {
+                  assert join != null; // covered by the assertCondition
+
+                  if(recognizedTable)
+                  {
+                     boolean isLeftToRight = join.getLeftTable().equals(table.getName()) && join.getRightTable().equals(association.getAssociatedTableName());
+                     boolean isRightToLeft = join.getRightTable().equals(table.getName()) && join.getLeftTable().equals(association.getAssociatedTableName());
+                     assertCondition(isLeftToRight || isRightToLeft, "join [" + association.getJoinName() + "] does not connect tables [" + table.getName() + "] and [" + association.getAssociatedTableName() + "]" + messageSuffix);
+                     if(isLeftToRight)
+                     {
+                        assertCondition(join.getType().equals(JoinType.ONE_TO_MANY) || join.getType().equals(JoinType.ONE_TO_ONE), "Join type does not have 'one' on this table's side side (left)" + messageSuffix);
+                     }
+                     else if(isRightToLeft)
+                     {
+                        assertCondition(join.getType().equals(JoinType.MANY_TO_ONE) || join.getType().equals(JoinType.ONE_TO_ONE), "Join type does not have 'one' on this table's side (right)" + messageSuffix);
+                     }
+                  }
+               }
             }
          }
       }
@@ -927,13 +968,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 //
@@ -1038,6 +1074,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());
+         }
+      }
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -1545,6 +1606,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))
@@ -1660,9 +1731,12 @@ public class QInstanceValidator
 
                   String dataSourceErrorPrefix = "Report " + reportName + " data source " + dataSource.getName() + " ";
 
+                  boolean hasASource = false;
+
                   if(StringUtils.hasContent(dataSource.getSourceTable()))
                   {
-                     assertCondition(dataSource.getStaticDataSupplier() == null, dataSourceErrorPrefix + "has both a sourceTable and a staticDataSupplier (exactly 1 is required).");
+                     hasASource = true;
+                     assertCondition(dataSource.getStaticDataSupplier() == null, dataSourceErrorPrefix + "has both a sourceTable and a staticDataSupplier (not compatible together).");
                      if(assertCondition(qInstance.getTable(dataSource.getSourceTable()) != null, dataSourceErrorPrefix + "source table " + dataSource.getSourceTable() + " is not a table in this instance."))
                      {
                         if(dataSource.getQueryFilter() != null)
@@ -1671,14 +1745,21 @@ public class QInstanceValidator
                         }
                      }
                   }
-                  else if(dataSource.getStaticDataSupplier() != null)
+
+                  if(dataSource.getStaticDataSupplier() != null)
                   {
+                     assertCondition(dataSource.getCustomRecordSource() == null, dataSourceErrorPrefix + "has both a staticDataSupplier and a customRecordSource (not compatible together).");
+                     hasASource = true;
                      validateSimpleCodeReference(dataSourceErrorPrefix, dataSource.getStaticDataSupplier(), Supplier.class);
                   }
-                  else
+
+                  if(dataSource.getCustomRecordSource() != null)
                   {
-                     errors.add(dataSourceErrorPrefix + "does not have a sourceTable or a staticDataSupplier (exactly 1 is required).");
+                     hasASource = true;
+                     validateSimpleCodeReference(dataSourceErrorPrefix, dataSource.getCustomRecordSource(), ReportCustomRecordSourceInterface.class);
                   }
+
+                  assertCondition(hasASource, dataSourceErrorPrefix + "does not have a sourceTable, customRecordSource, or a staticDataSupplier.");
                }
             }
 
@@ -1937,78 +2018,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 ->
             {
-               ////////////////////////////////////////////////////////////////////////////////////////////////
-               // 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())
+               assertCondition(!StringUtils.hasContent(possibleValueSource.getTableName()), "enum-type possibleValueSource " + name + " should not have a tableName.");
+               assertCondition(!CollectionUtils.nullSafeHasContents(possibleValueSource.getSearchFields()), "enum-type possibleValueSource " + name + " should not have searchFields.");
+               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.");
+
+               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 ->
-                  {
-                     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());
+                  tableMetaData = qInstance.getTable(possibleValueSource.getTableName());
+                  assertCondition(tableMetaData != null, "Unrecognized table " + possibleValueSource.getTableName() + " for possibleValueSource " + name + ".");
                }
 
-               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/instances/loaders/AbstractMetaDataLoader.java

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/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();
 
-   /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-   // maybe, remove this altogether - just let the frontend compute & send if needed... but how does it know last version...? //
-   /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-   private List<QFrontendStepMetaData> updatedFrontendStepList = null;
+   private ProcessMetaDataAdjustment processMetaDataAdjustment = 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();
-
-      //////////////////////////////////////////////////////////////////////////////////////////////////////////////
-      // 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()))
+      boolean haveAllAccessKey = hasAllAccessKey(recordSecurityLock);
+      if(haveAllAccessKey)
       {
-         //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-         // 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))
+         if(sourceQueryJoin != null)
          {
-            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)
-            {
-               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-               // 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 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;
-            }
+         ////////////////////////////////////////////////////////////////////////////////////////
+         // 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/QFilterCriteria.java

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

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

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

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

@@ -36,6 +36,7 @@ import com.kingsrook.qqq.backend.core.instances.QMetaDataVariableInterpreter;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.AbstractFilterExpression;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.expressions.FilterVariableExpression;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
@@ -45,7 +46,7 @@ import com.kingsrook.qqq.backend.core.utils.ValueUtils;
  * Full "filter" for a query - a list of criteria and order-bys
  *
  *******************************************************************************/
-public class QQueryFilter implements Serializable, Cloneable
+public class QQueryFilter implements Serializable, Cloneable, QMetaDataObject
 {
    private static final QLogger LOG = QLogger.getLogger(QQueryFilter.class);
 
@@ -55,6 +56,16 @@ public class QQueryFilter implements Serializable, Cloneable
    private BooleanOperator    booleanOperator = BooleanOperator.AND;
    private List<QQueryFilter> subFilters      = new ArrayList<>();
 
+   //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   // initial intent here was - put, e.g., UNION between multiple SELECT (with the individual selects being defined in subFilters) //
+   // but, actually SQL would let us do, e.g., SELECT UNION SELECT INTERSECT SELECT                                                //
+   // so - we could see a future implementation where we:                                                                          //
+   // - used the top-level subFilterSetOperator to indicate hat we are doing a multi-query set-operation query.                    //
+   // - looked within the subFilter, to see if it specified a subFilterSetOperator - and use that operator before that query       //
+   // but - in v0, just using the one at the top-level works                                                                       //
+   //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   private SubFilterSetOperator subFilterSetOperator = null;
+
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // skip & limit are meant to only apply to QueryAction (at least at the initial time they are added here) //
    // e.g., they are ignored in CountAction, AggregateAction, etc, where their meanings may be less obvious  //
@@ -75,6 +86,19 @@ public class QQueryFilter implements Serializable, Cloneable
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public enum SubFilterSetOperator
+   {
+      UNION,
+      UNION_ALL,
+      INTERSECT,
+      EXCEPT
+   }
+
+
+
    /*******************************************************************************
     ** Constructor
     **
@@ -528,8 +552,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 +588,9 @@ public class QQueryFilter implements Serializable, Cloneable
             {
                try
                {
+                  Serializable interpretedValue = value;
+                  Exception    caughtException  = null;
+
                   if(value instanceof AbstractFilterExpression<?>)
                   {
                      ///////////////////////////////////////////////////////////////////////
@@ -553,17 +599,54 @@ public class QQueryFilter implements Serializable, Cloneable
                      ///////////////////////////////////////////////////////////////////////
                      if(value instanceof FilterVariableExpression filterVariableExpression)
                      {
-                        newValues.add(filterVariableExpression.evaluateInputValues(inputValues));
-                     }
-                     else
-                     {
-                        newValues.add(value);
+                        try
+                        {
+                           interpretedValue = filterVariableExpression.evaluateInputValues(inputValues);
+                        }
+                        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 +669,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 +799,59 @@ 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()
+      {
+
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Getter for subFilterSetOperator
+    *******************************************************************************/
+   public SubFilterSetOperator getSubFilterSetOperator()
+   {
+      return (this.subFilterSetOperator);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for subFilterSetOperator
+    *******************************************************************************/
+   public void setSubFilterSetOperator(SubFilterSetOperator subFilterSetOperator)
+   {
+      this.subFilterSetOperator = subFilterSetOperator;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for subFilterSetOperator
+    *******************************************************************************/
+   public QQueryFilter withSubFilterSetOperator(SubFilterSetOperator subFilterSetOperator)
+   {
+      this.subFilterSetOperator = subFilterSetOperator;
+      return (this);
+   }
+
+
 }

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

@@ -66,6 +66,14 @@ public class QueryInput extends AbstractTableActionInput implements QueryOrGetIn
    private List<QueryJoin> queryJoins     = null;
    private boolean         selectDistinct = false;
 
+   /////////////////////////////////////////////////////////////////////////////
+   // if this set is null, then the default (all fields) should be included   //
+   // if it's an empty set, that should throw an error                        //
+   // or if there are any fields in it that aren't valid fields on the table, //
+   // or in a selected queryJoin.                                             //
+   /////////////////////////////////////////////////////////////////////////////
+   private Set<String> fieldNamesToInclude;
+
    ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // if you say you want to includeAssociations, you can limit which ones by passing them in associationNamesToInclude. //
    // if you leave it null, you get all associations defined on the table.  if you pass it as empty, you get none.       //
@@ -686,4 +694,35 @@ public class QueryInput extends AbstractTableActionInput implements QueryOrGetIn
       return (queryHints.contains(queryHint));
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for fieldNamesToInclude
+    *******************************************************************************/
+   public Set<String> getFieldNamesToInclude()
+   {
+      return (this.fieldNamesToInclude);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for fieldNamesToInclude
+    *******************************************************************************/
+   public void setFieldNamesToInclude(Set<String> fieldNamesToInclude)
+   {
+      this.fieldNamesToInclude = fieldNamesToInclude;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fieldNamesToInclude
+    *******************************************************************************/
+   public QueryInput withFieldNamesToInclude(Set<String> fieldNamesToInclude)
+   {
+      this.fieldNamesToInclude = fieldNamesToInclude;
+      return (this);
+   }
+
 }

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("auditId", QFieldType.INTEGER).withPossibleValueSourceName(TABLE_NAME_AUDIT))
+         .withField(new QFieldMetaData("id", QFieldType.LONG))
+         .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 AlertType alertType;
+   private String       html;
+   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,14 @@ 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 isInProcess       = false;
 
    private boolean                   canAddChildRecord = false;
    private Map<String, Serializable> defaultValuesForNewChildRecords;
@@ -352,4 +357,173 @@ 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);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for isInProcess
+    *******************************************************************************/
+   public Boolean getIsInProcess()
+   {
+      return (this.isInProcess);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for isInProcess
+    *******************************************************************************/
+   public void setIsInProcess(Boolean isInProcess)
+   {
+      this.isInProcess = isInProcess;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for isInProcess
+    *******************************************************************************/
+   public ChildRecordListData withIsInProcess(Boolean isInProcess)
+   {
+      this.isInProcess = isInProcess;
+      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 Placement placement = Placement.BOTTOM;
+   private CompositeWidgetData blockData;
+   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,12 +22,9 @@
 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
+ ** MetaDataProducerHelper, to point at a package full of these, and populate
  ** your whole QInstance.
  *******************************************************************************/
 public abstract class MetaDataProducer<T extends MetaDataProducerOutput> implements MetaDataProducerInterface<T>

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

@@ -22,22 +22,33 @@
 package com.kingsrook.qqq.backend.core.model.metadata;
 
 
-import java.io.IOException;
 import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
 import java.lang.reflect.Modifier;
 import java.util.ArrayList;
 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.data.QField;
+import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
 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.model.metadata.possiblevalues.PossibleValueEnum;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.ChildJoinFromRecordEntityGenericMetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.ChildRecordListWidgetFromRecordEntityGenericMetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.PossibleValueSourceOfEnumGenericMetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.PossibleValueSourceOfTableGenericMetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildRecordListWidget;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildTable;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingEntity;
+import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingPossibleValueEnum;
+import com.kingsrook.qqq.backend.core.utils.ClassPathUtils;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
@@ -51,8 +62,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 +96,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)
       {
@@ -95,6 +104,9 @@ public class MetaDataProducerHelper
       }
       List<MetaDataProducerInterface<?>> producers = new ArrayList<>();
 
+      ////////////////////////////////////////////////////////////////////////////////////////
+      // loop over classes, processing them based on either their type or their annotations //
+      ////////////////////////////////////////////////////////////////////////////////////////
       for(Class<?> aClass : classesInPackage)
       {
          try
@@ -106,23 +118,27 @@ public class MetaDataProducerHelper
 
             if(MetaDataProducerInterface.class.isAssignableFrom(aClass))
             {
-               boolean foundValidConstructor = false;
-               for(Constructor<?> constructor : aClass.getConstructors())
-               {
-                  if(constructor.getParameterCount() == 0)
-                  {
-                     Object o = constructor.newInstance();
-                     producers.add((MetaDataProducerInterface<?>) o);
-                     foundValidConstructor = true;
-                     break;
-                  }
-               }
+               CollectionUtils.addIfNotNull(producers, processMetaDataProducer(aClass));
+            }
 
-               if(!foundValidConstructor)
+            if(aClass.isAnnotationPresent(QMetaDataProducingEntity.class))
+            {
+               QMetaDataProducingEntity qMetaDataProducingEntity = aClass.getAnnotation(QMetaDataProducingEntity.class);
+               if(qMetaDataProducingEntity.producePossibleValueSource())
                {
-                  LOG.warn("Found a class which implements MetaDataProducerInterface, but it does not have a no-arg constructor, so it cannot be used.", logPair("class", aClass.getSimpleName()));
+                  producers.addAll(processMetaDataProducingEntity(aClass));
                }
             }
+
+            if(aClass.isAnnotationPresent(QMetaDataProducingPossibleValueEnum.class))
+            {
+               QMetaDataProducingPossibleValueEnum qMetaDataProducingPossibleValueEnum = aClass.getAnnotation(QMetaDataProducingPossibleValueEnum.class);
+               if(qMetaDataProducingPossibleValueEnum.producePossibleValueSource())
+               {
+                  CollectionUtils.addIfNotNull(producers, processMetaDataProducingPossibleValueEnum(aClass));
+               }
+            }
+
          }
          catch(Exception e)
          {
@@ -173,54 +189,176 @@ public class MetaDataProducerHelper
             LOG.debug("Not using producer which is not enabled", logPair("producer", producer.getClass().getSimpleName()));
          }
       }
-
    }
 
 
 
-   /*******************************************************************************
-    ** 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
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @SuppressWarnings("unchecked")
+   private static <T extends PossibleValueEnum<T>> MetaDataProducerInterface<?> processMetaDataProducingPossibleValueEnum(Class<?> aClass)
    {
-      List<Class<?>> classes = new ArrayList<>();
-      ClassLoader    loader  = Thread.currentThread().getContextClassLoader();
-
-      for(ClassPath.ClassInfo info : getTopLevelClasses(loader))
+      String warningPrefix = "Found a class annotated as @" + QMetaDataProducingPossibleValueEnum.class.getSimpleName();
+      if(!PossibleValueEnum.class.isAssignableFrom(aClass))
       {
-         if(info.getName().startsWith(packageName))
+         LOG.warn(warningPrefix + ", but which is not a " + PossibleValueEnum.class.getSimpleName() + ", so it will not be used.", logPair("class", aClass.getSimpleName()));
+         return null;
+      }
+
+      PossibleValueEnum<?>[] values = (PossibleValueEnum<?>[]) aClass.getEnumConstants();
+      return (new PossibleValueSourceOfEnumGenericMetaDataProducer<T>(aClass.getSimpleName(), (PossibleValueEnum<T>[]) values));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static List<MetaDataProducerInterface<?>> processMetaDataProducingEntity(Class<?> aClass) throws Exception
+   {
+      List<MetaDataProducerInterface<?>> rs = new ArrayList<>();
+
+      String warningPrefix = "Found a class annotated as @" + QMetaDataProducingEntity.class.getSimpleName();
+      if(!QRecordEntity.class.isAssignableFrom(aClass))
+      {
+         LOG.warn(warningPrefix + ", but which is not a " + QRecordEntity.class.getSimpleName() + ", so it will not be used.", logPair("class", aClass.getSimpleName()));
+         return (rs);
+      }
+
+      Field tableNameField = aClass.getDeclaredField("TABLE_NAME");
+      if(!tableNameField.getType().equals(String.class))
+      {
+         LOG.warn(warningPrefix + ", but whose TABLE_NAME field is not a String, so it will not be used.", logPair("class", aClass.getSimpleName()));
+         return (rs);
+      }
+
+      String tableNameValue = (String) tableNameField.get(null);
+      rs.add(new PossibleValueSourceOfTableGenericMetaDataProducer(tableNameValue));
+
+      //////////////////////////
+      // process child tables //
+      //////////////////////////
+      QMetaDataProducingEntity qMetaDataProducingEntity = aClass.getAnnotation(QMetaDataProducingEntity.class);
+      for(ChildTable childTable : qMetaDataProducingEntity.childTables())
+      {
+         Class<? extends QRecordEntity> childEntityClass = childTable.childTableEntityClass();
+         if(childTable.childJoin().enabled())
          {
-            classes.add(info.load());
+            CollectionUtils.addIfNotNull(rs, processChildJoin(aClass, childTable));
+
+            if(childTable.childRecordListWidget().enabled())
+            {
+               CollectionUtils.addIfNotNull(rs, processChildRecordListWidget(aClass, childTable));
+            }
+         }
+         else
+         {
+            if(childTable.childRecordListWidget().enabled())
+            {
+               //////////////////////////////////////////////////////////////////////////
+               // if not doing the join, can't do the child-widget, so warn about that //
+               //////////////////////////////////////////////////////////////////////////
+               LOG.warn(warningPrefix + " requested to produce a ChildRecordListWidget, but not produce a Join - which is not allowed (must do join to do widget). ", logPair("class", aClass.getSimpleName()), logPair("childEntityClass", childEntityClass.getSimpleName()));
+            }
          }
       }
 
-      return (classes);
+      return (rs);
    }
 
 
 
-   /*******************************************************************************
+   /***************************************************************************
     **
-    *******************************************************************************/
-   private static ImmutableSet<ClassPath.ClassInfo> getTopLevelClasses(ClassLoader loader) throws IOException
+    ***************************************************************************/
+   private static MetaDataProducerInterface<?> processChildRecordListWidget(Class<?> aClass, ChildTable childTable) throws Exception
    {
-      if(topLevelClasses == null)
+      Class<? extends QRecordEntity> childEntityClass = childTable.childTableEntityClass();
+      String                         parentTableName  = getTableNameStaticFieldValue(aClass);
+      String                         childTableName   = getTableNameStaticFieldValue(childEntityClass);
+
+      ChildRecordListWidget childRecordListWidget = childTable.childRecordListWidget();
+      return (new ChildRecordListWidgetFromRecordEntityGenericMetaDataProducer(childTableName, parentTableName, childRecordListWidget));
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static String findPossibleValueField(Class<? extends QRecordEntity> entityClass, String possibleValueSourceName)
+   {
+      for(Field field : entityClass.getDeclaredFields())
       {
-         topLevelClasses = ClassPath.from(loader).getTopLevelClasses();
+         if(field.isAnnotationPresent(QField.class))
+         {
+            QField qField = field.getAnnotation(QField.class);
+            if(qField.possibleValueSourceName().equals(possibleValueSourceName))
+            {
+               return field.getName();
+            }
+         }
       }
 
-      return (topLevelClasses);
+      return (null);
    }
 
 
 
-   /*******************************************************************************
+   /***************************************************************************
     **
-    *******************************************************************************/
-   public static void clearTopLevelClassCache()
+    ***************************************************************************/
+   private static MetaDataProducerInterface<?> processChildJoin(Class<?> aClass, ChildTable childTable) throws Exception
    {
-      topLevelClasses = null;
+      Class<? extends QRecordEntity> childEntityClass = childTable.childTableEntityClass();
+
+      String parentTableName        = getTableNameStaticFieldValue(aClass);
+      String childTableName         = getTableNameStaticFieldValue(childEntityClass);
+      String possibleValueFieldName = findPossibleValueField(childEntityClass, parentTableName);
+      if(!StringUtils.hasContent(possibleValueFieldName))
+      {
+         LOG.warn("Could not find field in [" + childEntityClass.getSimpleName() + "] with possibleValueSource referencing table [" + aClass.getSimpleName() + "]");
+         return (null);
+      }
+
+      return (new ChildJoinFromRecordEntityGenericMetaDataProducer(childTableName, parentTableName, possibleValueFieldName));
    }
 
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static MetaDataProducerInterface<?> processMetaDataProducer(Class<?> aClass) throws Exception
+   {
+      for(Constructor<?> constructor : aClass.getConstructors())
+      {
+         if(constructor.getParameterCount() == 0)
+         {
+            Object o = constructor.newInstance();
+            return (MetaDataProducerInterface<?>) o;
+         }
+      }
+
+      LOG.warn("Found a class which implements MetaDataProducerInterface, but it does not have a no-arg constructor, so it cannot be used.", logPair("class", aClass.getSimpleName()));
+      return null;
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static String getTableNameStaticFieldValue(Class<?> aClass) throws NoSuchFieldException, IllegalAccessException
+   {
+      Field tableNameField = aClass.getDeclaredField("TABLE_NAME");
+      if(!tableNameField.getType().equals(String.class))
+      {
+         return (null);
+      }
+
+      String tableNameValue = (String) tableNameField.get(null);
+      return (tableNameValue);
+   }
 }

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,22 +19,20 @@
  * 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;
 
 
 /*******************************************************************************
  ** Interface for classes that know how to produce meta data objects.  Useful with
- ** MetaDataProducerHelper, to put point at a package full of these, and populate
+ ** MetaDataProducerHelper, to point at a package full of these, and populate
  ** your whole QInstance.
  **
  ** See also MetaDataProducer - an implementer of this interface, which actually
  ** came first, and is fine to extend if producing a meta-data class is all your
- ** clas means to do (nice and "Single-responsibility principle").
+ ** class means to do (nice and "Single-responsibility principle").
  **
  ** But, in some applications you may want to, for example, have one class that
  ** defines a process step, and also produces the meta-data for that process, so

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... //
@@ -1242,7 +1245,7 @@ public class QInstance
       {
          this.supplementalMetaData = new HashMap<>();
       }
-      this.supplementalMetaData.put(supplementalMetaData.getType(), supplementalMetaData);
+      this.supplementalMetaData.put(supplementalMetaData.getName(), supplementalMetaData);
       return (this);
    }
 
@@ -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/QMetaDataObject.java

@@ -0,0 +1,34 @@
+/*
+ * 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;
+
+
+import java.io.Serializable;
+
+
+/*******************************************************************************
+ ** interface common among all objects that can be considered qqq meta data -
+ ** e.g., stored in a QInstance.
+ *******************************************************************************/
+public interface QMetaDataObject extends Serializable
+{
+}

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

@@ -22,6 +22,7 @@
 package com.kingsrook.qqq.backend.core.model.metadata;
 
 
+import java.util.function.Supplier;
 import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 
@@ -30,20 +31,13 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
  ** Base-class for instance-level meta-data defined by some supplemental module, etc,
  ** outside of qqq core
  *******************************************************************************/
-public abstract class QSupplementalInstanceMetaData implements TopLevelMetaDataInterface
+public interface QSupplementalInstanceMetaData extends TopLevelMetaDataInterface
 {
 
-   /*******************************************************************************
-    ** Getter for type
-    *******************************************************************************/
-   public abstract String getType();
-
-
-
    /*******************************************************************************
     **
     *******************************************************************************/
-   public void enrich(QTableMetaData table)
+   default void enrich(QTableMetaData table)
    {
       ////////////////////////
       // noop in base class //
@@ -55,7 +49,7 @@ public abstract class QSupplementalInstanceMetaData implements TopLevelMetaDataI
    /*******************************************************************************
     **
     *******************************************************************************/
-   public void validate(QInstance qInstance, QInstanceValidator validator)
+   default void validate(QInstance qInstance, QInstanceValidator validator)
    {
       ////////////////////////
       // noop in base class //
@@ -68,9 +62,33 @@ public abstract class QSupplementalInstanceMetaData implements TopLevelMetaDataI
     **
     *******************************************************************************/
    @Override
-   public void addSelfToInstance(QInstance qInstance)
+   default void addSelfToInstance(QInstance qInstance)
    {
       qInstance.withSupplementalMetaData(this);
    }
 
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static <S extends QSupplementalInstanceMetaData> S of(QInstance qInstance, String name)
+   {
+      return ((S) qInstance.getSupplementalMetaData(name));
+   }
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static <S extends QSupplementalInstanceMetaData> S ofOrWithNew(QInstance qInstance, String name, Supplier<S> supplier)
+   {
+      S s = (S) qInstance.getSupplementalMetaData(name);
+      if(s == null)
+      {
+         s = supplier.get();
+         s.addSelfToInstance(qInstance);
+      }
+      return (s);
+   }
+
 }

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

@@ -26,7 +26,7 @@ package com.kingsrook.qqq.backend.core.model.metadata;
  ** Interface for meta-data classes that can be added directly (e.g, at the top
  ** level) to a QInstance (such as a QTableMetaData - not a QFieldMetaData).
  *******************************************************************************/
-public interface TopLevelMetaDataInterface extends MetaDataProducerOutput
+public interface TopLevelMetaDataInterface extends MetaDataProducerOutput, QMetaDataObject
 {
 
    /*******************************************************************************

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

@@ -22,10 +22,13 @@
 package com.kingsrook.qqq.backend.core.model.metadata.audits;
 
 
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
+
+
 /*******************************************************************************
  **
  *******************************************************************************/
-public class QAuditRules
+public class QAuditRules implements QMetaDataObject
 {
    private AuditLevel auditLevel;
 

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/QCodeReference.java

@@ -23,13 +23,14 @@ package com.kingsrook.qqq.backend.core.model.metadata.code;
 
 
 import java.io.Serializable;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
 
 
 /*******************************************************************************
  ** Pointer to code to be ran by the qqq framework, e.g., for custom behavior -
  ** maybe process steps, maybe customization to a table, etc.
  *******************************************************************************/
-public class QCodeReference implements Serializable
+public class QCodeReference implements Serializable, QMetaDataObject
 {
    private String    name;
    private QCodeType codeType;

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/AdornmentType.java

@@ -68,6 +68,9 @@ public enum AdornmentType
       String DEFAULT_EXTENSION = "defaultExtension";
       String DEFAULT_MIME_TYPE = "defaultMimeType";
 
+      String SUPPLEMENTAL_PROCESS_NAME   = "supplementalProcessName";
+      String SUPPLEMENTAL_CODE_REFERENCE = "supplementalCodeReference";
+
       ////////////////////////////////////////////////////
       // use these two together, as in:                 //
       // FILE_NAME_FORMAT = "Order %s Packing Slip.pdf" //

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

@@ -40,8 +40,10 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.data.QField;
 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.QMetaDataObject;
 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;
@@ -53,7 +55,7 @@ import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
  ** Meta-data to represent a single field in a table.
  **
  *******************************************************************************/
-public class QFieldMetaData implements Cloneable
+public class QFieldMetaData implements Cloneable, QMetaDataObject
 {
    private static final QLogger LOG = QLogger.getLogger(QFieldMetaData.class);
 
@@ -73,10 +75,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 +1062,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/fields/QFieldType.java

@@ -120,6 +120,16 @@ public enum QFieldType
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public boolean isTemporal()
+   {
+      return this == QFieldType.DATE || this == QFieldType.DATE_TIME || this == QFieldType.TIME;
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/

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();
-
-      if(appMetaData.getIcon() != null)
-      {
-         this.iconName = appMetaData.getIcon().getName();
-      }
+      this.icon = appMetaData.getIcon();
 
       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;
-   }
-
-
-
-   /*******************************************************************************
-    ** Setter for iconName
-    **
-    *******************************************************************************/
-   public void setIconName(String iconName)
-   {
-      this.iconName = iconName;
+      return (icon == null ? null : icon.getName());
    }
 
 
@@ -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()
-               .filter(QFrontendStepMetaData.class::isInstance)
-               .map(QFrontendStepMetaData.class::cast)
-               .collect(Collectors.toList());
+            this.frontendSteps = switch(processMetaData.getStepFlow())
+            {
+               case LINEAR -> processMetaData.getStepList().stream()
+                  .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.iconName = processMetaData.getIcon().getName();
-      }
+      this.icon = processMetaData.getIcon();
 
       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.iconName = tableMetaData.getIcon().getName();
-      }
+      this.icon = tableMetaData.getIcon();
 
       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/help/QHelpContent.java

@@ -25,6 +25,7 @@ package com.kingsrook.qqq.backend.core.model.metadata.help;
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
 
 
 /*******************************************************************************
@@ -41,7 +42,7 @@ import java.util.Set;
  ** May be dynamically added to meta-data via (non-meta-) data - see
  ** HelpContentMetaDataProvider and QInstanceHelpContentManager
  *******************************************************************************/
-public class QHelpContent
+public class QHelpContent implements QMetaDataObject
 {
    private String        content;
    private HelpFormat    format;

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

@@ -22,11 +22,14 @@
 package com.kingsrook.qqq.backend.core.model.metadata.layout;
 
 
+import com.kingsrook.qqq.backend.core.model.metadata.QMetaDataObject;
+
+
 /*******************************************************************************
  ** Interface shared by meta-data objects which can be placed into an App.
  ** e.g., Tables, Processes, and Apps themselves (since they can be nested)
  *******************************************************************************/
-public interface QAppChildMetaData
+public interface QAppChildMetaData extends QMetaDataObject
 {
    /*******************************************************************************
     **